refactor: write-skill phase 1 refactor — grill, implementation, lessons

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>

.agents/skills/write-skill/SKILL-TEMPLATE.md

@@ -0,0 +1,88 @@
+---
+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>