review-skill
Reviews, audits, and scores skill files (SKILL.md) for quality, completeness, frontmatter correctness, discoverability, and anti-patterns. Use when asked to review, audit, check, or improve a skill file, or when a user says "is this skill good?", "check my skill", or pastes a SKILL.md for feedback. Also use proactively after writing a new skill — self-apply as a final quality gate. Don't use for reviewing general Markdown documentation, README files, or code files that are not skill definitions.
- License 许可
- MIT
- 最近更新
- 2026-07-11
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- review-skill
- metadata
- { "version": "1.0" }
- description
- Reviews, audits, and scores skill files (SKILL.md) for quality, completeness, frontmatter correctness, discoverability, and anti-patterns. Use when asked to review, audit, check, or improve a skill file, or when a user says "is this skill good?", "check my skill", or pastes a SKILL.md for feedback. Also use proactively after writing a new skill — self-apply as a final quality gate. Don't use for reviewing general Markdown documentation, README files, or code files that are not skill definitions.
- argument-hint
- Optional: skill name or path. Omit to audit all discovered skills.
03 SKILL.md 正文
Review Skill
Audit SKILL.md files against the Agent Skills specification and produce a scored Markdown report.
Guardrails
- Only review
SKILL.mdfiles — not general Markdown, READMEs, or code. - Collect all discovered skills before reviewing any.
- This skill can review itself as a smoke test.
Step 1: Discovery
If the user provided a specific skill name or path, review only that skill and skip the search below.
Otherwise search every location:
| Priority | Location | Scope |
|---|---|---|
| 1 | skills/ |
repo-level reference skills |
| 2 | .github/skills/ |
GitHub Copilot project skills |
| 3 | .agents/skills/ |
standardized agent skills (preferred) |
| 4 | .claude/skills/ |
Claude agent skills |
| 5 | ~/.copilot/skills/ |
user-level Copilot skills |
| 6 | ~/.agents/skills/ |
user-level agent skills (preferred) |
| 7 | ~/.claude/skills/ |
user-level Claude skills |
A skill is a subfolder containing SKILL.md (preferred) or
SKILLS.md (non-standard — flag it). Loose .md files are not skills.
If the same skill name appears in multiple locations, report the conflict and note which location wins at runtime (higher priority number = lower precedence).
Step 2: Review each skill
Apply every check below. Assign severity: Error (blocks correct function), Warning (degrades quality or discoverability), Info (style suggestion).
File and folder
| Check | Pass condition | Severity if failed |
|---|---|---|
| Skill in named subfolder | Not loose in skills root | Error |
File named SKILL.md |
Exact match, case-sensitive | Warning |
| Folder name format | [a-z0-9-]+ only |
Warning |
Frontmatter
Validate against the Agent Skills specification.
Skills in agent-loaded locations (.agents/, .github/, .copilot/,
.claude/) must have frontmatter. Skills in a root skills/
folder intended as human-readable reference may omit it — note but
don't error.
Errors (block correct function):
- Frontmatter block missing (
---delimiters not found) — Error for agent-loaded, Info for reference skills namedoes not match folder name exactlydescriptionmissing or empty
Warnings (degrade quality):
descriptionunder 20 charsdescriptionlacks searchable trigger phrases- Unknown frontmatter fields (spec allows:
license,compatibility,metadata,allowed-tools)
Info:
- No negative trigger ("Don't use when...") in description
Body content
Errors:
- No numbered, actionable procedure steps
./pathreferences that don't resolve to a file
Warnings:
- Over 500 lines (recommend splitting to
references/) - Absolute paths (
/home/...) instead of./ - Time-sensitive logic (hard-coded dates or version cutoffs)
- Future-tense only — has promises but no current steps
Info:
- Body opens with a "Purpose and contract" section instead of a brief orienting sentence or guardrails
- No guardrails section (if applicable)
- No output contract (if the skill produces artifacts)
Quality and discoverability
- Would this description cause the agent to select the skill for the right tasks?
- Are procedures specific enough to produce consistent output across runs?
- Is bulk content pushed to
references/rather than inline? - Does the argument-hint (if declared) have corresponding branch logic in the procedure?
Step 3: Anti-patterns
Flag if present — these are the most common skill authoring mistakes:
| Anti-Pattern | Explanation |
|---|---|
| Vague description | "A helpful skill" — agent cannot route to it |
| No negative trigger | Adjacent tasks will false-positive |
| Monolithic body | Everything inline; no references/ offload |
| Missing procedure | Preamble only, no actionable steps |
| Unused declared fields | argument-hint in frontmatter, no branch in body |
Step 4: Output
Produce a Markdown report:
# Skill Review Report
## Summary
- Skills found: N
- Locations searched: [list]
- Issues: N errors, N warnings, N info
## Skills Reviewed
### `<folder-name>`
**Location**: `<relative path to SKILL.md>`
**Status**: ✅ Pass / ⚠️ Warnings / ❌ Errors
| Check | Severity | Result | Note |
| ------------------- | -------- | ------ | ----------------------------------- |
| Folder naming | — | ✅ | |
| File name | Warning | ⚠️ | Uses SKILLS.md |
| Frontmatter present | Error | ❌ | No --- block |
| name matches folder | — | N/A | Cannot check (no frontmatter) |
| description quality | Warning | ⚠️ | 12 chars, too short |
| Negative trigger | Info | ℹ️ | Consider adding "Don't use when..." |
| Procedure present | — | ✅ | |
| File length | — | ✅ | 94 lines |
**Recommendations** (ordered by severity):
1. ❌ Add YAML frontmatter with `name` and `description`
2. ⚠️ Rename `SKILLS.md` → `SKILL.md`
3. ⚠️ Expand description to include trigger phrases
4. ℹ️ Add a negative trigger to reduce false positives
---
If only one skill was reviewed (scoped run), omit the Summary section and go straight to the skill block.
04 同仓库更多 Skills
pygta-validate
Run validation across the workspace root and configured external repos with changes.
pygta-project
Scaffold a new pyglotaran analysis project with standard folder structure and starter notebook. Don't use when modifying an existing project or changing the scaffold script itself