skill-authoring-guide

Skill Authoring Guide

Use this skill when creating or improving a reusable skill.

What Good Skills Do

• Trigger reliably from name and description — the description must be specific enough to avoid false triggers.
• Stay short in SKILL.md and move bulk detail into references/ or scripts/.
• Teach a workflow or decision pattern, not just dump background information.
• Include scripts or references only when they eliminate repeated work or prevent ambiguity.

Frontmatter Template

---
name: kebab-case-matching-directory-name
description: Use when [trigger condition]. Does [what it does]. [Optional: NOT for X.]
---

Body Format

Default to a pure Markdown body after the YAML frontmatter. Use headings such as ## Purpose, ## When to Use, ## Workflow, and ## Verification. Do not use XML-like tags such as <Purpose>, <Workflow>, or <Use_When> as normal top-level sections. XML-like tags are acceptable only when they strictly delimit nested examples, quoted input, external documents, or machine-readable prompt payloads.

Good description (specific, trigger-clear):

Use when designing or reviewing filesystem MCP access, path boundaries, allowed roots, and method allowlists.

Weak description (too broad, won't trigger reliably):

Helps with MCP things and file access.

Workflow

1. Define the job

• What specific problem does this skill solve?
• When should it trigger? (Be concrete — "when the user mentions X" or "when you're about to do Y".)
• What should it explicitly NOT handle? State the boundary.

2. Write strong frontmatter

• name must match the directory name exactly.
• description must say what the skill does AND when to use it in one sentence.

3. Keep the body lean

• SKILL.md should be readable in one focused pass — target 50–120 lines.
• Use Markdown headings for top-level structure.
• Move bulky reference material into references/.
• Move deterministic scripts (validators, init scripts) into scripts/.
• If SKILL.md exceeds 150 lines, split off the excess into a reference file.