Agent Skills Creator

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 ghostwriter).

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 a skill or update a collection → same reference, plus references/capability-delta.md for retention decisions and the collection ledger.
• Skill never triggers, triggers on the wrong prompts, or its description is being trimmed in a crowded listing → the Routing Evals section of references/evaluation-and-iteration.md, then the description. Body edits do not fix routing.
• Skill stops after a first draft and hands back for review when nobody asked → "Say Where the Work Ends" in references/authoring-tips.md; the fix is the scope of done and the review checkpoints, not the steps.

Reference Files

The validator is the single local statement of mechanical gates. From the repository root:

skills/agent-skills-creator/scripts/validate.sh skills/<name>   # one skill
skills/agent-skills-creator/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 where the repo has one)
- [ ] Step 7: Smoke-test installation
- [ ] Step 8: Evaluate and iterate

Step 1: Choose a pattern

Check for an existing owner of the job before creating a skill; references/adopt-adapt-author.md guides reuse and scope.

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, the --- on line 1. 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, and the key use case first because the listing trims descriptions from the tail when it runs over budget. Keep it as short as it can be while still saying when it applies: every installed description sits in every session, and one that over-claims loads a skill that does not help. validate.sh enforces the limits, so write for routing and let the script police the constraints.

Decide where the skill will run before adding any other field. Use portable fields for this collection; put genuine runtime prerequisites in compatibility. Host-specific fields require current host documentation and a deliberately host-specific package. State authorization boundaries in the body when a workflow deploys, sends, or spends, and grant the safe loops just as explicitly; the body carries both sides of that envelope. The format reference distinguishes these contracts.

Step 3: Write SKILL.md body

Read references/authoring-tips.md first: it carries the judgement on what to include, how hard to say it, the permission and completion scope, degrees of freedom, content patterns, and progressive disclosure. Build the Gotchas section from observed failures; it is 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, all covered in references/executable-code.md and references/format-specification.md: scripts/ for executables the agent composes, resolved relative to the installed SKILL.md; Claude Code can substitute ${CLAUDE_SKILL_DIR}; !`command` injection for data the skill always needs at invocation (a diff, PR comments); hooks frontmatter for a PreToolUse gate that should exist only while the skill is active; config.json for setup context that would otherwise be re-asked every session.

Step 5: Validate

skills/agent-skills-creator/scripts/validate.sh skills/<name>

Output separates format requirements from house conventions, including recommendations adopted as local gates. Fix every FAIL. Run skills-ref validate <dir> for an independent metadata and naming check. Neither check establishes behavioral quality or compatibility with every host.

Step 6: Update README.md

Add the skill's bullet under the matching category heading and bump the count; validate.sh checks both and names what is missing. Where the repo also ships docs/skills.mdx, add the same bullet there.