0018 — factory/write-skill (bootstrap skill) #31

New Issue

Claude · 2026-06-28T17:10:48Z

Claude commented

2026-06-28 17:10:48 +00:00

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?
Close-out workflow gap (consider in grill): the roadmap housekeeping section drifts out of sync because there is no explicit step requiring it to be updated when work is completed. The issue acceptance checklist gets updated; the roadmap does not. Should the doc convention (or a close-out convention) define a rule for this? Or does it belong in the development workflow section of ROADMAP.md itself?

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.

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 (run HOTL): subagent fresh-context behavioral test 2026-05-26 — process order fully correct
Per-skill process followed for both phases
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
Refactor: .agents/skills/write-skill/SKILL-TEMPLATE.md exists
Refactor: .agents/skills/write-skill/META-TEMPLATE.md exists
Refactor: .agents/skills/write-skill/CATEGORIES.md exists
Refactor: .agents/skills/write-skill/META.md exists
Refactor: write-skill/SKILL.md rewritten — 6 sections, XML blocks, 3-field frontmatter
Refactor: docs/notes/skill-implementation-workflow.md updated
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
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 & 2

Status: complete (Phases 1 and 2); Phase 3 pending

Files produced:

.agents/skills/write-skill/SKILL.md
.agents/evals/factory/write-skill/eval.yaml
.agents/skills/write-docs/SKILL.md
.agents/evals/implement/write-docs/eval.yaml
.agents/skills/write-skill/SKILL-TEMPLATE.md
.agents/skills/write-skill/META-TEMPLATE.md
.agents/skills/write-skill/CATEGORIES.md
.agents/skills/write-skill/META.md

**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? - **Close-out workflow gap (consider in grill):** the roadmap housekeeping section drifts out of sync because there is no explicit step requiring it to be updated when work is completed. The issue acceptance checklist gets updated; the roadmap does not. Should the doc convention (or a close-out convention) define a rule for this? Or does it belong in the development workflow section of ROADMAP.md itself? **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`. ## Acceptance criteria - [x] `.agents/skills/write-skill/SKILL.md` exists; `metadata.category: factory`; authoring standard met - [x] Trigger description validates against explicit, implicit, and negative test queries - [x] `.agents/evals/factory/write-skill/eval.yaml` exists; produced via `write-eval` - [x] `install.sh` deploys `write-skill` to `~/.agents/skills/` - [x] **HITL (run HOTL):** subagent fresh-context behavioral test 2026-05-26 — process order fully correct - [x] Per-skill process followed for both phases - [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 - [x] **Refactor:** `.agents/skills/write-skill/META-TEMPLATE.md` exists - [x] **Refactor:** `.agents/skills/write-skill/CATEGORIES.md` exists - [x] **Refactor:** `.agents/skills/write-skill/META.md` exists - [x] **Refactor:** `write-skill/SKILL.md` rewritten — 6 sections, XML blocks, 3-field frontmatter - [x] **Refactor:** `docs/notes/skill-implementation-workflow.md` updated - [ ] **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 - [ ] **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 & 2 **Status:** complete (Phases 1 and 2); Phase 3 pending **Files produced:** - `.agents/skills/write-skill/SKILL.md` - `.agents/evals/factory/write-skill/eval.yaml` - `.agents/skills/write-docs/SKILL.md` - `.agents/evals/implement/write-docs/eval.yaml` - `.agents/skills/write-skill/SKILL-TEMPLATE.md` - `.agents/skills/write-skill/META-TEMPLATE.md` - `.agents/skills/write-skill/CATEGORIES.md` - `.agents/skills/write-skill/META.md`

Claude added this to the Legacy / Triage milestone 2026-06-28 17:10:48 +00:00

Claude added the Kind/Feature

Priority

Medium

3

labels 2026-06-28 17:10:48 +00:00

Claude closed this issue

2026-06-28 17:13:43 +00:00

Claude referenced this issue

2026-06-28 17:14:45 +00:00

refactor: align repo with marketplace/plugin model — migrate docs and issues to Gitea, rewrite specs, clean up stale artifacts #15

Sign in to join this conversation.