agent-skills-creator

Create and improve skills in the Agent Skills open format: full lifecycle from pattern selection through validation and README update.

• IS: creating new agent skills and auditing or rewriting existing ones: SKILL.md, references, rules folders, scripts, evaluations.
• IS NOT: AGENTS.md/CLAUDE.md instruction files (use agents-md) or general documentation quality (use docs-writing).

Choose a Mode

• New skill → Creation Workflow below.
• Audit, improve, or rewrite an existing skill → references/improving-existing-skills.md, which scores eleven audit dimensions, runs an ordered rewrite, then reuses Steps 5-8 for validation and shipping.
• Simplify, rightsize, or cut an over-constrained skill → same reference. Run /doctor first: the harness ships skill and CLAUDE.md rightsizing, and this skill’s audit is the deeper per-skill pass that follows it, not a replacement.

Reference Files

Mechanical rules are not in any of these. scripts/validate.sh is their single statement:

scripts/validate.sh skills/<name>   # one skill
scripts/validate.sh --all           # every skill in the repo

Creation Workflow

Copy this checklist to track progress:

Skill creation progress:
- [ ] Step 1: Choose a pattern
- [ ] Step 2: Create directory and frontmatter
- [ ] Step 3: Write SKILL.md body
- [ ] Step 4: Add reference or rule files
- [ ] Step 5: Validate
- [ ] Step 6: Update README.md and docs/skills.mdx
- [ ] Step 7: Smoke-test installation
- [ ] Step 8: Evaluate and iterate

Step 1: Choose a pattern

Simple/hub, workflow, rules-based, or mixed. references/skill-patterns.md has the shapes, the in-repo example for each, and the problem-to-pattern affinity table.

Step 2: Create directory and frontmatter

Create skills/<name>/SKILL.md with name and description. Write the description as a model trigger, not a human summary: what it does, what it covers, then “Use when…” with the phrases users actually say. validate.sh enforces the limits, so write for routing and let the script police the constraints.

Step 3: Write SKILL.md body

references/authoring-tips.md carries the judgement. Apply:

• Open with an IS/IS-NOT pair when adjacent skills exist or scope creep is likely (“Open with Boundaries”)
• Add only context Claude lacks (“Don’t State the Obvious”); use consistent terminology
• Phrase guidance as an outcome, reserving absolutes for safety, data loss, format contracts, and observed failures (“Judgement Over Rules”)
• Check nothing here contradicts the harness, a sibling skill, or the repo AGENTS.md; route instead of restate (“Don’t Fight the Harness or a Sibling”)
• Keep the opinions that make the skill worth invoking; cut only what Claude already does unprompted (“Cut Constraints, Keep Opinions”)
• Match degrees of freedom to fragility: prose for open-ended work, exact commands for fragile or destructive ops (“Degrees of Freedom”)
• Reach for named content patterns: template for fixed output, examples only where style is the deliverable, conditional for decision points
• Add a copyable progress checklist for multi-step workflows; validation loops for quality-critical tasks
• Build a Gotchas section from observed failures: the highest-signal content in any skill

Step 4: Add reference or rule files

• Workflow/mixed: a references/ folder, each file linked from SKILL.md with a “Read when” condition
• Rules-based: a rules/ folder; references/rules-folder-structure.md covers _sections.md, _template.md, and file naming
• Simple/hub: track files alongside SKILL.md, linked from a tracks table

Prefer a reference that is code. An existing implementation or a test suite pins a contract better than prose describing it (“Reference-as-Spec”). Split by loading condition, not line count: two topics read at different moments are two files.

Advanced: scripts/ for executables Claude composes (see references/executable-code.md), config.json for setup context that would otherwise be re-asked every session, and on-demand PreToolUse/PostToolUse hooks for safety gates.

Step 5: Validate

scripts/validate.sh skills/<name>

Output separates format (the spec) from house style (this repo’s taste). Fix every FAIL; a SKIP always states why it did not apply.

Step 6: Update README.md and docs/skills.mdx

Add a bullet under the matching category heading in both files, and bump the skill count near the top of the README:

- **[<skill-name>](./skills/<skill-name>/SKILL.md)**: <one-line description>

Categories: Architecture, Design, Writing, Quality, Shipping, Authoring. validate.sh verifies both bullets and the count.

Step 7: Smoke-test

npx skills add mblode/agent-skills -g --skill <name> -y
ls ~/.claude/skills/<name>/

skills add writes to ~/.agents/skills/<name>/, symlinked into ~/.claude/skills/<name>/ for Claude Code to pick up. For local iteration without reinstalling, symlink the repo folder directly and unlink when done:

ln -s /path/to/agent-skills/skills/<name> ~/.claude/skills/<name>

Step 8: Evaluate and iterate

references/evaluation-and-iteration.md. Define 3+ scenarios, test on each target model, and iterate on observed behavior rather than assumptions. Ablate any rule you suspect is dead weight: delete it, rerun the scenarios, keep it only if one regresses.

Anti-patterns

• Absolute prohibitions where outcome phrasing would do; the rule gets followed on the one prompt in ten where you would have wanted a pivot
• Directives restating or contradicting the harness, a sibling skill, or the repo AGENTS.md, forcing the model to reconcile before it can act
• Cutting a skill’s opinions during a simplification pass, leaving something that validates clean and changes no behavior
• Usage examples standing in for an expressive interface; name the parameters and enums instead
• A rule stated in SKILL.md and again in a script’s --help, a tool description, or a rule file
• Telling users to hand-write memories into CLAUDE.md; auto-memory owns user, feedback, and project facts
• Describing a contract in prose when the code or test suite that defines it could be pointed at
• Dumping the full specification into the SKILL.md body instead of a reference file
• Time-sensitive content (“before August 2025, use…”)
• Restating what Claude already knows (Markdown, general coding advice, standard conventions)
• A description written as a human summary or in “I audit…” voice instead of a third-person trigger with “Use when…” phrases
• Vague names (helper, utils, tools, documents, data) that give the model nothing to route on
• Skipping a Gotchas section for skills with known failure modes
• Magic numbers in scripts with no justifying comment
• Shipping without testing on every target model; what reads well to Opus may underspecify for Haiku

Related Skills

• agents-md for auditing AGENTS.md/CLAUDE.md instruction files
• docs-writing for documentation quality rules