Name: Writing Agent Skills
Author: msewell

Workflow: Creating a new skill

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.
Choose a name. Lowercase, hyphens only, 1–64 chars. Prefer gerund form (e.g., processing-pdfs over pdf-processor). Must match directory name.
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.
Write the body. Use imperative form. Include only what the agent cannot already know. Keep under 500 lines (~5000 tokens).
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).
Add scripts only if needed. Include bundled scripts when the same code is rewritten repeatedly or deterministic reliability matters.
Check against the pre-ship checklist in .

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.
Choose a name. Lowercase, hyphens only, 1–64 chars. Prefer gerund form (e.g., processing-pdfs over pdf-processor). Must match directory name.
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.
Write the body. Use imperative form. Include only what the agent cannot already know. Keep under 500 lines (~5000 tokens).
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).
Add scripts only if needed. Include bundled scripts when the same code is rewritten repeatedly or deterministic reliability matters.
Check against the pre-ship checklist in .

Writing Agent Skills