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

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

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: 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 (write-docs): first skill authored end-to-end by the factory. Follow full per-skill workflow from docs/notes/skill-implementation-workflow.md.

Next session start:

• Load: CONTEXT.md, docs/notes/skill-implementation-workflow.md, docs/issues/0018-factory-write-skill.md
• First action: HITL behavioral test for write-skill, then begin phase 2 (write-docs) using write-skill