| name | audit-skill |
| description | Audit an existing SKILL.md against agentskills.io best practices. Use when user wants to review, audit, or improve a skill's quality — checking scope, context efficiency, instruction calibration, and effective patterns. Designed to feed findings into skill-creator for iteration. |
Skill Auditor
Audit a SKILL.md against agentskills.io best practices and produce structured findings ready for skill-creator iteration.
Process
- Ask for the skill path if not provided
- Read
SKILL.md and any referenced files in the skill folder
- Audit against each dimension below
- Report findings, then ask: "Want to iterate on this with skill-creator?"
Audit Dimensions
1. Grounded in real expertise
- Instructions are specific: names actual APIs, schemas, edge cases, conventions
- No generic filler ("handle errors appropriately", "follow best practices")
2. Context window efficiency
- Adds what the agent lacks; omits what it already knows
- No over-explanation of common concepts (HTTP, PDFs, migrations, etc.)
SKILL.md under 500 lines / 5 000 tokens- Large reference material moved to
references/ with conditional load triggers
3. Scope coherence
- Covers one coherent unit of work
- Not too narrow (would force multiple skills per task)
- Not too broad (hard to trigger precisely)
4. Instruction calibration
- Flexible where variation is acceptable — explains why rather than rigid steps
- Prescriptive only for fragile, sequential, or destructive operations
- One clear default per choice; alternatives mentioned briefly, not as equal menus
5. Procedures over declarations
- Teaches how to approach a class of problems, not what to produce for a specific instance
- Reusable method that generalizes across inputs
6. Effective patterns (check which are present and warranted)
- Gotchas — non-obvious environment-specific facts (wrong field names, soft deletes, misleading endpoints)
- Output templates — concrete template when format must be exact
- Checklists — step-by-step with checkboxes for workflows with dependencies or gates
- Validation loops — agent runs validator, fixes issues, repeats until passing
- Plan-validate-execute — for batch/destructive ops: structured plan → validation script → execution
7. Progressive disclosure
- Heavy content in separate files under
references/ or assets/
- Each external file linked with a conditional trigger, not a generic "see references/"
Output Format
Report per dimension:
| Dimension | Status | Finding | Fix |
|---|
| Grounded | OK / ⚠ / ✗ | … | … |
End with Top 3 priority changes ordered by impact.
Then ask the user whether to hand off to skill-creator for iteration.
Gotchas
- A skill that passes all dimensions may still not be valuable — if the agent already handles the task without it, the skill adds noise. Flag this if it seems likely.
- Don't penalize brevity. A 20-line skill can be excellent if it's specific and grounded.
- Progressive disclosure is only relevant for skills that legitimately need more content; don't suggest splitting a short skill.
