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>
2026-05-18 06:48:46 +00:00
parent 2631142a0e
commit e3cc0b65f4
12 changed files with 593 additions and 127 deletions
--- a/docs/ROADMAP.md
+++ b/docs/ROADMAP.md
@@ -33,7 +33,7 @@ A parallel workstream (not a numbered chunk) that runs alongside the chunk seque
 |---|---|---|
 | ✅ 1 | Repo skeleton + `install.sh` — structure in place, Claude Code wired up | Nothing else can be built without the structure and install working |
 | ✅ 2 | Core instructions — `coding.md`, `git.md` (incl. conventional commits), `testing.md`; communication rules in `providers/claude-code/CLAUDE.md` always-on section; retire `global.md`; migrate `docs/` to subdirectory-by-type naming | Instructions are the foundation everything else references; commit convention and doc naming must be in place before history accumulates |
-| ⏳ 3 | Skills library rebuild — the 12 existing skills are first-draft placeholders that predate the factory research; all are rebuilt or replaced. **Target library:** `docs/research/ai-coding-factory/ai-coding-factory-skills-index.md` is the canonical build reference — use it directly for each skill's trigger description, constraints, and category. Core categories: roles (6), design (3), factory (7 meta-skills — entirely new, high priority), implement (4 incl. tdd multi-file), test (3), review (4), deploy (4), operate (4), cross-cutting (4). Global optional: IaC (7) and Gitea (3) — scope defined in Chunk 3 PRD. **Naming convention:** the skills-index uses `category/skill-name` notation (e.g., `design/grill-me`) for identification only; actual paths are flat per ADR-0009 (`grill-me/SKILL.md`), category expressed in SKILL.md frontmatter. **Authoring standard:** frontmatter (`name`, `description`, `version`, `updated`, `metadata.category`), role, when/when-not, required inputs, constraints, process, output format, failure handling — per `ai-coding-factory-implementation-guidance.md` Section 10. **Process per skill:** check skills-index for trigger description and constraints → check implementation guidance Section 4–5 for framework sourcing → research/inspect open-source implementations → implement. Delete `ai-coding-factory-skills-index.md` when all skills exist. **Infrastructure complete**: 12 skills deployed to `~/.agents/skills/` via `install.sh`; provider adapter pattern in place. | Skills are the most immediately useful output; the rebuild is necessary because existing skills predate the authoring standard and the factory research |
+| ⏳ 3 | Skills library rebuild — the 12 existing skills are first-draft placeholders that predate the factory research; all are rebuilt or replaced. **Target library:** `docs/research/ai-coding-factory/ai-coding-factory-skills-index.md` is the canonical build reference — use it directly for each skill's trigger description, constraints, and category. Core categories: roles (6), design (3), factory (7 meta-skills — entirely new, high priority), implement (4 incl. tdd multi-file), test (3), review (4), deploy (4), operate (4), cross-cutting (4). Global optional: IaC (7) and Gitea (3) — scope defined in Chunk 3 PRD. **Naming convention:** the skills-index uses `category/skill-name` notation (e.g., `design/grill-me`) for identification only; actual paths are flat per ADR-0009 (`grill-me/SKILL.md`), category expressed in SKILL.md frontmatter. **Authoring standard:** see `SKILL-TEMPLATE.md` in `.agents/skills/write-skill/` (authoritative). Frontmatter: `name`, `description`, `metadata.category` only — provenance fields (`version`, `updated`, `when`, `source`, `references`) live in `META.md` per `META-TEMPLATE.md`. Body: 6 sections (Required inputs, Constraints, Process, Output format, Failure handling, Self-check) — Role and When/When not dropped per agentskills.io spec. **Process per skill:** check skills-index for trigger description and constraints → check implementation guidance Section 4–5 for framework sourcing → research/inspect open-source implementations → implement. Delete `ai-coding-factory-skills-index.md` when all skills exist. **Infrastructure complete**: 12 skills deployed to `~/.agents/skills/` via `install.sh`; provider adapter pattern in place. | Skills are the most immediately useful output; the rebuild is necessary because existing skills predate the authoring standard and the factory research |
 | 4 | Workflows — formalize the workstream workflow (kick-off types → grill → artifact → issues → implement → QA → commit); feature, bug, architecture, improvement, feedback patterns. **Prerequisite:** WorkflowContext schema (what each skill in a chain receives and returns) must be designed before any workflow skill is written; `docs/spec/` must exist (implement-feature constraint: update spec in same PR as behavior change) | Higher-level patterns built on top of a working skills foundation; grill feedback intake design before starting |
 | 5 | Agents — role skills (Architect, Developer, Reviewer, Security, QA, Ops) in `.agents/skills/` with `category: roles`; `core/agents/` for provider-agnostic subagent definitions needing isolated execution context (`context: fork`), translated to `.claude/agents/` by adapter; cross-project orchestration agents as use case | Role skills benefit from workflow patterns being established first; subagent definitions require the skills library to be stable |
 | 6 | Sync + project init tooling — `sync.sh` and `init-project.sh` | Tooling only makes sense once there is content worth syncing and scaffolding |
--- a/docs/issues/0018-factory-write-skill.md
+++ b/docs/issues/0018-factory-write-skill.md
@@ -70,12 +70,19 @@ Follow the per-skill workflow defined in `docs/notes/skill-implementation-workfl
 - [ ] **HITL:** human reviews SKILL.md and eval before committing
 - [x] Per-skill process followed for both phases (see `docs/notes/skill-implementation-workflow.md`)
 - [x] Trigger description for each skill tested against explicit, implicit, and negative queries before body written
- [x] `when:` frontmatter field present in both SKILL.md files
- [x] `source:` and `references:` fields correctly populated or absent
+- ~~[x] `when:` frontmatter field present in both SKILL.md files~~ — superseded by refactor: `when:` moves to META.md
+- ~~[x] `source:` and `references:` fields correctly populated or absent~~ — superseded by refactor: both move to META.md
 - [x] eval.yaml for each skill contains all 5 required test types
 - [x] Body ≤500 lines for each skill
 - [x] Phase 2 (`write-docs`) is the first skill produced end-to-end by the factory
 - [x] `docs/spec/overview.md` updated to reflect both skills deployed
+- [x] **Refactor:** `.agents/skills/write-skill/SKILL-TEMPLATE.md` exists — authoritative 6-section template with XML blocks
+- [x] **Refactor:** `.agents/skills/write-skill/META-TEMPLATE.md` exists — YAML block with inline-commented source schema
+- [x] **Refactor:** `.agents/skills/write-skill/CATEGORIES.md` exists — category table copied from factory-integration-decisions.md
+- [x] **Refactor:** `.agents/skills/write-skill/META.md` exists — write-skill's own provenance (self-authored, no source, references agentskills.io)
+- [x] **Refactor:** `write-skill/SKILL.md` rewritten — 6 sections, XML blocks, 3-field frontmatter, no Role, no When/When not
+- [x] **Refactor:** `docs/notes/skill-implementation-workflow.md` updated — references SKILL-TEMPLATE.md instead of embedding inline template
+- [ ] **Refactor HITL:** open fresh session, invoke "write a new skill for X", verify: overlap scan first, grill to gather, agent proposes negative cases, per-section explicit confirmation, copy-then-fill both files, write-eval invoked, HITL prompted
 - [ ] **Phase 3:** `/grill-me` session completed; grill output committed
 - [ ] **Phase 3:** `docs/notes/doc-convention.md` written and committed
 - [ ] **Phase 3:** `write-docs` SKILL.md output format updated to reference the convention (via `upgrade-skill` if substantive)
@@ -134,3 +141,346 @@ Follow the per-skill workflow defined in `docs/notes/skill-implementation-workfl
 **Open threads:**
 - Documentation convention: scoped to Phase 3 of this issue — see "What to build" above. `write-docs` output format section will be updated once the convention is defined.
 - HITL behavioral test: see above.
+
+---
+
+## Handoff — Phase 1 Refactor (write-skill)
+
+**Status:** implementation complete — pending HITL behavioral test
+
+**Files produced:**
+- `.agents/skills/write-skill/SKILL.md` — rewritten (6 sections, XML blocks, 3-field frontmatter)
+- `.agents/skills/write-skill/SKILL-TEMPLATE.md` — authoritative 6-section template with inline examples
+- `.agents/skills/write-skill/META-TEMPLATE.md` — provenance schema with inline-commented YAML
+- `.agents/skills/write-skill/CATEGORIES.md` — self-contained category table
+- `.agents/skills/write-skill/META.md` — write-skill's own provenance (v1.1, self-authored)
+
+**Context:** the Phase 1 write-skill was hand-authored as a bootstrap skill and does not follow the quality bar it is supposed to produce. A full grill session (2026-05-18) redesigned it from the ground up. The implementation session should produce all four files and update the authoring standard.
+
+---
+
+### What changes and why
+
+The current write-skill is heavy, duplicates the agentskills.io spec incorrectly, embeds its own output template inline (28 lines), and loads provenance metadata that is never used at runtime. The refactor makes it:
+
+- **Modular** — templates extracted to human-usable files; provenance separated into META.md
+- **Spec-compliant** — frontmatter reduced to the four fields agentskills.io actually defines
+- **Token-optimised** — provenance not loaded at runtime (progressive disclosure)
+- **Clearer** — plain English constraints, numbered steps in improve-codebase-architecture tone, XML grouping
+
+---
+
+### New file structure
+
+```
+.agents/skills/write-skill/
+├── SKILL.md              ← rewritten (6 sections, XML-structured, lean frontmatter)
+├── SKILL-TEMPLATE.md     ← NEW: authoritative template for new skill bodies (copy-fill)
+├── META-TEMPLATE.md      ← NEW: authoritative template for new skill META.md files (copy-fill)
+├── CATEGORIES.md         ← NEW: category table (self-contained reference, not a runtime dependency)
+└── META.md               ← NEW: write-skill's own provenance record
+```
+
+---
+
+### Frontmatter — new spec
+
+**Before:**
+```yaml
+name: write-skill
+description: ...
+version: "1.0"
+updated: 2026-05-17
+when: ...
+metadata:
+  category: factory
+references:
+  - ...
+```
+
+**After:**
+```yaml
+name: write-skill
+description: ...
+metadata:
+  category: factory
+```
+
+`version`, `updated`, `when`, `source`, `references` all move to `META.md`. `allowed-tools` added only when the skill has a narrow, well-defined tool surface — write-skill does not, so omit.
+
+**Rationale:** agentskills.io spec defines only `name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools` as frontmatter fields. Everything else is a project extension. Project extensions that are audit/provenance records (not routing or runtime data) belong in META.md where they are not loaded on every skill scan.
+
+---
+
+### META.md — content and schema
+
+META.md is a markdown file containing a single YAML code block. Content for write-skill:
+
+```yaml
+version: "1.1"
+updated: 2026-05-18
+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 an existing placeholder to the canonical authoring standard
+
+# source: omitted — self-authored original; no upstream content adopted
+# Absence of source means self-authored. If content is adopted from upstream,
+# add a source entry per the META-TEMPLATE.md schema.
+
+references:
+  - https://agentskills.io/specification.md
+  - https://agentskills.io/skill-creation/optimizing-descriptions
+```
+
+**The source vs references distinction — make this explicit in META-TEMPLATE.md:**
+
+- `source:` — content you **adopted**. You read upstream code or docs, took text or logic, and incorporated it. Tracked at commit-level (repo slug, commit SHA, files with inline comments, updated date) so upgrade-skill can flag when upstream changed. **Absence means self-authored original.**
+- `references:` — content you **cited**. It informed the skill but you took nothing verbatim. URLs, papers, standards, documentation.
+
+Example: if you adapted Pocock's grill-me SKILL.md, that is `source:`. If you read agentskills.io best-practices and followed principles without copying text, that is `references:`.
+
+---
+
+### Description field — new requirements
+
+Per agentskills.io spec and the optimizing-descriptions guide:
+- **Routing only** — what the skill does, when to use it, negative triggers
+- **Max 1024 characters**
+- **Imperative phrasing** — "Use when..." not "This skill does..."
+- **Include negative triggers** — the spec explicitly recommends this for preventing false activation on adjacent tasks
+- **No behavioral/role framing** — that is the body's job
+
+The `when:` frontmatter field moves to META.md. Any information it contained that is relevant to routing (trigger context, invocation conditions) must be incorporated into `description:`. The current description already covers most of this — review and ensure nothing from `when:` is lost.
+
+---
+
+### Dropped sections
+
+**Role** — removed from the authoring standard entirely.
+
+Rationale: not defined by agentskills.io spec. The three best-performing reference skills (grill-with-docs, tdd, improve-codebase-architecture) all work without it. The description + process carry the behavioral framing adequately. Chunk 5 agents will handle cognitive mode at session level. When Role is just a restatement of the description, it is dead weight (governance principle: minimum tokens to accomplish the task accurately).
+
+**When to use / When not to use** — removed from the authoring standard.
+
+Rationale: agentskills.io spec and the optimizing-descriptions guide both state that the description field is the correct place for trigger scope and negative cases. A separate body section repeating the same information violates DRY and the progressive disclosure principle (the description is read at startup; a body section is read only after activation — by which point the routing decision has already been made).
+
+---
+
+### Authoring standard update
+
+Body sections drop from 8 to 6, in this order:
+
+1. Required inputs
+2. Constraints
+3. Process
+4. Output format
+5. Failure handling
+6. Self-check
+
+`SKILL-TEMPLATE.md` becomes the authoritative template, superseding the inline template currently embedded in `docs/notes/skill-implementation-workflow.md`. Update that document to reference `SKILL-TEMPLATE.md` instead of duplicating it — single source of truth.
+
+---
+
+### XML structure
+
+Three blocks wrapping the 6 sections:
+
+```
+<requirements>
+  ## Required inputs
+  ## Constraints
+</requirements>
+
+<steps>
+  ## Process
+  ## Output format
+</steps>
+
+<checks>
+  ## Failure handling
+  ## Self-check
+</checks>
+```
+
+Permitted by factory rule: body will be >500 tokens with ≥3 logical sections. Named for plain-language clarity following grill-with-docs style.
+
+---
+
+### Required inputs (confirmed content)
+
+- **Skill name** — inferred from description if not stated explicitly; ask if ambiguous
+- **Category** — from the category table in `.agents/skills/write-skill/CATEGORIES.md` (see below)
+- **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 (confirmed content)
+
+Write in plain English, one rule per bullet, boundary condition stated inline:
+
+- 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
+
+**Do not include a constraint about body section structure — the template enforces that mechanically.**
+
+---
+
+### Process (confirmed content)
+
+Write in improve-codebase-architecture tone: short numbered steps, action verbs, side effects stated inline. No bureaucratic padding.
+
+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.
+
+**Open thread — research step:** a source discovery, source review, and governance conflict check step (per `docs/notes/skill-implementation-workflow.md` steps 1–3) belongs between step 1 (overlap scan) and step 2 (grill). Add this once the factory has enough maturity to support it. This is deliberately deferred, not forgotten.
+
+Note: process now has 8 steps (copy and fill are explicitly split at steps 5 and 6).
+
+---
+
+### Output format (confirmed content)
+
+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.
+
+---
+
+### Failure handling (confirmed content — lean, no overlap with constraints or process)
+
+- 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 (confirmed content)
+
+- [ ] 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
+
+---
+
+### SKILL-TEMPLATE.md — what to produce
+
+A complete, correctly-structured skeleton for a new skill body. Contains:
+- Correct frontmatter block (3 fields only: name, description, metadata.category)
+- All 6 body sections as `## ` headers in correct order
+- Three XML blocks wrapping sections as documented above
+- Placeholder comments in each section explaining what goes there and from which source
+- No prose content — placeholders only
+
+The template is the authoritative structure reference. If the section structure changes, update the template — not the skill body.
+
+---
+
+### CATEGORIES.md — what to produce
+
+A reference file at `.agents/skills/write-skill/CATEGORIES.md` containing the canonical category table. The skill is self-contained — it must not reference `docs/notes/factory-integration-decisions.md` at runtime. The table is copied verbatim from that document:
+
+| Category | Scope |
+|---|---|
+| `design` | grill-me, grill-with-docs, to-prd, prototype, architecture-review |
+| `plan` | to-issues, triage |
+| `implement` | tdd, diagnose, implement-feature, refactor, write-docs |
+| `test` | write-tests, generate-test-data, review-test-coverage |
+| `review` | improve-codebase-architecture, code-review, security-review, pr-description, changelog-entry |
+| `deploy` | write-ci-pipeline, write-deployment-config, write-ai-review-workflow, deployment-checklist |
+| `operate` | write-runbook, incident-diagnosis, post-mortem, inspect-deployment |
+| `iac` | write-ansible-role, write-terraform-module, write-k8s-manifest, write-docker-compose, proxmox-vm-spec, iac-security-review, write-molecule-test |
+| `cross-cutting` | zoom-out, caveman, session-handoff, governance-check, git-guardrails, git-commit-message |
+| `factory` | write-skill, write-adr, write-workflow, write-eval, validate-skill, upgrade-skill, write-issue-spec |
+| `roles` | architect, developer, reviewer, security, qa, ops — Chunk 5 |
+
+---
+
+### META-TEMPLATE.md — what to produce
+
+A YAML code block inside a markdown file. The template must be self-explanatory — a reader should understand every field without consulting any other file. Produce exactly this structure with inline comments preserved:
+
+```yaml
+version: "1.0"          # increment on meaningful changes to the skill
+updated: YYYY-MM-DD     # ISO date of last update
+
+# when: describes when this skill is loaded — the full trigger context.
+# More detail than the description field; not used for routing.
+when: <describe the invocation conditions here>
+
+# source: tracks content you ADOPTED from an upstream repo.
+# Adopt = you read someone else's code or docs and incorporated text or logic directly.
+# Omit this field entirely if the skill is self-authored — absence means original work.
+# Present only when content was actually taken, tracked at commit-level for upgrade reviews.
+source:
+  - repo: org/repo-name          # GitHub slug — no URL, slug is stable and searchable
+    commit: <full SHA>           # exact commit reviewed at time of adoption
+    files:
+      - path/to/file.md          # inline comment: what was taken from this file
+      - path/to/other.md         # inline comment: what was taken from this file
+    updated: YYYY-MM-DD          # date this source entry was last reviewed
+
+# references: tracks content you CITED but did not adopt verbatim.
+# Cite = you read it and it informed the skill, but nothing was copied or adapted.
+# Examples: a spec you followed, a paper that shaped the approach, external documentation.
+# Distinct from source: source = took content; references = informed by content.
+references:
+  - https://example.com/relevant-doc
+```
+
+---
+
+### Open threads for future sessions
+
+1. **Research step** — add source discovery, source review, and governance conflict check between overlap scan and grill once the factory supports it (documented above in Process)
+
+2. **upgrade-skill** — when built, should reference `write-skill/SKILL-TEMPLATE.md` and `write-skill/META-TEMPLATE.md` rather than duplicating them. If templates being "owned" by write-skill feels awkward for upgrade-skill, move them to a shared factory location at that point. Do not act on this now — the templates' location is reversible and upgrade-skill doesn't exist yet.
+
+3. **skill-implementation-workflow.md** — update to reference `SKILL-TEMPLATE.md` as the authoritative template instead of embedding its own inline copy. Single source of truth.
+
+4. **write-eval** — follows the old 8-section standard. When write-skill is updated, write-eval should be reviewed and updated to the new 6-section standard in a follow-on session.
+
+5. **All Chunk 3 skills** — any skills produced by write-skill going forward follow the new 6-section standard with META.md. Skills already produced (write-docs) should be reviewed against the new standard in issue 0028 (chunk 3 closure).
+
+---
+
+### Implementation order for next session
+
+1. Read: `CONTEXT.md`, this issue file, current `.agents/skills/write-skill/SKILL.md`
+2. Write `META-TEMPLATE.md` first — the source block schema with inline YAML comments must be explicit here before anything else references it
+3. Write `SKILL-TEMPLATE.md` — 6 sections, XML blocks (`<requirements>`, `<steps>`, `<checks>`), correct frontmatter (3 fields only)
+4. Write `CATEGORIES.md` — copy the category table from `docs/notes/factory-integration-decisions.md` verbatim
+5. Rewrite `SKILL.md` — follow the new structure (write-skill does not copy-fill its own template; it models the same structure directly)
+6. Write write-skill's own `META.md` — `version: "1.1"`, `updated: 2026-05-18`, no `source` (self-authored original), `references` cites agentskills.io spec and optimizing-descriptions
+7. Update `docs/notes/skill-implementation-workflow.md` — reference `SKILL-TEMPLATE.md` instead of embedding its own inline template copy
+8. Update acceptance criteria in this issue to reflect the new standard
+9. HITL behavioral test — open a fresh session, invoke "write a new skill for X", verify: overlap scan first, grill used for gathering, agent proposes negative cases before trigger test, per-section explicit confirmation, both files produced via copy-then-fill, write-eval invoked, HITL prompted
--- a/docs/notes/factory-integration-decisions.md
+++ b/docs/notes/factory-integration-decisions.md
@@ -53,7 +53,8 @@ All skills — new and rebuilt — must follow this standard:
 - `name:` — matches directory name
 - `description:` — trigger-tested before writing the body (explicit, implicit, negative cases)
 - `metadata: category:` — from the category table above
- `metadata: version:` — semantic version; increment on meaningful changes
+
+`version:`, `updated:`, `when:`, `source:`, and `references:` are provenance/audit fields — they live in `META.md` alongside the SKILL.md (not in frontmatter). See `META-TEMPLATE.md` in `.agents/skills/write-skill/` for the META.md schema.

 **Body required sections:**
 - Constraints (highest-ROI element — prevents overengineering)
--- a/docs/notes/skill-implementation-workflow.md
+++ b/docs/notes/skill-implementation-workflow.md
@@ -103,11 +103,13 @@ Do not write the SKILL.md until the human has confirmed every section. The synth
 **c. SKILL.md** (sub-agent)  
 Once all sections are confirmed, spawn a write agent to produce the SKILL.md using `write-skill` (or hand-write for bootstrap skills). The agent receives: trigger description, per-section decisions from step b, upstream content to incorporate, authoring standard (see below).

-**c. `source:` and `references:` fields**  
-Populate after upstream review. Two distinct fields:
+**c. META.md — `source:` and `references:` fields**  
+Populate `META.md` after upstream review. Two distinct fields:
 - `source:` — upstream provenance tracking (repo slug, commit SHA, files adopted with inline comments, updated date). Present only if content was adopted. Absence = self-authored.
 - `references:` — general citations (research papers, documentation, standard specifications). Present only if the skill cites external research.

+Both fields live in `META.md` alongside the SKILL.md — not in frontmatter. See `META-TEMPLATE.md` in `.agents/skills/write-skill/` for the full schema.
+
 **d. eval.yaml** (sub-agent)  
 Invoke `write-eval` in two steps to preserve its confirmation gate:
 1. Sub-agent proposes test cases and returns the plan to the main conversation.
@@ -152,37 +154,29 @@ If this skill produced a cross-cutting observation — a pattern that appeared a
 ```yaml
 ---
 name: skill-name
-description: <trigger description — written and tested first>
-version: "1.0"
-updated: YYYY-MM-DD
-when: <when this skill is invoked — e.g. "invoked by /skill-name trigger">
+description: <trigger description — routing only; written and tested first; max 1024 chars>
 metadata:
  category: <design|factory|implement|test|review|deploy|operate|cross-cutting|iac>
-source:                              # omit entirely if self-authored
-  - repo: org/repo
-    commit: abc1234
-    files:
-      - path/to/file.md              # inline comment: what was taken
-    updated: YYYY-MM-DD
-references:                          # omit if no external citations
-  - <URL or citation>
+# allowed-tools: <add only when the skill has a narrow, well-defined tool surface; omit otherwise>
 ---
 ```

-`when:` is added to all Chunk 3 skills now; full bidirectional reference convention (reverse map, reference scanner) is deferred to Chunk 4 for refinement.
+Frontmatter contains only these fields. `version`, `updated`, `when`, `source`, and `references` are provenance/audit fields — they are not used for routing or runtime execution. They live in `META.md` alongside the SKILL.md, loaded only when needed. See `META-TEMPLATE.md` in `.agents/skills/write-skill/` for the META.md schema.

-`allowed-tools:` — optional field to restrict which tools the skill may invoke. Reduces token cost of tool definitions. Add when the skill has a narrow, well-defined tool surface.
+### Body sections

-### Body sections (required, in this order)
+Use `.agents/skills/write-skill/SKILL-TEMPLATE.md` as the authoritative structure reference. The template defines the required sections, correct order, XML grouping, and placeholder comments for each section.

-1. **Role** — one sentence: who the agent is when this skill is active
-2. **When to use / When not to use** — explicit inclusion and exclusion criteria; negative cases are as important as positive
-3. **Required inputs** — what must be present before the skill proceeds
-4. **Constraints** — non-negotiable rules; the highest-ROI section for preventing over-engineering
-5. **Process** — numbered steps (not bullets)
-6. **Output format** — exactly what the skill produces; structured if downstream workflow steps depend on it
-7. **Failure handling** — what to return if inputs are missing or a step fails; never silent failure
-8. **Self-check** — skill-specific correctness criteria the agent verifies before responding; must be concrete, not generic
+Summary (6 sections, in order):
+
+1. **Required inputs** — what must be present before the skill proceeds
+2. **Constraints** — non-negotiable rules; the highest-ROI section for preventing over-engineering
+3. **Process** — numbered steps (not bullets)
+4. **Output format** — exactly what the skill produces; structured if downstream workflow steps depend on it
+5. **Failure handling** — what to return if inputs are missing or a step fails; never silent failure
+6. **Self-check** — skill-specific correctness criteria the agent verifies before responding; must be concrete, not generic
+
+**Role** and **When to use / When not to use** are removed from the authoring standard. The description field carries trigger scope and negative cases (agentskills.io spec); Role is redundant when description + process provide adequate behavioral framing.

 **Size:** body ≤500 lines. Use XML tags only for skills with ≥3 logical sections and 500+ tokens; default to prose.

@@ -236,6 +230,6 @@ Upstream review happens per-skill during step 2, not once at chunk start.

 ## Open decisions carried forward

- **`when:` full resolution** — Chunk 4 (bidirectional reference convention, reference scanner tooling)
+- **Bidirectional reference convention** — Chunk 4 (reference scanner tooling; reverse map "what files point to X?"). The `when:` field itself is resolved — it lives in `META.md` alongside every skill.
 - **PRD/issue template scope** — refined during `write-prd` (0020) and `write-issue-spec` (0019) implementation
 - **Merging `zoom-out` into architect role** — revisit at Chunk 5 grill
--- a/docs/spec/overview.md
+++ b/docs/spec/overview.md
@@ -2,7 +2,7 @@

 Current deployed state of this repo — what you get if you run `install.sh` today. Updated at the close of each chunk and in the same PR as any behavior change.

-*Last updated: 2026-05-17 (issue 0018 phase 2)*
+*Last updated: 2026-05-18 (issue 0018 phase 1 refactor)*

 ## What is deployed

@@ -47,6 +47,8 @@ For chunk planning and open questions, see `docs/ROADMAP.md`.

 ## Recent changes

+- 2026-05-18 — Issue 0018 phase 1 refactor complete: `write-skill` redesigned from scratch. New files added to skill directory: `SKILL-TEMPLATE.md` (authoritative 6-section template with XML blocks, human-usable), `META-TEMPLATE.md` (provenance schema with inline-commented YAML), `CATEGORIES.md` (self-contained category table), `META.md` (write-skill's own provenance). SKILL.md rewritten: 6 sections replacing 8 (Role and When/When not dropped — not in agentskills.io spec); frontmatter reduced to 3 fields (`name`, `description`, `metadata.category`); provenance fields (`version`, `updated`, `when`, `source`, `references`) moved to META.md (progressive disclosure — not loaded at startup). `docs/notes/skill-implementation-workflow.md` updated to reference SKILL-TEMPLATE.md as the authoritative template.
+
 - 2026-05-17 — Issue 0018 phase 2 complete: `write-docs` skill written and deployed. First skill produced end-to-end by the factory (SKILL.md via `write-skill`, eval via `write-eval`). Category: implement. Key decisions: file-approval gate before reading (user names files or approves proposals); gap check before drafting (user fills what code doesn't explain); stage skipping allowed with logged reason; full revised section shown before confirmation gate; surgical edits only with per-round delta summary; Reader Testing via scoped sub-agent (doc + questions only, no source files); summary/overview sections written last. Sources: anthropics/skills doc-coauthoring (Reader Testing stage, surgical-edit constraint), mattpocock/skills write-a-skill (trigger pattern), bmad-code-org/BMAD-METHOD bmad-advanced-elicitation (confirmation gate). Open follow-up: documentation convention (file/folder/content structure, global vs repo-specific) — not yet defined.
 - 2026-05-17 — Issue 0018 phase 1 complete: `write-skill` bootstrap skill written and deployed. Hand-written (factory bootstrap). Self-authored — no upstream content adopted; agentskills.io best-practices and optimizing-descriptions docs cited as references. Speckit excluded (AGPL-3.0). Key decisions: new-skill + placeholder-conversion scope only (upgrades → `upgrade-skill`); trigger description tested against 3 cases before body written; `write-eval` invoked as step 7 in process; HITL prompt as step 8. Eval at `.agents/evals/factory/write-skill/eval.yaml`.
 - 2026-05-17 — Issue 0017 complete: `write-eval` bootstrap skill written and deployed. Two sections schema (`trigger_tests` + `output_tests`), provider-agnostic string assertions, show-plan-then-merge-on-rerun behaviour, conflict flagging (B model). Sources: agentskills/agentskills, darkrishabh/agent-skills-eval, bmad-code-org/BMAD-METHOD, mattpocock/skills. Hand-written eval at `.agents/evals/factory/write-eval/eval.yaml`.