writing-agent-skillslisted

# Writing Agent Skills ## Workflow: Creating a new skill 1. **Clarify scope.** Ask what task the skill should teach an agent to perform. Identify what context an agent lacks — that gap is the skill's content. 2. **Choose a name.** Lowercase, hyphens only, 1–64 chars. Prefer gerund form (e.g., `processing-pdfs` over `pdf-processor`). Must match directory name. 3. **Write the description.** This is the most important text in the skill — it controls when the skill activates. Write in third person. State both what the skill does AND when to use it. Include keywords matching how users phrase requests. Max 1024 chars. 4. **Write the body.** Use imperative form. Include only what the agent cannot already know. Keep under 500 lines (~5000 tokens). 5. **Apply progressive disclosure.** If content exceeds 500 lines, move detailed information into `references/` files. Link from `SKILL.md` — keep all references one level deep (no chains). 6. **Add scripts only if needed.** Include bundled scripts when the same code is rewritten repeatedly or deterministic reliability matters. 7. **Validate.** Check against the pre-ship checklist in [references/08-organizing-and-checklist.md](references/08-organizing-and-checklist.md). ## Workflow: Reviewing an existing skill 1. Read the skill's `SKILL.md` and all bundled files. 2. Check for these common problems: - **Weak description** — vague, missing keywords, wrong point-of-view - **Kitchen sink** — body over 500