holocron/docs/issues/0018-factory-write-skill.md

0018 — factory/write-skill (bootstrap skill)

Type: HITL
Parent PRD: docs/prd/chunk-3-skills-library.md

What to build

Phase 1: write-skill

Build write-skill — the second bootstrap skill. Once complete, it is used to author all subsequent SKILL.md files in Chunk 3.

Trigger description (from skills index): "Write a new skill for X, create a SKILL.md that does Y"

Key constraints:

• Produces a complete SKILL.md following the authoring standard in docs/notes/skill-implementation-workflow.md
• Validates trigger description against explicit, implicit, and negative test queries before completing
• Flags if the proposed skill overlaps with an existing skill in the library
• Skill file: .agents/skills/write-skill/SKILL.md; metadata.category: factory
• SKILL.md is hand-written (write-skill cannot author itself before it exists)
• Eval via write-eval (issue 0017)

Phase 2: write-docs

Build write-docs — the first skill authored via write-skill itself (the factory eating itself for the first time). Implement immediately after phase 1 is complete and deployed.

Trigger description (from skills index): "Write documentation for X, document this module, create docs for this feature"

Key constraints:

• Skill file: .agents/skills/write-docs/SKILL.md; metadata.category: implement
• SKILL.md authored via write-skill; eval via write-eval
• Follow full per-skill workflow from docs/notes/skill-implementation-workflow.md (sub-agents for discovery, review, conflict check)
• Derives from code and spec; never invents behaviour

Phase 3: Documentation convention

Define the canonical documentation convention for this repo — the missing input that write-docs currently defers to "user-specified or conventionally appropriate path." Without this, every write-docs invocation requires the user to re-decide where output goes.

Opening action: /grill-me session to resolve the convention before writing anything.

Questions the grill must resolve:

• What documentation types exist in this repo? (reference, guide, README section, inline comment, changelog entry, etc.)
• Where does each type live? (file paths, directory structure — e.g. does docs/ own all prose, or do modules carry their own READMEs?)
• Global defaults vs. repo-specific overrides — what layer does the convention live at?
• What format standards apply per type? (required headers, prose vs structured, max length)
• Does write-docs need to be updated after the convention is defined, or does it reference it at runtime?

Expected outputs:

• docs/notes/doc-convention.md — the convention document (file/folder/content structure, per-type rules, override model)
• Update to write-docs SKILL.md output format section — reference the convention instead of deferring to "conventionally appropriate path"
• Update to CONTEXT.md if the convention becomes a standing repo-level principle

No new SKILL.md for this phase — this is a convention document, not a skill. If write-docs needs substantial changes after the grill, use upgrade-skill.

Implementation notes

Follow the per-skill workflow defined in docs/notes/skill-implementation-workflow.md (produced by issue 0016).

Known upstream sources to review:

• mattpocock/skills — contains write-a-skill, the direct Pocock equivalent; review at current HEAD; record SHA in source: for any adopted content
• agentskills.io open standard — the SKILL.md format spec is the authoritative reference for what write-skill must produce; cross-reference against the standard before finalising output format constraints
• bmad-method/bmad-method — check for any skill-authoring or template-writing patterns

Acceptance criteria

• .agents/skills/write-skill/SKILL.md exists; metadata.category: factory; authoring standard met
• Trigger description validates against explicit, implicit, and negative test queries
• .agents/evals/factory/write-skill/eval.yaml exists; produced via write-eval
• install.sh deploys write-skill to ~/.agents/skills/
• HITL: human runs behavioral test: invoke "write a new skill for X" and verify the produced SKILL.md meets the authoring standard
• HITL: human reviews SKILL.md and eval before committing
• Per-skill process followed for both phases (see docs/notes/skill-implementation-workflow.md)
• Trigger description for each skill tested against explicit, implicit, and negative queries before body written
• when: frontmatter field present in both SKILL.md files
• source: and references: fields correctly populated or absent
• eval.yaml for each skill contains all 5 required test types
• Body ≤500 lines for each skill
• Phase 2 (write-docs) is the first skill produced end-to-end by the factory
• docs/spec/overview.md updated to reflect both skills deployed
• 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)
• Phase 3: CONTEXT.md updated if convention becomes a standing principle

Blocked by

• 0016 (grill defines per-skill workflow)
• 0017 (write-eval needed to produce the eval for this skill)

Handoff — Phase 1

Status: complete — pending HITL behavioral test (acceptance criteria steps 5–6)

Files produced:

• .agents/skills/write-skill/SKILL.md
• .agents/evals/factory/write-skill/eval.yaml

Key decisions:

• Scope: new-skill creation + placeholder→canonical conversion only. Updating/fixing existing skills → upgrade-skill (separate skill in the index).
• Trigger validation (3 cases) is a named gate in write-skill's process before body content is written.
• write-eval is step 7 of write-skill's process — the skill invokes it automatically. HITL prompt is step 8.
• Self-authored (no source: field); references: cites agentskills.io best-practices and optimizing-descriptions.
• speckit-agent-skills (dceoy) excluded — AGPL-3.0 copyleft.
• Role is self-contained (no reference to workflow doc) so it can be used standalone after chunk 3.

Open threads:

• HITL behavioral test for write-skill: open a fresh session, invoke "write a new skill for X" in this repo context, verify trigger is tested before body, per-section walk-through happens, write-eval is invoked, HITL prompt appears.
• Phase 2 HITL behavioral test: open a fresh session, invoke "write docs for X" or "document this module", verify file-approval gate fires before any reading, gap check step appears, full section shown before confirmation gate, Reader Testing step present.

Next session start:

• Load: CONTEXT.md, docs/notes/skill-implementation-workflow.md, docs/issues/0019-factory-skills-remaining.md
• First action: HITL behavioral tests for write-skill (phase 1) and write-docs (phase 2) if not yet done, then begin issue 0019 — start with write-adr (must be verified before design skills issue 0020 begins)

---

Handoff — Phase 2

Status: complete — pending HITL behavioral test

Files produced:

• .agents/skills/write-docs/SKILL.md
• .agents/evals/implement/write-docs/eval.yaml

Key decisions:

• File-approval gate before reading: user names specific files, or skill proposes candidates and waits for approval — enforces governance scope discipline.
• Gap check before drafting: presents extracted behaviour, asks user to fill only what code doesn't explain — prevents invented content.
• Stage skipping: allowed with explicit user request + one-sentence logged reason (hybrid per synthesis grill decision).
• Confirmation gate: shows full revised section before gate fires, not just the diff (per synthesis grill decision).
• Surgical edits only + per-round delta summary (no hard iteration cap, delta summary keeps cumulative change reviewable).
• Reader Testing: scoped sub-agent receives only finished doc + questions — no source files (minimum data exposure per governance conflict 1).
• Sources adopted: anthropics/skills doc-coauthoring (Reader Testing stage, surgical-edit constraint, gap-check), mattpocock/skills write-a-skill (trigger pattern, checklist items), bmad-code-org/BMAD-METHOD bmad-advanced-elicitation (confirmation gate). bmad infrastructure (CSV registry, party mode) explicitly excluded.
• Rejected mattpocock 100-line limit — project convention (500 lines) takes precedence; noted in inline source comment.
• Prompts-as-code governance obligation satisfied: SKILL.md committed to repo; version control is the enforcement mechanism.

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.