Create Skill

Create agent skills that are portable, easy to trigger, and cheap to load. A skill is a folder containing a SKILL.md file with YAML frontmatter and markdown instructions.

Workflow

1. Intake (mandatory gate) — Understand what the skill should do. Ask at least 3 targeted questions before drafting anything. Collect:

   • A short name (lowercase, hyphenated)
   • What the skill enables the agent to do
   • When it should activate (trigger conditions)
   • What success looks like

   Summarize your understanding and get explicit confirmation before proceeding. Do not write SKILL.md until the user confirms.

2. Investigate the repo — Before asking questions, search the repo for:
   • Existing skills, conventions, and workflow docs
   • Scripts, templates, schemas relevant to the target workflow
   • Tool or dependency requirements
   • Whether the conversation already contains a workflow to capture
3. Clarify — Ask only questions that materially affect the skill. Push until these are clear:
   • Required workflow steps and their order
   • Required inputs and expected outputs
   • Dependencies on tools, scripts, or services
   • Whether the skill needs references/, scripts/, or assets/

4. Design the package — Structure:

   skill-name/
   ├── SKILL.md        # Metadata + core workflow
   ├── references/     # Detailed docs, loaded on demand
   ├── scripts/        # Executable code
   └── assets/         # Templates, resources

   • Keep SKILL.md under 500 lines
   • Move bulky detail into references/
   • Put deterministic execution in scripts/
   • Don't duplicate guidance across files

5. Write SKILL.md — Structure:

   ---
   name: skill-name
   description: >
     What the skill does and produces. Use when the user wants
     to <scenario>, mentions <keyword>, or asks about <topic>.
   ---

   Frontmatter rules:

   • Required: name and description in frontmatter. Other fields depend on your project's conventions.
   • Version in frontmatter is always "1.0.0" for new skills. Never use 0.x.y — first release is 1.0.0.
   • CHANGELOG.md starts with ## [Unreleased] containing the initial entries. Do not assign a version heading until the skill is actually released (git tagged).

   Writing rules:

   • Description optimizes activation, not teaching. State the job and when to use it in words a user would actually say. Include both actions and situations. Keep workflow details out of the description.

     Bad: Follows a 7-step process to generate SKILL.md files with YAML frontmatter.

     Good: Creates agent skills. Use when the user wants to build a SKILL.md, turn a workflow into a reusable skill, or is frustrated by inconsistent agent behavior.

   • Body is procedural and imperative. Tell the agent exactly how to proceed. Don't restate trigger criteria from the description — a "When to use" section in the body duplicates the description.
   • Use imperative form. "Do not", "Use", "Run" — not "prefer" or "consider".
   • Be concise. Terse reminders, not tutorials.
   • Include a complete example. One full, copy-paste-ready artifact beats scattered snippets.
   • Include a Boundaries section (mandatory). List what the skill DOES and Does NOT do.
   • Include a Common Failures section. List 2–3 domain-specific mistakes an agent would make without this guidance.

   See example-skill.md for a complete finished skill demonstrating these principles.

6. Validate — Test the skill with representative prompts:

   • 2–3 realistic positive prompts (things users would say)
   • At least 1 negative prompt (adjacent but shouldn't trigger)

   Write a brief validation report noting:

   • Which prompts triggered correctly
   • Which failed and why (trigger wording, workflow ambiguity, or missing resources)
   • What was fixed based on the failures

   Skip validation only for trivial skills where the trigger surface is obvious.

   Portability check — For distributable skills, verify:

   • No hardcoded project-specific paths (use discovery)
   • No project-specific terminology (internal jargon)
   • No references to specific rules/tools only in your repo
   • Instructions work in any repo with any directory layout
7. Acknowledge sources — If the skill draws on external practices, create references/ACKNOWLEDGMENTS.md listing each source with a link, license, what was adapted, and the version it was adopted in.
8. Confirm — Show the user the created skill and ask if adjustments are needed.

Boundaries

• DOES create skill directories, SKILL.md, references/, scripts/
• DOES validate with representative prompts
• Does NOT modify existing skills
• Does NOT create rules or profiles (separate workflows)

Example Scenario

User: "Turn my database migration steps into a skill." → Investigate repo (Flyway config) → ask about rollback scope → create migrate-database/SKILL.md → validate with prompts.

Common Failures

• Description leaks workflow — the agent reads the summary and skips the body, following a shortcut instead of the full procedure.
• Body too abstract to act on — "investigate the problem" isn't actionable. "Run git log --oneline -20 to check recent patterns" is.
• Weak enforcement in instructions — If evals show the agent ignoring a step, add it to a Common Failures section with NEVER/MUST language. Explicit failure modes with strong directives are more effective than polite workflow steps.

Quality Checklist

Before finalizing, use the skill design checklist, skill validation, and token optimization.