A free Claude skill that audits, builds and improves other skills against Anthropic's own skill-writing rules, including what changed for the newest Claude models.
Point it at a skill (or a whole folder of skills) and it gives you a findings report first: every rule marked pass, fail or not applicable, with the file and line as evidence and a proposed fix. It changes nothing until you say which fixes to apply.
A skill is a folder with a SKILL.md file that teaches Claude how to do a job the same way each time. Anthropic publishes clear rules for writing them, and it is easy to break several without noticing: descriptions that never trigger, reference files Claude only half reads, rules buried where compaction cuts them.
The core rules on Anthropic's skill authoring page have been stable for about a year. What changed is the models:
- The prompting guide for Claude Fable 5 says skills written for older models are often too prescriptive and can make output worse. Review them and remove what the model now does better on its own, but test before you delete.
- The guides for Fable 5, Opus 5.5 and Sonnet 5.5 all list a
reasoning_extractionrefusal: asking Claude to write out its reasoning in the reply can be declined. A short explanation of the answer is fine. - The Fable 5 guide also says to give the reason, not only the request, to steer with brief instructions instead of long lists, and to make checking explicit, preferring a fresh Claude as the checker over self-review.
Claude Code adds its own: put the most important instructions at the top of SKILL.md (compaction keeps only the first 5,000 tokens), and move any rule that has to hold on every run into a hook.
This skill checks all of that, and the validator script checks the mechanical parts in a second.
Claude Code. Put the folder in your skills folder and name it skill-creator-plus:
# for all your projects
git clone https://github.com/robonuggets/skill-creator-plus ~/.claude/skills/skill-creator-plus
# or for one project only, from the project folder
git clone https://github.com/robonuggets/skill-creator-plus .claude/skills/skill-creator-plusOn Windows, ~/.claude is the .claude folder inside your user folder. Downloading the ZIP from GitHub and copying the folder there works too.
claude.ai. Zip the folder (SKILL.md, references/, scripts/ and LICENSE; you can leave out examples/) and upload it under Skills in claude.ai settings. The frontmatter uses only the fields claude.ai accepts. The validator needs code execution turned on.
Just ask in plain words. Three modes:
| Mode | Say something like | You get |
|---|---|---|
| AUDIT | "Audit my deploy skill against Anthropic's rules." / "Check every skill in ~/.claude/skills and tell me what to fix first." | A report: one row per rule, fails first, ranked fixes. Nothing is edited until you pick. |
| NEW | "Make this a skill, we write release notes like this every Friday." | Test prompts first, then a new skill folder that passes the validator. |
| REFINE | "The report skill keeps forgetting the date filter. Fix the skill." | The rule rewritten around its reason, usually shorter than before. |
"Improve my skill for Opus 5.5" runs AUDIT, then REFINE with the fixes you approve.
See examples/pdf-helper-report.md for a full audit of a deliberately broken sample skill.
scripts/validate_skill.py checks the rules a script can check. Python 3.8 or newer, standard library only, works on Windows, Mac and Linux.
python3 scripts/validate_skill.py path/to/my-skill # one skill
python3 scripts/validate_skill.py --all ~/.claude/skills # every skill in a folder, one table
python3 scripts/validate_skill.py path/to/my-skill --json # machine-readable
python3 scripts/validate_skill.py path/to/my-skill --ban-em-dash # also flag em dashes
python3 scripts/init_skill.py my-new-skill --path ~/.claude/skills --refs --scriptsExit codes: 0 no errors (warnings and notes are fine), 1 errors found, 2 could not run. Each finding carries a rule ID from the table below.
Part of the real output for the sample skill in examples/pdf-helper/:
Skill: examples/pdf-helper (name: Claude_PDF_Helper)
ERROR FM1 SKILL.md:4 'description' has an unquoted ': ' (or ends with ':'), which YAML reads as a new key, so the frontmatter will not parse. Wrap the value in double quotes.
ERROR ST4 reference/advanced.md:3 reference/details.md is reached only through other reference files (reference/advanced.md:3), never from SKILL.md. Claude may only preview files it reaches that way (for example with head -100). Link it from SKILL.md, or fold its content into the file that needs it.
ERROR ST5 reference/api.md reference/api.md is 124 lines with no contents list in its first 50 lines. Add a '## Contents' list at the top so a partial read still shows everything the file covers.
WARN DS2 SKILL.md:4 description is not in third person (found "I can"). It is injected into the system prompt; write "Processes Excel files", not "I can help" or "You can use this".
WARN NM2 SKILL.md:20 asks Claude to write out its reasoning ("Think step by step and write"). Newer models (Claude Fable 5, Opus 5.5, Sonnet 5.5) may decline this with the reasoning_extraction refusal. Ask for the answer, or a short explanation of it, instead.
NOTE HK1 SKILL.md:11,31 words like "must always" mark a rule that must hold every time, and the frontmatter has no hooks. Prose can be skipped or cut by compaction; if the rule truly must hold, enforce it with a hook (frontmatter hooks:).
...
Result: 8 errors, 11 warnings, 6 notes - fix the errors first.
The full output is in examples/pdf-helper-validator-output.txt. With --all you get one table:
Skill Errors Warnings Notes Rules with errors or warnings
---------- ------ -------- ----- -----------------------------
pdf-helper 8 11 6 FM1 FM2 ST4 ST5
46 rules. Script means the validator decides. Script + read means the validator flags candidates and Claude confirms in context. Read means Claude judges it during an audit and cites the evidence. "Advice" marks rules from practice rather than from Anthropic's docs.
| ID | Rule | Checked by | Source |
|---|---|---|---|
| FM1 | Frontmatter starts on line 1 and parses as YAML | Script | Claude Code: Frontmatter reference |
| FM2 | Name: lowercase, numbers, hyphens, max 64, no "anthropic" or "claude", matches the folder | Script | Best practices: YAML frontmatter requirements |
| FM3 | Name says the activity (processing-pdfs), not vague (helper) |
Script + read | Best practices: Naming conventions |
| FM4 | Only recognised fields; only six for claude.ai and the Skills API | Script | Claude Code: Frontmatter outside Claude Code |
| FM5 | Invocation set on purpose (manual-only, background, paths) |
Read | Claude Code: Control who invokes a skill |
| DS1 | Description present, at most 1,024 characters, no XML tags | Script | Best practices: YAML frontmatter requirements |
| DS2 | Description in third person | Script + read | Best practices: Writing effective descriptions |
| DS3 | Says what it does and when to use it, in the user's words | Script + read | Best practices: Writing effective descriptions |
| DS4 | Key use case first; description plus when_to_use under 1,536 characters |
Script + read | Claude Code: Descriptions are cut short |
| ST1 | SKILL.md body under 500 lines | Script | Best practices: Progressive disclosure |
| ST2 | Most important instructions near the top | Script + read | Claude Code: Claude stops following a skill |
| ST3 | Split by area, details on demand | Read | Best practices: Progressive disclosure |
| ST4 | References one level deep from SKILL.md | Script | Best practices: Avoid deeply nested references |
| ST5 | Contents list on reference files over 100 lines | Script | Best practices: Table of contents |
| ST6 | Every file reachable and well named; no dead links or backups | Script + read | Best practices: Runtime environment |
| ST7 | Forward slashes in every path | Script | Best practices: Avoid Windows-style paths |
| CT1 | Concise: only what Claude does not already know | Read | Best practices: Concise is key |
| CT2 | Degrees of freedom match the risk; mix levels; "what if Claude does this differently?" | Read | Best practices: Degrees of freedom + advice |
| CT3 | Nothing time-sensitive; old ways under "Old patterns" | Script + read | Best practices: Time-sensitive information |
| CT4 | One term per concept | Read | Best practices: Consistent terminology |
| CT5 | Templates say how strict they are | Read | Best practices: Template pattern |
| CT6 | Input and output examples where style matters | Read | Best practices: Examples pattern |
| CT7 | A default plus one escape hatch, not a menu | Read | Best practices: Too many options |
| CT8 | MCP tools named in full, ServerName:tool_name |
Read | Best practices: MCP tool references |
| CT9 | No TODO, FIXME or unfilled placeholders |
Script | Advice |
| CT10 | One rule, one place | Read | Advice |
| WF1 | Checklist with "done when" lines and a go-back line | Script + read | Best practices: Workflows for complex tasks |
| WF2 | Feedback loop: check, fix, repeat (a style guide counts as a check) | Read | Best practices: Feedback loops |
| WF3 | Plan, validate, execute for batch or destructive jobs | Read | Best practices: Verifiable intermediate outputs |
| WF4 | Standing instructions, not one-time steps | Read | Claude Code: Skill content lifecycle |
| SC1 | Scripts solve errors instead of deferring them | Read | Best practices: Solve, don't defer |
| SC2 | No unexplained ("voodoo") constants | Read | Best practices: Solve, don't defer |
| SC3 | Says whether to run or read each script | Read | Best practices: Utility scripts |
| SC4 | Error messages name the problem and the fix | Read | Best practices: Verifiable intermediate outputs |
| SC5 | Packages listed with install lines; the Claude API cannot install | Script + read | Best practices: Package dependencies |
| NM1 | Not too prescriptive for newer models; test before deleting | Read + test | Fable 5: Scaffolding changes |
| NM2 | No instruction to write out the model's reasoning | Script + read | Fable 5: Scaffolding changes, Opus 5.5 |
| NM3 | Rules carry their reason | Read | Fable 5: Give the reason |
| NM4 | Brief steering; capitals only for real hard lines | Script + read | Fable 5: Instruction following + advice |
| NM5 | Verification explicit; fresh-context verifier preferred | Read | Fable 5: Scaffolding changes |
| HK1 | A rule that has to hold on every run lives in a hook | Script + read | Claude Code: Stops following, Hooks in skills |
| TS1 | At least three evaluations, built first, with a baseline | Read | Best practices: Build evaluations first |
| TS2 | Fresh Claude tests on real work, skill on and off | Read | Best practices: Iterate with Claude, Claude Code: Evaluate |
| TS3 | Tested on the models it runs on; full sweep only where it matters | Read | Best practices: Test with all models + advice |
| LB1 | No two skills claim the same triggers | Read | Advice |
| LB2 | Unused skills found with /skill-doctor and turned off |
Read | Claude Code: Find unused skills |
Rules were checked against Anthropic's pages on 2026-10-05.
SKILL.md the skill: rules, the three modes, links to the rest
references/audit-checklist.md every rule with why, how to check, and the report format
references/authoring-guide.md how to write each part of a skill
references/testing.md evaluations, baselines, model sweeps, test before you delete
scripts/validate_skill.py the validator
scripts/init_skill.py scaffolds a new skill that passes the validator
examples/ a broken sample skill, its validator output and its audit report
The failure-mode names used in audits (no-op, duplication, sediment, sprawl, premature completion) come from Matt Pocock's "writing-great-skills". Not affiliated with Anthropic. MIT license, see LICENSE.
Made by RoboNuggets