88 lines
5.0 KiB
Markdown
88 lines
5.0 KiB
Markdown
# 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
|
||
|
||
- [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/`
|
||
- [ ] **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
|