| name | checking-skill-quality |
| description | Use when the user says "check this skill", "review this skill", "quality check skill", "audit this skill", "skill quality check", "does this skill follow best practices", or provides a path to a SKILL.md file for review. Also triggers on "check skill quality", "skill review", or "is this skill well-written". Audits a skill file against the AIDB Skills Masterclass best practices framework, checking for the 5 skill killers, proper anatomy, scoping, and context binding.
|
Checking Skill Quality
Context Required
Read the target SKILL.md file before running. If the skill has a folder with supporting
files (templates, examples, scenarios), read those too to assess context binding.
Steps
- Ask for the skill path if not provided
- Read the full SKILL.md at that path — do not skim
- If a skill folder exists, list its contents and read any supporting files
- Check the frontmatter:
- Name: lowercase, hyphens only, max 64 chars, gerund form (verb-ing)?
- Description: starts with "Use when..."? Lists trigger phrases? Written in third person? Loud and specific?
- Check for the 5 Skill Killers:
- Killer 1 — Vague/quiet description: Is it specific, loud, third-person, with "Use when..." format and edge-case triggers?
- Killer 2 — Over-defined process: Is freedom matched to task fragility? Tight for fragile ops, loose for creative?
- Killer 3 — Stating the obvious: Does every paragraph add signal the model doesn't already know? Challenge each section.
- Killer 4 — Missing gotcha section: Is there a dedicated Gotcha Section with documented failure patterns specific to this skill?
- Killer 5 — Monolithic blob: Is the SKILL.md under 500 lines?
- Check skill anatomy completeness and quality:
- Steps: numbered list (not prose)?
- Output: literal template/example shown (not just described)?
- Gotcha Section: present and substantive — not empty, not generic?
- Constraints: sharp and specific to this skill (not generic model behavior)?
- Identity/role section: absent? Flag explicitly if present — "Act as a senior X" is always an anti-pattern
- Check scoping:
- Can you describe the skill's job in one sentence?
- Does it have two distinct triggers suggesting it should be two skills?
- Would two different people use different halves of it?
- Check context binding:
- Are files specific to this skill in the folder?
- Are shared/org-level references pointed to externally (not duplicated)?
- Is any context that should be external being embedded inline?
- Classify the skill type:
- Capability Uplift: new function the model can't do well alone — note it may become obsolete as models improve
- Encoded Preference: your workflow for something the model can do — note it gets more valuable over time
- Generate the audit report per the output format below
Output
Skill Quality Audit: [skill-name]
Type: Capability Uplift / Encoded Preference
Overall verdict: SOLID / NEEDS WORK / RED FLAG
5 Skill Killers Check
| # | Killer | Status | Notes |
|---|
| 1 | Vague/quiet description | PASS / FAIL | [specifics] |
| 2 | Over-defined process | PASS / FAIL | [specifics] |
| 3 | Stating the obvious | PASS / FAIL | [specifics] |
| 4 | Missing gotcha section | PASS / FAIL | [specifics] |
| 5 | Monolithic blob | PASS / FAIL | [line count] |
Anatomy Check
| Section | Present | Quality | Notes |
|---|
| Name (gerund, hyphens, ≤64 chars) | Yes/No | Good/Weak/N/A | |
| Description (trigger, loud, 3rd person) | Yes/No | Good/Weak | |
| Context Required | Yes/No | Good/Weak/N/A | |
| Steps (numbered, not prose) | Yes/No | Good/Weak | |
| Output (literal template shown) | Yes/No | Good/Weak | |
| Gotcha Section (substantive) | Yes/No | Good/Weak | |
| Constraints | Yes/No | Good/Weak/N/A | |
| Identity/role section (should be ABSENT) | Absent/Present | — | Flag if present |
Scoping
- One clear job: [yes/no + one-sentence description of the job]
- Split candidate: [yes/no + reason if yes]
Context Binding
- In-folder files: [list, or "none"]
- External references: [list, or "none"]
- Misplaced context: [yes/no + specifics if yes]
Top Recommended Improvements
- [Most impactful fix — be specific, not generic]
- [Second fix]
- [Third fix, if applicable]
Litmus Test
After this skill runs, can the output be used directly — or will it need editing and restructuring? [honest assessment based on how precise the steps and output format are]
Gotcha Section
- Do not mark a skill SOLID just because all sections are present — check the QUALITY of each section, not just presence
- A description that lists trigger phrases but is vague about what the skill does still fails Killer 1
- The Gotcha Section is the highest-signal content in any skill — missing or generic gotcha content is always at least NEEDS WORK
- Do not flag prose in Steps as automatic fail if the prose is tight and directive — the problem is prose that hides ambiguity or gives the model too much latitude on fragile operations
- A Capability Uplift skill should be noted as potentially obsolete if a recent model improvement may have addressed the gap it fills
- The litmus test is not rhetorical — actually assess whether the output format and step precision would produce directly usable output
- If supporting files exist but are not referenced in the SKILL.md, flag the disconnect
- Do not skip the scoping check — skills that try to do two jobs are a common failure mode that the rest of the audit misses
Constraints
- Read the entire skill file before issuing any verdict
- Overall verdict rules:
- RED FLAG: any Killer scores FAIL and the fix is non-trivial, or an identity/role section is present
- NEEDS WORK: one or more Killers fail but fixes are minor, or anatomy sections are weak
- SOLID: all 5 Killers pass and anatomy is complete and high-quality
- Do not soften verdicts to be encouraging — the point is to surface real issues
- Flag identity/role sections ("Act as a...") explicitly every time — no exceptions
