Defame1297
e3cc0b65f4
Complete 2026-05-18 workstream for write-skill refactor (issue 0018 phase 1). Grill output (handoff in docs/issues/0018-factory-write-skill.md): - 6-section standard replaces 8: Role and When/When not dropped (not in agentskills.io spec; description carries trigger scope and negatives) - Frontmatter reduced to 3 fields; provenance moves to META.md (progressive disclosure — not loaded at every skill scan) - SKILL-TEMPLATE.md and META-TEMPLATE.md as authoritative copy-fill artifacts - CATEGORIES.md as self-contained category reference in skill directory - Copy and fill explicitly split into separate process steps for determinism New files in .agents/skills/write-skill/: - SKILL-TEMPLATE.md — 6-section template with XML blocks and inline examples per section - META-TEMPLATE.md — provenance schema with inline-commented YAML; source vs references explicit - CATEGORIES.md — self-contained category table (no runtime dependency on factory docs) - META.md — write-skill's own provenance (v1.1, self-authored) SKILL.md rewritten: 8-step process, XML blocks (<requirements>, <steps>, <checks>), 3-field frontmatter, copy-then-fill steps explicit. Supporting docs updated: - skill-implementation-workflow.md: SKILL-TEMPLATE.md as authoritative template; source:/references: now reference META.md; when: marked resolved - factory-integration-decisions.md: frontmatter spec corrected - ROADMAP.md: authoring standard description updated - CONTEXT.md: Source field entry corrected; META.md added to glossary - docs/spec/overview.md: 2026-05-18 refactor entry added - docs/issues/0018: handoff status updated; acceptance criteria marked complete LESSONS.md: 3 entries added in grill session (cargo-culted body sections, provenance fields in frontmatter, copy-fill determinism) + 1 from implementation (planning meta-commentary does not belong in deployed artifacts). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
85 lines
5.0 KiB
Markdown
85 lines
5.0 KiB
Markdown
---
|
|
name: write-skill
|
|
description: Use when the user wants to author a new skill file or convert an existing placeholder to the canonical authoring standard. Triggers: "write a new skill for X", "create a SKILL.md that does Y", "build a skill to handle Z". Do NOT use when fixing or updating an existing well-formed skill (use upgrade-skill), running existing evals (use write-eval), refactoring application code, or writing documentation for non-skill artifacts.
|
|
metadata:
|
|
category: factory
|
|
---
|
|
|
|
<requirements>
|
|
|
|
## Required inputs
|
|
|
|
- **Skill name** — kebab-case slug; inferred from user description if not stated explicitly, ask if ambiguous
|
|
- **Category** — from the category table in `CATEGORIES.md`; ask if unclear
|
|
- **Purpose + use cases** — what the skill does and what tasks it handles; source for the trigger description
|
|
- **For placeholder conversions:** existing SKILL.md path — read before writing
|
|
|
|
Negative trigger cases are NOT a required input. The agent proposes them based on the skill's purpose and adjacent skills found during the overlap scan. The user confirms or refines before trigger testing begins.
|
|
|
|
## Constraints
|
|
|
|
- Write two files for every skill: `SKILL.md` at `.agents/skills/<name>/SKILL.md` and `META.md` alongside it
|
|
- Frontmatter has three fields only: `name`, `description`, and `metadata.category` — add `allowed-tools` only when the skill has a narrow, well-defined tool surface
|
|
- Keep the body under 500 lines — move anything longer into separate files in the skill directory
|
|
- Use XML tags only when the body has three or more logical sections and exceeds 500 tokens — default to plain prose
|
|
- Test the trigger description against all three cases — explicit, implicit, negative — before writing any body content. Hard gate: a failed case means revise and retest, not proceed
|
|
- Check for overlapping skills in `.agents/skills/` before writing anything — if overlap is found, surface it and wait for direction
|
|
- For placeholder conversions: read the existing SKILL.md first and remove all stale or outdated content
|
|
|
|
</requirements>
|
|
|
|
<steps>
|
|
|
|
## Process
|
|
|
|
1. **Scan for overlap.** Check `.agents/skills/` for skills with similar purpose or trigger phrases. If overlap is found, surface it and wait for explicit direction — do not continue.
|
|
|
|
2. **Grill.** Run a focused grill to reach shared understanding of: skill name, category, purpose, and use cases. One question at a time, with a recommendation for each.
|
|
|
|
3. **Write and test the trigger description.** Draft `description:`. Propose negative trigger cases based on the skill's purpose and adjacent skills — get explicit user confirmation before running tests. Test all three cases and show per-case PASS/FAIL. A failed case means revise and retest — do not proceed.
|
|
|
|
4. **Walk through each section.** For each section in `SKILL-TEMPLATE.md`: propose content, state where it comes from, present alternatives if they exist. Wait for explicit human confirmation before moving to the next section.
|
|
|
|
5. **Copy both templates.** Copy `SKILL-TEMPLATE.md` to `.agents/skills/<name>/SKILL.md`. Copy `META-TEMPLATE.md` to `.agents/skills/<name>/META.md`. Do not modify content yet — copy first, fill second.
|
|
|
|
6. **Fill both files.** Fill in the copied `SKILL.md` with confirmed section content. Fill in the copied `META.md` with version, updated date, when, source (if applicable), and references (if applicable).
|
|
|
|
7. **Invoke `write-eval`.** Do not mark the skill complete without an eval file.
|
|
|
|
8. **Prompt for HITL.** Ask the user to open a fresh session, trigger the skill, and confirm output before committing.
|
|
|
|
## Output format
|
|
|
|
Two files produced for every skill:
|
|
|
|
- `SKILL.md` — copy-filled from `SKILL-TEMPLATE.md` at `.agents/skills/<name>/SKILL.md`
|
|
- `META.md` — copy-filled from `META-TEMPLATE.md` at `.agents/skills/<name>/META.md`
|
|
|
|
For placeholder conversions, `SKILL.md` replaces the existing file entirely — no partial edits.
|
|
|
|
</steps>
|
|
|
|
<checks>
|
|
|
|
## Failure handling
|
|
|
|
- Template file missing — stop, report the path searched, do not write from memory
|
|
- Existing SKILL.md not found for a placeholder conversion — stop, report the path searched
|
|
- `write-eval` fails or is unavailable — flag, do not mark the skill complete
|
|
|
|
## Self-check
|
|
|
|
- [ ] Overlap check completed before any content was written
|
|
- [ ] Trigger description tested against all three cases — all passed before body content was written
|
|
- [ ] Negative trigger cases confirmed by user before testing
|
|
- [ ] Each section confirmed explicitly by user before SKILL.md was written
|
|
- [ ] SKILL.md copy-filled from `SKILL-TEMPLATE.md` at correct path
|
|
- [ ] `META.md` copy-filled from `META-TEMPLATE.md` at correct path
|
|
- [ ] Frontmatter contains only `name`, `description`, and `metadata.category` (plus `allowed-tools` if applicable)
|
|
- [ ] Body is under 500 lines
|
|
- [ ] For placeholder conversions: existing files read, all stale content removed, old directory deleted if renamed
|
|
- [ ] `write-eval` invoked — eval file exists at correct path
|
|
- [ ] User prompted for HITL behavioral test
|
|
|
|
</checks>
|