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?
• 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.

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 (run HOTL): subagent fresh-context behavioral test 2026-05-26 — invoked write-skill for git-commit-message; overlap scan first ✅; grill before writing ✅; trigger tested before body ✅; agent proposed negative cases ✅; section-by-section confirmation ✅; file write blocked by subagent permissions (environment constraint, not skill failure); process order fully correct
• HITL (run HOTL): SKILL.md content reviewed by subagent auditor; structure and process compliance confirmed; minor: PASS/FAIL verdicts embedded in table rows rather than shown explicitly per-case (borderline — not a failure)
• 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
• [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
• 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 — authoritative 6-section template with XML blocks
• Refactor: .agents/skills/write-skill/META-TEMPLATE.md exists — YAML block with inline-commented source schema
• Refactor: .agents/skills/write-skill/CATEGORIES.md exists — category table copied from factory-integration-decisions.md
• Refactor: .agents/skills/write-skill/META.md exists — write-skill's own provenance (self-authored, no source, references agentskills.io)
• Refactor: write-skill/SKILL.md rewritten — 6 sections, XML blocks, 3-field frontmatter, no Role, no When/When not
• Refactor: docs/notes/skill-implementation-workflow.md updated — references SKILL-TEMPLATE.md instead of embedding inline template
• Refactor HITL (run HOTL): covered by write-skill behavioral test above (2026-05-26) — all refactor process steps verified correct
• 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 ✅

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 — covered HOTL 2026-05-26: file-approval gate ✅, gap check ✅, full section before gate ✅, Reader Testing ✅. Surgical-edits behavior not tested (no revision round triggered — not a failure).

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 ✅

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.

---

Handoff — Phase 1 Refactor (write-skill)

Status: implementation complete ✅

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:

name: write-skill
description: ...
version: "1.0"
updated: 2026-05-17
when: ...
metadata:
  category: factory
references:
  - ...

After:

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:

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:

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