131 lines
7.3 KiB
Markdown
131 lines
7.3 KiB
Markdown
---
|
|
name: write-skill
|
|
description: Write a new skill for X, create a SKILL.md that does Y, build a skill to handle Z. Use when the user wants to author a new skill file or convert an existing placeholder skill to the canonical authoring standard. Do NOT use when the user wants to fix or update an existing well-formed skill, run existing evals, refactor application code, or write documentation for non-skill artifacts.
|
|
version: "1.0"
|
|
updated: 2026-05-17
|
|
when: invoked by explicit trigger ("write a new skill for X", "create a SKILL.md that does Y") or implicit request to author a skill file or convert a placeholder to canonical format
|
|
metadata:
|
|
category: factory
|
|
references:
|
|
- https://agentskills.io/skill-creation/optimizing-descriptions
|
|
- https://agentskills.io/skill-creation/best-practices
|
|
---
|
|
|
|
## Role
|
|
|
|
You are a skill author producing complete, correctly-structured SKILL.md files for an AI agent skills library, following the agentskills.io open standard with project-specific extensions.
|
|
|
|
## When to use / When not to use
|
|
|
|
**Use when:**
|
|
- User wants to create a new skill ("write a skill for X", "build a skill that does Y")
|
|
- User wants to convert a placeholder or non-standard SKILL.md to canonical format
|
|
|
|
**Do not use when:**
|
|
- User wants to fix or update an existing well-formed skill → `upgrade-skill`
|
|
- User wants to run or evaluate existing skills → `write-eval`
|
|
- User wants to refactor application code → `implement/refactor`
|
|
- User wants to write docs for a non-skill artifact → `write-docs`
|
|
- User asks for a workflow, ADR, or PRD — dedicated skills exist for those
|
|
|
|
## Required inputs
|
|
|
|
- **Skill name** — kebab-case slug; inferred from description if not stated explicitly
|
|
- **Category** — one of: `design|factory|implement|test|review|deploy|operate|cross-cutting|iac`
|
|
- **Purpose + use cases** — what the skill does and what tasks it handles; source for the trigger description
|
|
- **When-not criteria** — adjacent tasks this skill must NOT activate on; needed for the negative trigger test
|
|
- For placeholder conversions: **existing SKILL.md path** — read before writing
|
|
|
|
## Constraints
|
|
|
|
- Output path: `.agents/skills/<skill-name>/SKILL.md`
|
|
- Frontmatter must include: `name`, `description`, `version`, `updated`, `when`, `metadata.category`; `source:` only if upstream content adopted; `references:` only if external citations used
|
|
- Body must contain all 8 sections in order: Role, When to use / When not to use, Required inputs, Constraints, Process, Output format, Failure handling, Self-check
|
|
- Trigger description must be tested against 3 cases (explicit, implicit, negative) before any body content is written — do not proceed if any case fails
|
|
- Body ≤500 lines; XML tags only if ≥3 logical sections and 500+ tokens
|
|
- Check for overlapping skills in `.agents/skills/` before writing — flag overlap and get direction before continuing
|
|
- For placeholder conversions: read existing SKILL.md before writing; remove all dead Pocock references (`setup-matt-pocock-skills`, `AGENT-BRIEF.md`, `OUT-OF-SCOPE.md`)
|
|
- Show proposed structure and confirm with user before writing the file
|
|
- Do not mark a skill complete until both the eval and the HITL behavioral test are done
|
|
|
|
## Process
|
|
|
|
1. **Gather requirements.** If not provided upfront, ask: what does the skill do, what tasks does it handle, what should it NOT activate on, what category, is this a new skill or a placeholder conversion?
|
|
|
|
2. **Check for overlap.** Scan `.agents/skills/` for existing skills with similar purpose or trigger phrases. If overlap found, surface the conflicting skill name and description — get explicit direction before continuing.
|
|
|
|
3. **Draft the trigger description.** Write the `description:` field from the gathered requirements.
|
|
|
|
4. **Test the trigger description** against three cases before writing anything else:
|
|
- Explicit: a query using the trigger phrase directly — must activate
|
|
- Implicit: a query describing the task without naming it — must activate
|
|
- Negative: an adjacent task from the when-not criteria — must NOT activate
|
|
|
|
If any case fails, propose a revised description and re-test. Do not proceed to the body until all three pass.
|
|
|
|
5. **Walk through each body section.** For each of the 8 sections: state the proposed content and where it comes from, present alternatives if they exist. Get confirmation before moving to the next section. Do not write the file until all sections are confirmed.
|
|
|
|
6. **Write the SKILL.md** at `.agents/skills/<skill-name>/SKILL.md`. For placeholder conversions: read the existing file first, carry forward content worth keeping, remove dead references.
|
|
|
|
7. **Invoke `write-eval`.** Run `write-eval` to produce the eval at `.agents/evals/<category>/<skill-name>/eval.yaml`. Do not mark the skill complete until the eval file exists.
|
|
|
|
8. **Prompt for HITL behavioral test.** Remind the user to open a fresh session, invoke the skill with its trigger phrase, and verify the output meets the authoring standard before committing. The skill is not done until this test passes.
|
|
|
|
## Output format
|
|
|
|
```markdown
|
|
---
|
|
name: <skill-name>
|
|
description: <tested trigger description>
|
|
version: "1.0"
|
|
updated: YYYY-MM-DD
|
|
when: <when this skill is invoked>
|
|
metadata:
|
|
category: <category>
|
|
source: # omit if self-authored
|
|
- repo: org/repo
|
|
commit: <sha>
|
|
files:
|
|
- path/to/file.md # what was taken
|
|
updated: YYYY-MM-DD
|
|
references: # omit if no external citations
|
|
- <URL or citation>
|
|
---
|
|
|
|
## Role
|
|
## When to use / When not to use
|
|
## Required inputs
|
|
## Constraints
|
|
## Process
|
|
## Output format
|
|
## Failure handling
|
|
## Self-check
|
|
```
|
|
|
|
For placeholder conversions, the output replaces the existing file entirely — no partial edits.
|
|
|
|
## Failure handling
|
|
|
|
- **Skill name missing or ambiguous:** ask before proceeding — do not invent a name
|
|
- **Category not provided:** ask before computing the output path — do not guess
|
|
- **Trigger description fails a test case:** propose a revised description and re-test; do not proceed to body content until all three pass
|
|
- **Overlap found with existing skill:** surface the conflict (name + description of the conflicting skill), ask for direction — do not continue autonomously
|
|
- **Existing SKILL.md not found for a placeholder conversion:** stop and report the path searched; do not write based on assumptions
|
|
- **Confirmed sections would produce a body exceeding 500 lines:** flag before writing, ask which sections to trim
|
|
- **`write-eval` fails or is unavailable:** flag to the user — do not mark the skill complete without an eval
|
|
|
|
## Self-check
|
|
|
|
- [ ] All 8 body sections present in order
|
|
- [ ] Trigger description tested against all 3 cases — all pass before body was written
|
|
- [ ] Overlap check completed against `.agents/skills/`
|
|
- [ ] Output path correct: `.agents/skills/<skill-name>/SKILL.md`
|
|
- [ ] Frontmatter complete: `name`, `description`, `version`, `updated`, `when`, `metadata.category` present
|
|
- [ ] `source:` present only if upstream content adopted; absent if self-authored
|
|
- [ ] `references:` present only if external citations used; absent otherwise
|
|
- [ ] Body ≤500 lines
|
|
- [ ] Proposed structure confirmed by user before file was written
|
|
- [ ] For placeholder conversions: dead Pocock references removed
|
|
- [ ] `write-eval` invoked — eval.yaml exists at correct path
|
|
- [ ] User prompted for HITL behavioral test
|