| name | skill-review-expert |
| description | Review a Claude Code skill file for correctness, clarity, and compliance with Claude prompting guidelines and skill authoring best practices. Use when editing, auditing, or creating skills. |
Skill Review Expert
Review a skill file against Claude's prompting guidelines and skill authoring best practices. Produces structured findings grouped by severity.
Scope: This review covers the skill file's text — structure, clarity, consistency, and compliance. It does not verify referenced tool behavior or runtime agent compliance.
Workflow
- Read the target skill file
- Run the automated scans (see Tooling section)
- Run each check category below, using scan results as evidence
- Report findings grouped by severity (Critical > Important > Suggestion)
- For each finding: state the problem, cite the violated check ID, show a concrete fix
Authority hierarchy: Claude platform docs > skill authoring best practices > reviewer opinion. When uncertain, check Context7 (/websites/platform_claude_en) for the canonical answer.
Failure modes:
- File has no frontmatter → treat as unstructured skill, flag under B2
- File is not a skill (no actionable instructions) → report and stop
- Context7 unreachable → proceed using cached knowledge, note in report
Tooling (run first)
Automated scans provide evidence for checks A1, B5, D3, and D4. Set the target path, then run all four:
SKILL_FILE="path/to/skill.md"
grep -n "Don't\|Do not\|Do NOT\|Never\|Avoid\|don't" "$SKILL_FILE"
grep -n '\\\\' "$SKILL_FILE"
grep -n -i 'see \|above\|below\|described in' "$SKILL_FILE"
grep -o -i '\b\(finding\|issue\|result\|problem\|check\)\b' "$SKILL_FILE" | sort | uniq -c | sort -rn
Check Categories
A. Prompting Compliance (Claude platform docs)
Source: https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices
| # | Check | What to look for |
|---|
| A1 | Positive framing | Instructions phrased as what TO do. Flag every "Don't", "Never", "Avoid" that can be reframed. Example: "Use tp for real bugs" instead of "Don't use wontfix". |
| A2 | Clear and direct | Imperative, unambiguous, specific. Flag hedging ("you might want to", "consider", "it may be useful"). Example: "Run cargo test" passes; "You could try running tests" fails. |
| A3 | Concrete examples | Every non-trivial instruction has a code block, command, or worked example. Flag abstract rules with no example. |
| A4 | Structured with markup | Headers, tables, and code blocks for scannability. Flag walls of prose (>5 sentences without a break), deeply nested bullets, or unstructured lists > 5 items. |
| A5 | Consistent instructions | Tables, decision trees, examples, and prose all agree. Flag any case where two sections give different guidance for the same scenario. |
| A6 | Context before instructions | Reference material (what things are) appears before procedural material (what to do with them). Flag instructions that reference concepts defined later. |
B. Skill Authoring Best Practices
Source: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
| # | Check | What to look for |
|---|
| B1 | Concise — skip what Claude knows | Flag definitions of common concepts (what a PR is, what unit tests are). Only include context Claude lacks. Example of waste: "A pull request is a way to propose changes..." |
| B2 | Clear trigger in frontmatter | description field specifies when to activate. Flag vague descriptions ("useful for development"). Example of good: "Use when reviewing code with quorum or recording feedback." |
| B3 | Delegate to deterministic tools | Invoke linters/scripts/CLIs for verifiable checks; reserve LLM reasoning for judgment calls. Flag skills that use LLM reasoning for things grep or a linter could verify. |
| B4 | Reference external truths | Stable rules belong in referenced files (STYLE_GUIDE.md, .eslintrc), not duplicated inline. Flag large rule blocks (>20 lines) that restate a config file. |
| B5 | Unix paths only | All file paths use forward slashes. Flag backslashes. |
| B6 | Actionable output | Every instruction produces a concrete action (a command, a verdict, a file edit). Flag instructions ending with "handle appropriately" or "use good judgment". |
C. LLM Anti-Pattern Guards
Source: observed failure modes in agent workflows
| # | Check | What to look for |
|---|
| C1 | Inline until repeated | Flag instructions that push extraction or DRY before a pattern repeats 3+ times. Example: "Extract a helper for this" when the pattern appears once. |
| C2 | Trust the type system | Flag instructions to add null checks, error handling, or validation for scenarios guaranteed by types or framework contracts. Example: null-checking a non-optional field. |
| C3 | Delegate style to linters | Style/whitespace rules belong in linter config. Flag instructions about indentation, line length, or brace style. Example: "Use 2-space indentation" belongs in .editorconfig. |
| C4 | Remove dead interfaces cleanly | Flag instructions to maintain old exports, re-export removed types, or add deprecation wrappers when all call sites are controlled. Example: keeping a _legacyFoo re-export. |
D. Internal Consistency
| # | Check | What to look for |
|---|
| D1 | Decision tree completeness | Every scenario has exactly one matching path. Flag gaps (no matching row) and overlaps (multiple matching rows). Example: a finding that is both "wrong" and "outside diff" should have a clear resolution order. |
| D2 | Example-prose agreement | Code examples match surrounding text. Flag examples using different flags or patterns than the prose specifies. Example: prose says --verbose but the code block uses -v. |
| D3 | Cross-reference integrity | "See section X" or "described above" points to existing content. Use the grep scan to find all references, verify each. |
| D4 | Terminology consistency | Same concept uses the same term throughout. Use the frequency scan to spot synonyms. Example: "finding" and "issue" used interchangeably for the same concept. |
E. Information Architecture
| # | Check | What to look for |
|---|
| E1 | Happy path first | Most common workflow appears before edge cases and advanced options. Flag skills that lead with configuration. Example: "Configuration" section before "Quick Start" is backwards. |
| E2 | Progressive disclosure | Simple usage before advanced flags. Quick reference before deep explanation. Flag skills that front-load complexity or version history. |
| E3 | Scannable for quick decisions | An agent mid-task can find the answer in <10 seconds. Flag decision logic buried in paragraphs — decision points belong in tables or numbered steps. |
| E4 | Section ordering matches usage flow | Sections follow the order encountered during a task. Flag reference material interleaved with workflow steps. |
F. Agent Compliance Prediction
| # | Check | What to look for |
|---|
| F1 | Unambiguous verdicts | For every decision point, the agent can determine the right action without guessing. Flag cases where the answer depends on unstated context. Example: "use the appropriate model" — appropriate how? |
| F2 | Required vs optional is explicit | Flag ambiguous optionality ("you can also...", "optionally...") for steps that are actually required. Example: "You can run tests" when tests are mandatory. |
| F3 | Failure modes addressed | What happens when a tool fails, a file is missing, or output is unexpected? Flag workflows with no error path. Example: "Run quorum review" with no guidance for when quorum is not installed. |
| F4 | Scope boundaries clear | The skill states what it covers and what it delegates. Flag skills that could cause scope creep. Example: a review skill that starts refactoring code. |
Output Format
## Skill Review: <skill-name>
### Critical (blocks correct agent behavior)
- **[A5]** Conflicting instructions: "Key principles" says use `tp` for out-of-diff bugs,
but "Workflow step 3" says use `fp --fp-kind out-of-scope`.
Fix: Align both to `tp --in-diff false`, which matches calibrator behavior.
### Important (degrades quality or compliance)
- **[A1]** Negative framing: "Don't use wontfix" (line 42)
Fix: "Always choose `tp` or `fp` — `wontfix` is inert."
### Suggestions (polish)
- **[E2]** Configuration section appears before basic usage.
Fix: Move configuration after the workflow section.
### Passing
A2, A3, A4, B1, B2, B5, C1-C4, D1-D4, E1, E3, F1-F4
Evaluation-Driven Iteration
After reviewing, the skill author should:
- Fix all Critical findings — these cause wrong agent behavior
- Fix Important findings — these degrade quality measurably
- Consider Suggestions — these improve polish but may not be worth the churn
- Re-run this review on the updated skill to verify fixes and catch regressions
For calibrating this reviewer: run it on a skill, observe the agent using that skill on a real task, note where the agent makes mistakes. Add a check for each observed failure mode.
