| name | skill-authoring |
| description | Create a new SKILL.md with YAML frontmatter, routing description, and structured body sections from scratch. Use this for "create a skill for X", "write a skill that handles Y", "I need a new skill to do Z", or when a repeated task pattern should become a reusable agent procedure. Do not use for improving existing skills (skill-improver), fixing triggers only (skill-trigger-optimization), adapting to a different context (skill-adaptation), or installing packaged skills (skill-installer). |
| license | Apache-2.0 |
| compatibility | {"clients":["opencode","copilot","codex","gemini-cli","claude-code"]} |
Purpose
Create new agent skills in the SKILL.md format: YAML frontmatter for routing metadata plus a markdown body with Purpose, When to use, Operating procedure, Output defaults, and Failure handling. The description field is routing logic — it determines whether the skill fires.
When to use this skill
Use when:
- User says "create a skill for X", "write a skill that...", "I need a skill to handle..."
- Repeated task pattern needs capturing as a reusable procedure
- Capability should be packaged for distribution or reuse across projects
- New agent specialization needed for a repo's agent team
Do NOT use when:
- Skill exists and needs improvement →
skill-improver
- Only description/trigger needs fixing →
skill-trigger-optimization
- Skill needs adaptation to different context →
skill-adaptation
- User wants to install a packaged skill →
skill-installer
- User wants a one-off prompt, not a reusable skill
Operating procedure
Step 1 — Define the skill's job in one sentence
Write: "This skill [verb] when [trigger] and produces [output]."
If you cannot write this sentence, the scope is wrong — narrow until it works.
Calibrate specificity to task fragility:
- High freedom (prose): Multiple valid approaches, context-dependent decisions
- Medium freedom (pseudocode): Preferred pattern with acceptable variation
- Low freedom (exact scripts): Fragile operations where consistency is critical
Step 2 — Choose the name
- Lowercase, hyphens, 2–4 words, under 64 characters
- Describe what it does (verb-noun), not when it's used
- Examples:
premortem, gap-analysis, acceptance-criteria-hardening
Step 3 — Write the YAML frontmatter
---
name: skill-name
description: >-
[Action verb] [specific object] when [task conditions].
Use this for [2-3 realistic trigger phrases in quotes].
Do not use for [adjacent non-matching cases with named alternatives].
license: Apache-2.0
compatibility:
clients: [opencode, copilot, codex, gemini-cli, claude-code]
---
Description field rules
The description is routing logic — the highest-leverage field in the skill.
Requirements:
- Start with an action verb (not a noun phrase)
- Include 2–3 realistic trigger phrases users would say
- State what the skill produces
- End with "Do not use for..." naming adjacent skills
Weak: "Helps with PDFs."
Strong: "Extract structured data from PDFs when the task involves tables, scanned pages, or layout-dependent interpretation. Use this for 'extract the table from this PDF', 'convert this PDF to CSV', or 'parse the scanned invoice'. Do not use for plain-text summarization when PDF text is already clean (use text-summarization)."
Flag a description if it: is under 12 words, has no action verb first, has no condition, lacks trigger examples, could apply to multiple skills, or has no negative boundary.
Frontmatter fields
| Field | Required | Notes |
|---|
name | Yes | Must match folder name |
description | Yes | Routing logic, not documentation |
license | Recommended | Default: Apache-2.0 |
compatibility.clients | Recommended | Which agent clients support this skill |
Common authoring mistakes
Watch for these — they are the most frequent causes of weak skills from new authors:
- Writing a tutorial instead of a procedure. Symptoms: "Let me explain…", background history sections, technology overviews. A skill is an operating manual, not a textbook. Cut everything the agent doesn't need mid-task.
- Describing goals instead of steps. Symptoms: "Ensure quality", "Optimize performance" with no HOW. Every step must be a concrete verb the agent can execute: Read, Write, List, Check, Run.
- Copying reference material inline. Symptom: SKILL.md >200 lines filled with lookup tables, API schemas, or configuration catalogs. Extract to
references/ and link from the procedure.
- Writing the description last. The description should be written FIRST — it defines the scope everything else must serve. Writing it last leads to scope drift where the body outgrows the description.
- Forgetting negative boundaries. Every skill must say what it's NOT for with named alternatives. Without this, hosts cannot distinguish adjacent skills and routing degrades.
Step 4 — Write the body sections
Every SKILL.md body contains these sections in order:
Purpose (required)
2–3 sentences. What problem does it solve? What output does it produce? No filler.
When to use this skill (required)
- "Use when:" — 4–6 specific trigger phrases or observable conditions
- "Do NOT use when:" — 3–4 confusion cases with named alternatives
Operating procedure (required)
Numbered steps. Each starts with a verb. Each is completable and verifiable.
Rules:
- No meta-commentary ("Keep scope explicit", "Think about the approach")
- No hedge verbs ("Consider", "You might want to", "Ensure")
- Use action verbs: Read, List, Write, Check, Run, Compare
- Each step must be independently executable
Output defaults (required)
Exact format with template showing section names, field names, or schemas.
Bad: "Structured markdown with clear next steps"
Good: Template with named sections, tables, or code blocks
Failure handling (required)
Name 2–3 most common failure modes with specific recovery actions.
Bad: "If something goes wrong, report the issue"
Good: "If target file does not exist: stop, report missing path, ask user to confirm location"
References (optional)
Real URLs to authoritative documentation. Not vague "see docs".
Size target
Keep SKILL.md under 500 lines. Over that, extract reference material into references/ and link from SKILL.md. Challenge each paragraph: "Does this justify its token cost?"
Skills load at three levels:
- Metadata (name + description) — always in context (~100 words)
- SKILL.md body — loaded when skill triggers (target: under 5k words)
- Bundled resources — loaded on demand by the agent
Step 5 — Validate against anti-patterns
Check the completed skill for:
- Circular triggers ("when task involves X" without defining X)
- Boilerplate procedure steps with no specific action
- Generic output defaults lacking concrete format
- Vague failure handling without recovery actions
- Description that could apply to multiple different skills
Step 6 — Create the skill folder
skill-name/
├── SKILL.md # Frontmatter + body sections
├── scripts/ # Optional: deterministic automation
├── references/ # Optional: large docs for progressive disclosure
└── templates/ # Optional: reusable output skeletons
Only create subdirectories if they contain actual files. Do not add README.md, CHANGELOG.md, or other meta-documentation — the folder contains only what an agent needs to do the job.
Output defaults
Deliver a complete skill folder containing:
- SKILL.md with valid YAML frontmatter and all required body sections
- references/ if the skill needs progressive disclosure for large reference material
- scripts/ if the skill includes deterministic automation
- templates/ if the skill provides reusable output skeletons
The SKILL.md must pass all Step 5 anti-pattern checks before delivery.
References
Failure handling
- Scope too broad: Skill handles multiple distinct tasks → split via
skill-variant-splitting
- Cannot write one-sentence definition: Scope is wrong → narrow until the sentence works
- Overlaps existing skill: Check catalog → merge or differentiate explicitly in descriptions
- No clear trigger phrases: Ask user what words they'd use when they need this capability
- Description lint-passes but never fires: Add more trigger phrase variations → test with
skill-testing-harness
