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

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

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 the agent 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 the target agent already does unprompted ("Cut Constraints, Keep Opinions"). On current frontier models over-prescription is not merely wasted tokens: instructions carried forward from older models are often too prescriptive and lower output quality, so the constraint cut is correctness work
• 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
• Write the permission side of the envelope, not only the restriction: grant a known-safe loop with the reason it is safe, and keep confirmation for what deploys, sends, spends, or writes outside the working tree ("Grant Permission, Don't Just Restrict")
• State the workflow dependencies, what the finished state includes, and the completion evidence; scope and evidence are different sentences ("Say Where the Work Ends"). Keep a stop-for-review step only where the decision is genuinely the user's; current frontier models honor a mandatory pause literally and end the task there. Add a checklist only when it helps track a long or resumable task
• Put the deliverable, routing, and task-specific constraints first; loading and compaction behavior depend on the host. A skill with several workflows makes SKILL.md a router (mode choice, shared contract, one pointer per workflow) and keeps each workflow's body in its own reference ("Use the File System for Progressive Disclosure")
• 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.