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>
89 lines
3.8 KiB
Markdown
89 lines
3.8 KiB
Markdown
---
|
|
name: <skill-name>
|
|
# description: routing-only field — loaded at startup for every skill scan to decide whether
|
|
# to activate this skill. Write in imperative phrasing ("Use when X", not "This skill does X").
|
|
# Must cover: (1) what the skill does, (2) when to invoke it, (3) negative triggers — what
|
|
# adjacent tasks must NOT activate it. No behavioral or role framing; that belongs in the body.
|
|
# Max 1024 characters. The `when:` detail that lived here previously now lives in META.md.
|
|
# Example: "Use when the user wants to create a new SKILL.md file or convert a placeholder to
|
|
# canonical format. Do NOT use when updating an existing well-formed skill — use upgrade-skill."
|
|
description: <trigger description>
|
|
metadata:
|
|
category: <category — see CATEGORIES.md>
|
|
# allowed-tools: <add only when the skill has a narrow, well-defined tool surface; omit otherwise>
|
|
---
|
|
|
|
<requirements>
|
|
|
|
## Required inputs
|
|
|
|
<!-- List each required input as a bullet: name, what it is, how the agent obtains it.
|
|
Negative trigger cases are NOT listed here — the agent proposes them during trigger testing.
|
|
Example:
|
|
- **Skill name** — kebab-case slug; inferred from user description if not stated explicitly, ask if ambiguous
|
|
- **Existing SKILL.md path** — for placeholder conversions only; read before writing -->
|
|
|
|
- **<Input name>** — <description; how obtained>
|
|
|
|
## Constraints
|
|
|
|
<!-- One rule per bullet. State the boundary condition inline. Plain English, no jargon.
|
|
Do not include a constraint about body section structure — the template enforces that.
|
|
Example:
|
|
- Frontmatter has three fields only: `name`, `description`, and `metadata.category` — add `allowed-tools` only when the skill has a narrow, well-defined tool surface
|
|
- Body ≤500 lines — move anything longer into separate files in the skill directory -->
|
|
|
|
- <constraint>
|
|
|
|
</requirements>
|
|
|
|
<steps>
|
|
|
|
## Process
|
|
|
|
<!-- Numbered steps with a bold action label. Short, direct sentences — state what to do and
|
|
what happens as a result. Call out hard gates explicitly (steps that block all progress
|
|
until satisfied). No preamble, no meta-commentary about the steps themselves.
|
|
Example:
|
|
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. -->
|
|
|
|
1. **<Step name>.** <what to do and what happens as a result>
|
|
|
|
## Output format
|
|
|
|
<!-- Describe the files or artifacts produced. Include paths and how they are created
|
|
(copy-fill from template, generated, etc.). State the template used for structured file output.
|
|
Example:
|
|
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` -->
|
|
|
|
<description of output>
|
|
|
|
</steps>
|
|
|
|
<checks>
|
|
|
|
## Failure handling
|
|
|
|
<!-- One bullet per failure mode. Lean — no overlap with constraints or process.
|
|
Format: condition — action.
|
|
Example:
|
|
- Template file missing — stop, report the path searched, do not write from memory
|
|
- `write-eval` fails or is unavailable — flag, do not mark the skill complete -->
|
|
|
|
- <failure condition> — <what to do>
|
|
|
|
## Self-check
|
|
|
|
<!-- Verifiable checklist the agent runs before declaring the skill complete.
|
|
Each item must be checkable, not aspirational.
|
|
Example:
|
|
- [ ] Overlap check completed before any content was written
|
|
- [ ] Trigger description tested against all three cases — all passed before body content was written -->
|
|
|
|
- [ ] <check>
|
|
|
|
</checks>
|