diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 92efc50f..7e8aae75 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,7 +7,7 @@ Thanks for your interest in contributing! This project is a collection of produc 1. Create a directory under `skills/` with a kebab-case name 2. Add a `SKILL.md` following the format in [docs/skill-anatomy.md](docs/skill-anatomy.md) 3. Include YAML frontmatter with `name` and `description` fields -4. Ensure the `description` starts with "Use when" and describes triggering conditions +4. Ensure the `description` briefly says what the skill does, then includes clear "Use when" trigger conditions ### Skill Quality Bar @@ -20,7 +20,12 @@ Skills should be: ### Structure -Every skill should include these sections: +Every new skill must have: + +- `SKILL.md` in the skill directory +- YAML frontmatter with valid `name` and `description` + +New skills should generally follow the standard anatomy: - **Overview** — What this skill does and why it matters - **When to Use** — Triggering conditions diff --git a/README.md b/README.md index db5132f3..ff74b3a4 100644 --- a/README.md +++ b/README.md @@ -207,7 +207,7 @@ Quick-reference material that skills pull in when needed: ## How Skills Work -Every skill follows a consistent anatomy: +Most skills follow a consistent anatomy: ``` ┌─────────────────────────────────────────────┐ @@ -215,7 +215,7 @@ Every skill follows a consistent anatomy: │ │ │ ┌─ Frontmatter ─────────────────────────┐ │ │ │ name: lowercase-hyphen-name │ │ -│ │ description: Use when [trigger] │ │ +│ │ description: What it does. Use when… │ │ │ └───────────────────────────────────────┘ │ │ │ │ Overview → What this skill does │ diff --git a/docs/skill-anatomy.md b/docs/skill-anatomy.md index ba529901..6b648223 100644 --- a/docs/skill-anatomy.md +++ b/docs/skill-anatomy.md @@ -9,7 +9,7 @@ Every skill lives in its own directory under `skills/`: ``` skills/ skill-name/ - SKILL.md # Required: The skill definition + SKILL.md # Required: The skill definition supporting-file.md # Optional: Reference material loaded on demand ``` @@ -26,11 +26,11 @@ description: Brief statement of what the skill does. Use when [specific trigger **Rules:** - `name`: Lowercase, hyphen-separated. Must match the directory name. -- `description`: Starts with what the skill does (third person), followed by trigger conditions. Include both *what* and *when*. Maximum 1024 characters. +- `description`: Start with what the skill does, then include one or more clear "Use when" trigger conditions. Include both *what* and *when*. Maximum 1024 characters. **Why this matters:** Agents discover skills by reading descriptions. The description is injected into the system prompt, so it must tell the agent both what the skill provides and when to activate it. Do not summarize the workflow — if the description contains process steps, the agent may follow the summary instead of reading the full skill. -### Standard Sections +### Standard Sections (Recommended Pattern) ```markdown # Skill Title @@ -91,6 +91,28 @@ Observable signs that the skill is being violated. Useful during code review and ### Verification The exit criteria. A checklist the agent uses to confirm the skill's process is complete. Every checkbox should be verifiable with evidence (test output, build result, screenshot, etc.). +## Required vs Recommended + +Required: + +- A skill directory under `skills/` +- A `SKILL.md` file +- Valid frontmatter with `name` and `description` + +Recommended for new contributions: + +- Follow the standard section anatomy above unless there is a clear reason not to +- `# Skill Title` +- `## Overview` +- `## When to Use` +- A clearly named workflow section such as `## Process`, `## The Workflow`, or `## Steps` +- `## Common Rationalizations` +- `## Red Flags` +- `## Verification` +- Add supporting files only when they keep `SKILL.md` focused + +This is the common project pattern, but not every existing skill uses the exact same section names or layout. + ## Supporting Files Create supporting files only when: