name: skill-creator-plus description: Audits, creates and improves Agent Skills (folders with a SKILL.md) against Anthropic's skill authoring best practices, the Claude Code skills docs and the prompting guides for newer models such as Claude Fable 5 and Opus 5.5. Audit mode reports every rule as pass, fail or not applicable, with file and line evidence and a proposed fix, and changes nothing until the user approves. Use when the user asks to audit, review, check or score a skill or a folder of skills, to create a new skill or turn a repeated workflow into one, to improve, shorten, refactor or update an old skill for newer models, or to run the skill validator. license: MIT

Skill Creator Plus

Audits, builds and improves skills so Claude takes the same process on each run. A skill is a table of contents, not a manual: the description gets it chosen, SKILL.md says what to do, and detail waits in reference files until a step needs it.

Rules for every mode

1. Report before you change. Start from evidence: the validator's output and a full read of the skill. In AUDIT, edit nothing until the user picks which findings to fix, because a skill change alters each future run and the user owns that call. A direct request to fix a named problem is already that approval.
2. Absorb, don't layer. Fold new guidance into the rule it refines and delete what it replaces. A good edit usually leaves the skill shorter. Write the reason, not the date, so a later editor can tell whether the rule still holds.
3. Test before you delete. Newer models often do better with fewer instructions, but only a with-skill and without-skill run proves a line is dead weight. Method: references/testing.md, "Test before you delete".
4. The validator is the floor. scripts/validate_skill.py checks what a script can check. The judgment rules in references/audit-checklist.md need a careful read.

Pick the mode

"Improve this skill" means AUDIT, then REFINE with the approved changes.

AUDIT

Copy this checklist into the reply and tick it off:

Audit progress:
- [ ] 1 Validator run on every skill in scope
- [ ] 2 Each skill read in full: SKILL.md, references, scripts
- [ ] 3 Every checklist rule marked pass, fail or N/A, with evidence
- [ ] 4 Report written
- [ ] 5 User chose which changes to apply
- [ ] 6 Approved changes applied
- [ ] 7 Validator re-run with no new errors or warnings

Step 1. Run the validator. python3 scripts/validate_skill.py <skill-folder> for one skill, or --all <folder> for a library; then audit in full the skills the user picks, by default the five with the most errors. Add --json to parse the results. Done when you have output for every skill in scope.

Step 2. Read the skill. All of it: SKILL.md, each reference file, each script. Done when you can name the skill's job, its branches and what every file is for.

Step 3. Mark every rule. Open references/audit-checklist.md. Script rules take the validator's result; read rules need evidence you can cite as file and line. Done when no rule is unmarked.

Step 4. Write the report in the format at the end of the checklist: the table with fails first, the changes ranked by impact, then anything that needs the user's decision. The worked example in examples/ shows the bar.

Step 5. Stop and ask. End the turn with the numbered changes. Edit nothing until the user picks.

Step 6. Apply the approved changes following REFINE. Before deleting instructions as too prescriptive (rule NM1), run the test in references/testing.md.

Step 7. Re-run the validator. If it shows a new error or warning, return to Step 6.

NEW

New skill progress:
- [ ] 1 Evidence: the task done once without a skill, gaps noted
- [ ] 2 Three test prompts and a no-skill baseline
- [ ] 3 Shape, invocation and freedom chosen
- [ ] 4 Folder scaffolded
- [ ] 5 Frontmatter and body written
- [ ] 6 Validator clean
- [ ] 7 Tests re-run in a fresh session
- [ ] 8 Audit checklist passed

1. Evidence. Do the task once with Claude and no skill, or read real past examples. Note what had to be explained. Done when you can list the gaps the skill must close.
2. Tests first. Write three prompts people would type and record the no-skill result (references/testing.md). Done when the baseline is written down.
3. Shape. Choose single file, bundle or router; who can invoke it; and the freedom for each step (references/authoring-guide.md). Done when each choice has a one-line reason.
4. Scaffold. Run python3 scripts/init_skill.py <name> --path <skills-folder>, adding --refs, --scripts or --user-invoked as needed. It creates the folder and validates it. Done when the folder exists.
5. Write. Description first, then the body: the most important rules at the top, a checklist with a go-back line for multi-step work, detail in linked files. Replace every [FILL: ...] placeholder. Done when nothing is left to fill.
6. Validate. Run the validator on the folder. Fix every error; fix or justify every warning. If an error remains, return to step 5.
7. Re-test. Run the test prompts in a fresh session with the skill on. If one fails, return to step 5.
8. Audit. Mark the checklist rules that need a read. Done when nothing fails.

REFINE

1. Name the evidence in one line: what happened, what the user said, what shipped.
2. Find the principle that explains it. If you cannot name it, you are not ready to edit.
3. Rewrite every line the principle touches and delete lines it makes redundant. If a shipped result contradicts an older rule, the shipped result wins; tell the user.
4. Check. Run the validator. The file should not have grown; if it did, find what the new rule made redundant. If the validator shows a new error, return to step 3.

Resources

• references/audit-checklist.md - every rule with its ID, why it matters, how to check it and its source, plus the report format and the failure modes. Open in AUDIT step 3, and before calling any skill done.
• references/authoring-guide.md - how to write each part: frontmatter fields, description, structure, degrees of freedom, workflows, scripts, hooks, newer models. Open in NEW steps 3 to 5 and in REFINE.
• references/testing.md - evaluations, fresh-session baselines, Claude A and B, model sweeps, test before you delete. Open in NEW steps 2 and 7, and before cutting instructions.
• examples/pdf-helper-report.md - a finished audit report for the flawed sample skill in examples/pdf-helper/, built from the validator output in examples/pdf-helper-validator-output.txt. Open to see the bar for a report.
• scripts/validate_skill.py - run it, do not read it. --help lists the flags.
• scripts/init_skill.py - run it to scaffold a new skill.

Script paths are relative to this skill's folder (in Claude Code, ${CLAUDE_SKILL_DIR}). Use python3, or python on Windows. Python 3.8 or newer, standard library only, nothing to install.

skill-creator-plus

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.

Why this matters now

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_extraction refusal: 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.

Install

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-plus

On 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.

Use it

Just ask in plain words. Three modes:

"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.

The validator

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 --scripts

Exit 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

The rules

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.