Skill Doc Authoring
Produce a single valid SKILL.md that an agent will actually trigger and follow. The two failure modes this prevents: skills that never fire (weak description) and skills that fire but don't help (vague body).
File contract
- Directory name and
name: MUST match, lowercase, hyphens only, ≤ 64 chars.
- Filename MUST be exactly
SKILL.md (case-sensitive).
- Frontmatter has exactly two keys:
name, description. description ≤ 1024 chars.
skills/<skill-name>/SKILL.md
The description is the trigger
The agent decides whether to load the skill from the description alone. Write it in third person, lead with what it does, then "Use when …" with concrete user phrasings and situations. Include the trigger words a user would actually type.
- Weak:
Workflow for handling data.
- Strong:
Validate and clean CSV exports before import. Use when the user uploads a CSV, mentions "dirty data", or asks to "prep this for the database".
State when not to use it if a sibling skill is close — overlapping triggers cause the wrong skill to fire.
Body structure
Write for an agent with no project context. Concise, imperative, decision-oriented.
# Title
One-line purpose.
## When to use # + when not to
## Procedure / The loop # numbered, concrete, with commands
## Quality bar # how to know it's done right
## Anti-patterns # the tempting wrong moves
Rules:
- Imperative voice ("Run X", "Verify Y"), not "the agent should consider".
- Every step is verifiable or has a concrete command/example.
- Cut "Notes", "Overview" padding, and restatements. If a line doesn't change what the agent does, delete it.
- Put long reference material (schemas, tables, scripts) in sibling files and link them; keep
SKILL.md skimmable (aim < ~200 lines).
Procedure
- Extract the real procedure from the user (the SOP, the steps they actually take, the decisions and their criteria).
- Identify triggers: what does someone say/do right before this skill is needed?
- Draft the description (trigger test: would it fire on those phrasings? would it not fire on unrelated ones?).
- Write the body to the structure above.
- Validate: filename, name/dir match, frontmatter keys, description length.
- Dry-run mentally: give the skill to a context-free agent on 2–3 sample requests — does it know exactly what to do?
Anti-patterns
- Generic skeleton (Overview → "This skill enables…" → bulleted nouns → Notes) that fits any topic and helps with none.
- Description that describes the domain but never says when to fire.
- Restating general best practice the model already knows instead of the user's specific procedure.
- One giant
SKILL.md where a script + a short doc would serve better.
1---2name: skill-doc-authoring3description: Write a well-formed agent SKILL.md from a workflow, SOP, or repeated procedure. Use when the user wants to "create a skill", "turn this process into a skill", "document this workflow as a skill", or asks why a skill isn't triggering.4---56# Skill Doc Authoring78Produce a single valid `SKILL.md` that an agent will actually trigger and follow. The two failure modes this prevents: skills that never fire (weak description) and skills that fire but don't help (vague body).910## File contract1112- Directory name and `name:` MUST match, lowercase, hyphens only, ≤ 64 chars.13- Filename MUST be exactly `SKILL.md` (case-sensitive).14- Frontmatter has exactly two keys: `name`, `description`. `description` ≤ 1024 chars.1516```17skills/<skill-name>/SKILL.md18```1920## The description is the trigger2122The agent decides whether to load the skill from the `description` alone. Write it in third person, lead with what it does, then **"Use when …"** with concrete user phrasings and situations. Include the trigger words a user would actually type.2324- Weak: `Workflow for handling data.`25- Strong: `Validate and clean CSV exports before import. Use when the user uploads a CSV, mentions "dirty data", or asks to "prep this for the database".`2627State when **not** to use it if a sibling skill is close — overlapping triggers cause the wrong skill to fire.2829## Body structure3031Write for an agent with no project context. Concise, imperative, decision-oriented.3233```34# Title35One-line purpose.36## When to use # + when not to37## Procedure / The loop # numbered, concrete, with commands38## Quality bar # how to know it's done right39## Anti-patterns # the tempting wrong moves40```4142Rules:43- Imperative voice ("Run X", "Verify Y"), not "the agent should consider".44- Every step is verifiable or has a concrete command/example.45- Cut "Notes", "Overview" padding, and restatements. If a line doesn't change what the agent does, delete it.46- Put long reference material (schemas, tables, scripts) in sibling files and link them; keep `SKILL.md` skimmable (aim < ~200 lines).4748## Procedure49501. Extract the real procedure from the user (the SOP, the steps they actually take, the decisions and their criteria).512. Identify triggers: what does someone say/do right before this skill is needed?523. Draft the description (trigger test: would it fire on those phrasings? would it *not* fire on unrelated ones?).534. Write the body to the structure above.545. Validate: filename, name/dir match, frontmatter keys, description length.556. Dry-run mentally: give the skill to a context-free agent on 2–3 sample requests — does it know exactly what to do?5657## Anti-patterns5859- Generic skeleton (Overview → "This skill enables…" → bulleted nouns → Notes) that fits any topic and helps with none.60- Description that describes the domain but never says *when* to fire.61- Restating general best practice the model already knows instead of the user's specific procedure.62- One giant `SKILL.md` where a script + a short doc would serve better.
composio-community