refactor: write-skill phase 1 refactor — grill, implementation, lessons
Complete 2026-05-18 workstream for write-skill refactor (issue 0018 phase 1). Grill output (handoff in docs/issues/0018-factory-write-skill.md): - 6-section standard replaces 8: Role and When/When not dropped (not in agentskills.io spec; description carries trigger scope and negatives) - Frontmatter reduced to 3 fields; provenance moves to META.md (progressive disclosure — not loaded at every skill scan) - SKILL-TEMPLATE.md and META-TEMPLATE.md as authoritative copy-fill artifacts - CATEGORIES.md as self-contained category reference in skill directory - Copy and fill explicitly split into separate process steps for determinism New files in .agents/skills/write-skill/: - SKILL-TEMPLATE.md — 6-section template with XML blocks and inline examples per section - META-TEMPLATE.md — provenance schema with inline-commented YAML; source vs references explicit - CATEGORIES.md — self-contained category table (no runtime dependency on factory docs) - META.md — write-skill's own provenance (v1.1, self-authored) SKILL.md rewritten: 8-step process, XML blocks (<requirements>, <steps>, <checks>), 3-field frontmatter, copy-then-fill steps explicit. Supporting docs updated: - skill-implementation-workflow.md: SKILL-TEMPLATE.md as authoritative template; source:/references: now reference META.md; when: marked resolved - factory-integration-decisions.md: frontmatter spec corrected - ROADMAP.md: authoring standard description updated - CONTEXT.md: Source field entry corrected; META.md added to glossary - docs/spec/overview.md: 2026-05-18 refactor entry added - docs/issues/0018: handoff status updated; acceptance criteria marked complete LESSONS.md: 3 entries added in grill session (cargo-culted body sections, provenance fields in frontmatter, copy-fill determinism) + 1 from implementation (planning meta-commentary does not belong in deployed artifacts). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
15
.agents/skills/write-skill/CATEGORIES.md
Normal file
15
.agents/skills/write-skill/CATEGORIES.md
Normal file
@@ -0,0 +1,15 @@
|
||||
# Skill Categories
|
||||
|
||||
| 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 |
|
||||
27
.agents/skills/write-skill/META-TEMPLATE.md
Normal file
27
.agents/skills/write-skill/META-TEMPLATE.md
Normal file
@@ -0,0 +1,27 @@
|
||||
```yaml
|
||||
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
|
||||
```
|
||||
16
.agents/skills/write-skill/META.md
Normal file
16
.agents/skills/write-skill/META.md
Normal file
@@ -0,0 +1,16 @@
|
||||
```yaml
|
||||
version: "1.1"
|
||||
updated: 2026-05-18
|
||||
|
||||
# when: describes when this skill is loaded — the full trigger context.
|
||||
# More detail than the description field; not used for routing.
|
||||
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
|
||||
```
|
||||
88
.agents/skills/write-skill/SKILL-TEMPLATE.md
Normal file
88
.agents/skills/write-skill/SKILL-TEMPLATE.md
Normal file
@@ -0,0 +1,88 @@
|
||||
---
|
||||
name: <skill-name>
|
||||
# description: routing-only field — loaded at startup for every skill scan to decide whether
|
||||
# to activate this skill. Write in imperative phrasing ("Use when X", not "This skill does X").
|
||||
# Must cover: (1) what the skill does, (2) when to invoke it, (3) negative triggers — what
|
||||
# adjacent tasks must NOT activate it. No behavioral or role framing; that belongs in the body.
|
||||
# Max 1024 characters. The `when:` detail that lived here previously now lives in META.md.
|
||||
# Example: "Use when the user wants to create a new SKILL.md file or convert a placeholder to
|
||||
# canonical format. Do NOT use when updating an existing well-formed skill — use upgrade-skill."
|
||||
description: <trigger description>
|
||||
metadata:
|
||||
category: <category — see CATEGORIES.md>
|
||||
# allowed-tools: <add only when the skill has a narrow, well-defined tool surface; omit otherwise>
|
||||
---
|
||||
|
||||
<requirements>
|
||||
|
||||
## Required inputs
|
||||
|
||||
<!-- List each required input as a bullet: name, what it is, how the agent obtains it.
|
||||
Negative trigger cases are NOT listed here — the agent proposes them during trigger testing.
|
||||
Example:
|
||||
- **Skill name** — kebab-case slug; inferred from user description if not stated explicitly, ask if ambiguous
|
||||
- **Existing SKILL.md path** — for placeholder conversions only; read before writing -->
|
||||
|
||||
- **<Input name>** — <description; how obtained>
|
||||
|
||||
## Constraints
|
||||
|
||||
<!-- One rule per bullet. State the boundary condition inline. Plain English, no jargon.
|
||||
Do not include a constraint about body section structure — the template enforces that.
|
||||
Example:
|
||||
- Frontmatter has three fields only: `name`, `description`, and `metadata.category` — add `allowed-tools` only when the skill has a narrow, well-defined tool surface
|
||||
- Body ≤500 lines — move anything longer into separate files in the skill directory -->
|
||||
|
||||
- <constraint>
|
||||
|
||||
</requirements>
|
||||
|
||||
<steps>
|
||||
|
||||
## Process
|
||||
|
||||
<!-- Numbered steps with a bold action label. Short, direct sentences — state what to do and
|
||||
what happens as a result. Call out hard gates explicitly (steps that block all progress
|
||||
until satisfied). No preamble, no meta-commentary about the steps themselves.
|
||||
Example:
|
||||
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. -->
|
||||
|
||||
1. **<Step name>.** <what to do and what happens as a result>
|
||||
|
||||
## Output format
|
||||
|
||||
<!-- Describe the files or artifacts produced. Include paths and how they are created
|
||||
(copy-fill from template, generated, etc.). State the template used for structured file output.
|
||||
Example:
|
||||
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` -->
|
||||
|
||||
<description of output>
|
||||
|
||||
</steps>
|
||||
|
||||
<checks>
|
||||
|
||||
## Failure handling
|
||||
|
||||
<!-- One bullet per failure mode. Lean — no overlap with constraints or process.
|
||||
Format: condition — action.
|
||||
Example:
|
||||
- Template file missing — stop, report the path searched, do not write from memory
|
||||
- `write-eval` fails or is unavailable — flag, do not mark the skill complete -->
|
||||
|
||||
- <failure condition> — <what to do>
|
||||
|
||||
## Self-check
|
||||
|
||||
<!-- Verifiable checklist the agent runs before declaring the skill complete.
|
||||
Each item must be checkable, not aspirational.
|
||||
Example:
|
||||
- [ ] Overlap check completed before any content was written
|
||||
- [ ] Trigger description tested against all three cases — all passed before body content was written -->
|
||||
|
||||
- [ ] <check>
|
||||
|
||||
</checks>
|
||||
@@ -1,130 +1,84 @@
|
||||
---
|
||||
name: write-skill
|
||||
description: Write a new skill for X, create a SKILL.md that does Y, build a skill to handle Z. Use when the user wants to author a new skill file or convert an existing placeholder skill to the canonical authoring standard. Do NOT use when the user wants to fix or update an existing well-formed skill, run existing evals, refactor application code, or write documentation for non-skill artifacts.
|
||||
version: "1.0"
|
||||
updated: 2026-05-17
|
||||
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 a placeholder to canonical format
|
||||
description: Use when the user wants to author a new skill file or convert an existing placeholder to the canonical authoring standard. Triggers: "write a new skill for X", "create a SKILL.md that does Y", "build a skill to handle Z". Do NOT use when fixing or updating an existing well-formed skill (use upgrade-skill), running existing evals (use write-eval), refactoring application code, or writing documentation for non-skill artifacts.
|
||||
metadata:
|
||||
category: factory
|
||||
references:
|
||||
- https://agentskills.io/skill-creation/optimizing-descriptions
|
||||
- https://agentskills.io/skill-creation/best-practices
|
||||
---
|
||||
|
||||
## Role
|
||||
|
||||
You are a skill author producing complete, correctly-structured SKILL.md files for an AI agent skills library, following the agentskills.io open standard with project-specific extensions.
|
||||
|
||||
## When to use / When not to use
|
||||
|
||||
**Use when:**
|
||||
- User wants to create a new skill ("write a skill for X", "build a skill that does Y")
|
||||
- User wants to convert a placeholder or non-standard SKILL.md to canonical format
|
||||
|
||||
**Do not use when:**
|
||||
- User wants to fix or update an existing well-formed skill → `upgrade-skill`
|
||||
- User wants to run or evaluate existing skills → `write-eval`
|
||||
- User wants to refactor application code → `implement/refactor`
|
||||
- User wants to write docs for a non-skill artifact → `write-docs`
|
||||
- User asks for a workflow, ADR, or PRD — dedicated skills exist for those
|
||||
<requirements>
|
||||
|
||||
## Required inputs
|
||||
|
||||
- **Skill name** — kebab-case slug; inferred from description if not stated explicitly
|
||||
- **Category** — one of: `design|factory|implement|test|review|deploy|operate|cross-cutting|iac`
|
||||
- **Skill name** — kebab-case slug; inferred from user description if not stated explicitly, ask if ambiguous
|
||||
- **Category** — from the category table in `CATEGORIES.md`; ask if unclear
|
||||
- **Purpose + use cases** — what the skill does and what tasks it handles; source for the trigger description
|
||||
- **When-not criteria** — adjacent tasks this skill must NOT activate on; needed for the negative trigger test
|
||||
- For placeholder conversions: **existing SKILL.md path** — read before writing
|
||||
- **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
|
||||
|
||||
- Output path: `.agents/skills/<skill-name>/SKILL.md`
|
||||
- Frontmatter must include: `name`, `description`, `version`, `updated`, `when`, `metadata.category`; `source:` only if upstream content adopted; `references:` only if external citations used
|
||||
- Body must contain all 8 sections in order: Role, When to use / When not to use, Required inputs, Constraints, Process, Output format, Failure handling, Self-check
|
||||
- Trigger description must be tested against 3 cases (explicit, implicit, negative) before any body content is written — do not proceed if any case fails
|
||||
- Body ≤500 lines; XML tags only if ≥3 logical sections and 500+ tokens
|
||||
- Check for overlapping skills in `.agents/skills/` before writing — flag overlap and get direction before continuing
|
||||
- For placeholder conversions: read existing SKILL.md before writing; remove all dead Pocock references (`setup-matt-pocock-skills`, `AGENT-BRIEF.md`, `OUT-OF-SCOPE.md`)
|
||||
- Show proposed structure and confirm with user before writing the file
|
||||
- Do not mark a skill complete until both the eval and the HITL behavioral test are done
|
||||
- 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
|
||||
|
||||
</requirements>
|
||||
|
||||
<steps>
|
||||
|
||||
## Process
|
||||
|
||||
1. **Gather requirements.** If not provided upfront, ask: what does the skill do, what tasks does it handle, what should it NOT activate on, what category, is this a new skill or a placeholder conversion?
|
||||
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. **Check for overlap.** Scan `.agents/skills/` for existing skills with similar purpose or trigger phrases. If overlap found, surface the conflicting skill name and description — get explicit direction before continuing.
|
||||
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. **Draft the trigger description.** Write the `description:` field from the gathered requirements.
|
||||
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. **Test the trigger description** against three cases before writing anything else:
|
||||
- Explicit: a query using the trigger phrase directly — must activate
|
||||
- Implicit: a query describing the task without naming it — must activate
|
||||
- Negative: an adjacent task from the when-not criteria — must NOT activate
|
||||
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.
|
||||
|
||||
If any case fails, propose a revised description and re-test. Do not proceed to the body until all three pass.
|
||||
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.
|
||||
|
||||
5. **Walk through each body section.** For each of the 8 sections: state the proposed content and where it comes from, present alternatives if they exist. Get confirmation before moving to the next section. Do not write the file until all sections are confirmed.
|
||||
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).
|
||||
|
||||
6. **Write the SKILL.md** at `.agents/skills/<skill-name>/SKILL.md`. For placeholder conversions: read the existing file first, carry forward content worth keeping, remove dead references.
|
||||
7. **Invoke `write-eval`.** Do not mark the skill complete without an eval file.
|
||||
|
||||
7. **Invoke `write-eval`.** Run `write-eval` to produce the eval at `.agents/evals/<category>/<skill-name>/eval.yaml`. Do not mark the skill complete until the eval file exists.
|
||||
|
||||
8. **Prompt for HITL behavioral test.** Remind the user to open a fresh session, invoke the skill with its trigger phrase, and verify the output meets the authoring standard before committing. The skill is not done until this test passes.
|
||||
8. **Prompt for HITL.** Ask the user to open a fresh session, trigger the skill, and confirm output before committing.
|
||||
|
||||
## Output format
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: <skill-name>
|
||||
description: <tested trigger description>
|
||||
version: "1.0"
|
||||
updated: YYYY-MM-DD
|
||||
when: <when this skill is invoked>
|
||||
metadata:
|
||||
category: <category>
|
||||
source: # omit if self-authored
|
||||
- repo: org/repo
|
||||
commit: <sha>
|
||||
files:
|
||||
- path/to/file.md # what was taken
|
||||
updated: YYYY-MM-DD
|
||||
references: # omit if no external citations
|
||||
- <URL or citation>
|
||||
---
|
||||
Two files produced for every skill:
|
||||
|
||||
## Role
|
||||
## When to use / When not to use
|
||||
## Required inputs
|
||||
## Constraints
|
||||
## Process
|
||||
## Output format
|
||||
## Failure handling
|
||||
## Self-check
|
||||
```
|
||||
- `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, the output replaces the existing file entirely — no partial edits.
|
||||
For placeholder conversions, `SKILL.md` replaces the existing file entirely — no partial edits.
|
||||
|
||||
</steps>
|
||||
|
||||
<checks>
|
||||
|
||||
## Failure handling
|
||||
|
||||
- **Skill name missing or ambiguous:** ask before proceeding — do not invent a name
|
||||
- **Category not provided:** ask before computing the output path — do not guess
|
||||
- **Trigger description fails a test case:** propose a revised description and re-test; do not proceed to body content until all three pass
|
||||
- **Overlap found with existing skill:** surface the conflict (name + description of the conflicting skill), ask for direction — do not continue autonomously
|
||||
- **Existing SKILL.md not found for a placeholder conversion:** stop and report the path searched; do not write based on assumptions
|
||||
- **Confirmed sections would produce a body exceeding 500 lines:** flag before writing, ask which sections to trim
|
||||
- **`write-eval` fails or is unavailable:** flag to the user — do not mark the skill complete without an eval
|
||||
- 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
|
||||
|
||||
- [ ] All 8 body sections present in order
|
||||
- [ ] Trigger description tested against all 3 cases — all pass before body was written
|
||||
- [ ] Overlap check completed against `.agents/skills/`
|
||||
- [ ] Output path correct: `.agents/skills/<skill-name>/SKILL.md`
|
||||
- [ ] Frontmatter complete: `name`, `description`, `version`, `updated`, `when`, `metadata.category` present
|
||||
- [ ] `source:` present only if upstream content adopted; absent if self-authored
|
||||
- [ ] `references:` present only if external citations used; absent otherwise
|
||||
- [ ] Body ≤500 lines
|
||||
- [ ] Proposed structure confirmed by user before file was written
|
||||
- [ ] For placeholder conversions: dead Pocock references removed
|
||||
- [ ] `write-eval` invoked — eval.yaml exists at correct path
|
||||
- [ ] 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
|
||||
|
||||
</checks>
|
||||
|
||||
@@ -93,7 +93,10 @@ Contains always-on rules in plain markdown with no provider-specific syntax (no
|
||||
A skill calling another skill by name to delegate a sub-task. The calling skill focuses on the orchestration decision ("when to do X"); the called skill owns the mechanics ("how to do X"). Established compositions: `grill-me` calls `write-adr` when a decision crystallises; `implement-feature` calls `tdd` as its implementation methodology. Composition chains are formalised as workflows in Chunk 4.
|
||||
|
||||
### Source field
|
||||
Frontmatter field (`source:`) on skill files tracking upstream provenance. An array — supports multiple upstream sources per skill. Each entry: `repo` (GitHub slug, e.g. `mattpocock/skills` — no URL, slug is stable and searchable), `commit` (exact SHA reviewed at adoption), `files` (list of files adopted with inline comments on what was taken), `updated` (date of last upstream review for this entry). Absence of `source:` means self-authored original. Upstream review cadence: per-skill during Chunk 3 (run during source review step); quarterly after roadmap completion (post Chunk 7). Companion field: `references:` (array of URLs or citations) for general external citations — distinct from `source:` which tracks adoptions with commit-level traceability.
|
||||
Field (`source:`) in a skill's `META.md` tracking upstream provenance. An array — supports multiple upstream sources per skill. Each entry: `repo` (GitHub slug, e.g. `mattpocock/skills` — no URL, slug is stable and searchable), `commit` (exact SHA reviewed at adoption), `files` (list of files adopted with inline comments on what was taken), `updated` (date of last upstream review for this entry). Absence of `source:` means self-authored original. Upstream review cadence: per-skill during Chunk 3 (run during source review step); quarterly after roadmap completion (post Chunk 7). Companion field: `references:` (array of URLs or citations) for general external citations — distinct from `source:` which tracks adoptions with commit-level traceability. Both fields live in `META.md`, not in SKILL.md frontmatter.
|
||||
|
||||
### META.md
|
||||
A per-skill markdown file containing a single YAML code block with provenance and audit fields: `version`, `updated`, `when`, `source`, and `references`. Lives alongside the SKILL.md in the skill directory (`.agents/skills/<name>/META.md`). Not loaded at agent startup — progressive disclosure principle: name and description route the skill; provenance is only needed for upgrade reviews and audits. Prevents these fields from being scanned on every session start alongside every skill's name and description. The authoritative schema is `META-TEMPLATE.md` in `.agents/skills/write-skill/`. See also: [[Source field]].
|
||||
|
||||
### Provider-agnostic issue tracker
|
||||
Skills and workflows reference "linked issue" generically rather than a specific provider. In the file-based phase, an issue is a `docs/issues/NNNN-<slug>.md` file. When Gitea MCP is configured, the same skills use it instead. The active backend is determined at runtime by MCP availability. "Issue" is the canonical cross-provider term (GitHub, GitLab, Gitea all use it). Gitea-specific skills are a provider adapter (`providers/gitea/`), not part of the core library. See ADR-0011.
|
||||
|
||||
16
LESSONS.md
16
LESSONS.md
@@ -54,6 +54,22 @@ The per-skill workflow (and write-skill's own process step 4) requires testing t
|
||||
|
||||
write-eval's process requires presenting the full test plan and waiting for user confirmation before writing the file. When write-eval is invoked by passing pre-designed test cases directly to a write sub-agent, this gate is skipped — the file is written before the user sees the plan. This happened during write-docs (issue 0018 phase 2). Fix: when orchestrating write-eval as part of a larger workflow, split into two steps: (1) sub-agent proposes test cases and returns to the main conversation; (2) after user confirmation, sub-agent writes the file. Or: design cases in the main conversation, present them to the user, then spawn the write agent. The plan-then-write separation is the gate — collapsing it into a single sub-agent call silently removes it.
|
||||
|
||||
## 2026-05-18 — Skill body sections were cargo-culted, not spec-defined
|
||||
|
||||
The write-skill authoring standard required 8 body sections including Role and When/When not. These were assumed to be agentskills.io requirements. Checking the actual spec revealed the body has no format restrictions at all — recommended sections are step-by-step instructions, examples, and edge cases. Role and When/When not were added by convention without verifying the standard. Fix: before encoding any requirement as part of an authoring standard, check the upstream spec directly. The agentskills.io spec also confirmed that negative triggers belong in the description field — not in a separate body section — which eliminates a persistent duplication pattern across all skills.
|
||||
|
||||
## 2026-05-18 — Provenance fields in frontmatter are loaded on every skill scan
|
||||
|
||||
Fields like `source:`, `references:`, `version:`, `updated:`, and `when:` in SKILL.md frontmatter are loaded at agent startup alongside `name` and `description` for every installed skill. None of these are used for routing or runtime execution — they are audit and upgrade-cycle records. Loading them at startup violates progressive disclosure and wastes tokens proportional to the number of installed skills. Fix: move all non-routing frontmatter to a separate `META.md` file in the skill directory. Frontmatter keeps only `name`, `description`, `metadata.category`, and `allowed-tools` (when applicable) — the four fields the spec actually uses for routing and discovery.
|
||||
|
||||
## 2026-05-18 — Copy-fill is more deterministic than generate for structured skill artifacts
|
||||
|
||||
When a skill produces a structured artifact like SKILL.md, the natural approach is to generate it from internalized rules in the Process section. But this means section structure is only as reliable as the agent's instruction-following under token pressure. Copy-fill (copy the template to the target path, then fill in content) separates structure from content: the template mechanically enforces section order and presence, freeing the Process section to focus only on sequencing constraints (what order to decide things) rather than also policing structure. Side benefit: the template is a human-usable artifact that can be adopted independently of the skill. Fix applied in write-skill refactor: SKILL-TEMPLATE.md and META-TEMPLATE.md are the authoritative structure sources; the Process section no longer contains a body structure constraint — the template handles it.
|
||||
|
||||
## 2026-05-17 — HITL gap: agent delegates confirmation to permission system
|
||||
|
||||
The agent-level HITL rule ("require explicit confirmation before irreversible shared-state operations") is being bypassed: the agent calls the tool and lets the permission dialog catch it. This means the rule is not firing in agent reasoning — it's the permission system acting as a safety net. If a user selects "don't ask again," the net disappears. Fix: the HITL rule needs to be framed as "do not call the tool" rather than "ask before proceeding" — the agent must ask first, then act only after explicit confirmation.
|
||||
|
||||
## 2026-05-18 — Planning meta-commentary does not belong in deployed artifacts
|
||||
|
||||
During write-skill refactor, an "open thread" note (about a deferred research step) was written directly into the SKILL.md Process section. The user caught it. The rule it violated: a deployed artifact (SKILL.md, a runtime file loaded by agents) must not contain planning meta-commentary — deferred items, open threads, and implementation notes belong in the issue file, which is the planning artifact. The skill body should contain only content relevant to runtime execution. If a decision is deferred, record it in the issue and leave no trace in the skill. The distinction: issue = planning record; skill = executable instruction.
|
||||
|
||||
@@ -33,7 +33,7 @@ A parallel workstream (not a numbered chunk) that runs alongside the chunk seque
|
||||
|---|---|---|
|
||||
| ✅ 1 | Repo skeleton + `install.sh` — structure in place, Claude Code wired up | Nothing else can be built without the structure and install working |
|
||||
| ✅ 2 | Core instructions — `coding.md`, `git.md` (incl. conventional commits), `testing.md`; communication rules in `providers/claude-code/CLAUDE.md` always-on section; retire `global.md`; migrate `docs/` to subdirectory-by-type naming | Instructions are the foundation everything else references; commit convention and doc naming must be in place before history accumulates |
|
||||
| ⏳ 3 | Skills library rebuild — the 12 existing skills are first-draft placeholders that predate the factory research; all are rebuilt or replaced. **Target library:** `docs/research/ai-coding-factory/ai-coding-factory-skills-index.md` is the canonical build reference — use it directly for each skill's trigger description, constraints, and category. Core categories: roles (6), design (3), factory (7 meta-skills — entirely new, high priority), implement (4 incl. tdd multi-file), test (3), review (4), deploy (4), operate (4), cross-cutting (4). Global optional: IaC (7) and Gitea (3) — scope defined in Chunk 3 PRD. **Naming convention:** the skills-index uses `category/skill-name` notation (e.g., `design/grill-me`) for identification only; actual paths are flat per ADR-0009 (`grill-me/SKILL.md`), category expressed in SKILL.md frontmatter. **Authoring standard:** frontmatter (`name`, `description`, `version`, `updated`, `metadata.category`), role, when/when-not, required inputs, constraints, process, output format, failure handling — per `ai-coding-factory-implementation-guidance.md` Section 10. **Process per skill:** check skills-index for trigger description and constraints → check implementation guidance Section 4–5 for framework sourcing → research/inspect open-source implementations → implement. Delete `ai-coding-factory-skills-index.md` when all skills exist. **Infrastructure complete**: 12 skills deployed to `~/.agents/skills/` via `install.sh`; provider adapter pattern in place. | Skills are the most immediately useful output; the rebuild is necessary because existing skills predate the authoring standard and the factory research |
|
||||
| ⏳ 3 | Skills library rebuild — the 12 existing skills are first-draft placeholders that predate the factory research; all are rebuilt or replaced. **Target library:** `docs/research/ai-coding-factory/ai-coding-factory-skills-index.md` is the canonical build reference — use it directly for each skill's trigger description, constraints, and category. Core categories: roles (6), design (3), factory (7 meta-skills — entirely new, high priority), implement (4 incl. tdd multi-file), test (3), review (4), deploy (4), operate (4), cross-cutting (4). Global optional: IaC (7) and Gitea (3) — scope defined in Chunk 3 PRD. **Naming convention:** the skills-index uses `category/skill-name` notation (e.g., `design/grill-me`) for identification only; actual paths are flat per ADR-0009 (`grill-me/SKILL.md`), category expressed in SKILL.md frontmatter. **Authoring standard:** see `SKILL-TEMPLATE.md` in `.agents/skills/write-skill/` (authoritative). Frontmatter: `name`, `description`, `metadata.category` only — provenance fields (`version`, `updated`, `when`, `source`, `references`) live in `META.md` per `META-TEMPLATE.md`. Body: 6 sections (Required inputs, Constraints, Process, Output format, Failure handling, Self-check) — Role and When/When not dropped per agentskills.io spec. **Process per skill:** check skills-index for trigger description and constraints → check implementation guidance Section 4–5 for framework sourcing → research/inspect open-source implementations → implement. Delete `ai-coding-factory-skills-index.md` when all skills exist. **Infrastructure complete**: 12 skills deployed to `~/.agents/skills/` via `install.sh`; provider adapter pattern in place. | Skills are the most immediately useful output; the rebuild is necessary because existing skills predate the authoring standard and the factory research |
|
||||
| 4 | Workflows — formalize the workstream workflow (kick-off types → grill → artifact → issues → implement → QA → commit); feature, bug, architecture, improvement, feedback patterns. **Prerequisite:** WorkflowContext schema (what each skill in a chain receives and returns) must be designed before any workflow skill is written; `docs/spec/` must exist (implement-feature constraint: update spec in same PR as behavior change) | Higher-level patterns built on top of a working skills foundation; grill feedback intake design before starting |
|
||||
| 5 | Agents — role skills (Architect, Developer, Reviewer, Security, QA, Ops) in `.agents/skills/` with `category: roles`; `core/agents/` for provider-agnostic subagent definitions needing isolated execution context (`context: fork`), translated to `.claude/agents/` by adapter; cross-project orchestration agents as use case | Role skills benefit from workflow patterns being established first; subagent definitions require the skills library to be stable |
|
||||
| 6 | Sync + project init tooling — `sync.sh` and `init-project.sh` | Tooling only makes sense once there is content worth syncing and scaffolding |
|
||||
|
||||
@@ -70,12 +70,19 @@ Follow the per-skill workflow defined in `docs/notes/skill-implementation-workfl
|
||||
- [ ] **HITL:** human reviews SKILL.md and eval before committing
|
||||
- [x] Per-skill process followed for both phases (see `docs/notes/skill-implementation-workflow.md`)
|
||||
- [x] 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
|
||||
- [x] `source:` and `references:` fields correctly populated or absent
|
||||
- ~~[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
|
||||
- [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 — authoritative 6-section template with XML blocks
|
||||
- [x] **Refactor:** `.agents/skills/write-skill/META-TEMPLATE.md` exists — YAML block with inline-commented source schema
|
||||
- [x] **Refactor:** `.agents/skills/write-skill/CATEGORIES.md` exists — category table copied from factory-integration-decisions.md
|
||||
- [x] **Refactor:** `.agents/skills/write-skill/META.md` exists — write-skill's own provenance (self-authored, no source, references agentskills.io)
|
||||
- [x] **Refactor:** `write-skill/SKILL.md` rewritten — 6 sections, XML blocks, 3-field frontmatter, no Role, no When/When not
|
||||
- [x] **Refactor:** `docs/notes/skill-implementation-workflow.md` updated — references SKILL-TEMPLATE.md instead of embedding inline template
|
||||
- [ ] **Refactor HITL:** open fresh session, invoke "write a new skill for X", verify: overlap scan first, grill to gather, agent proposes negative cases, per-section explicit confirmation, copy-then-fill both files, write-eval invoked, HITL prompted
|
||||
- [ ] **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)
|
||||
@@ -134,3 +141,346 @@ Follow the per-skill workflow defined in `docs/notes/skill-implementation-workfl
|
||||
**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 — pending HITL behavioral test
|
||||
|
||||
**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:**
|
||||
```yaml
|
||||
name: write-skill
|
||||
description: ...
|
||||
version: "1.0"
|
||||
updated: 2026-05-17
|
||||
when: ...
|
||||
metadata:
|
||||
category: factory
|
||||
references:
|
||||
- ...
|
||||
```
|
||||
|
||||
**After:**
|
||||
```yaml
|
||||
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:
|
||||
|
||||
```yaml
|
||||
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:
|
||||
|
||||
```yaml
|
||||
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
|
||||
|
||||
@@ -53,7 +53,8 @@ All skills — new and rebuilt — must follow this standard:
|
||||
- `name:` — matches directory name
|
||||
- `description:` — trigger-tested before writing the body (explicit, implicit, negative cases)
|
||||
- `metadata: category:` — from the category table above
|
||||
- `metadata: version:` — semantic version; increment on meaningful changes
|
||||
|
||||
`version:`, `updated:`, `when:`, `source:`, and `references:` are provenance/audit fields — they live in `META.md` alongside the SKILL.md (not in frontmatter). See `META-TEMPLATE.md` in `.agents/skills/write-skill/` for the META.md schema.
|
||||
|
||||
**Body required sections:**
|
||||
- Constraints (highest-ROI element — prevents overengineering)
|
||||
|
||||
@@ -103,11 +103,13 @@ Do not write the SKILL.md until the human has confirmed every section. The synth
|
||||
**c. SKILL.md** (sub-agent)
|
||||
Once all sections are confirmed, spawn a write agent to produce the SKILL.md using `write-skill` (or hand-write for bootstrap skills). The agent receives: trigger description, per-section decisions from step b, upstream content to incorporate, authoring standard (see below).
|
||||
|
||||
**c. `source:` and `references:` fields**
|
||||
Populate after upstream review. Two distinct fields:
|
||||
**c. META.md — `source:` and `references:` fields**
|
||||
Populate `META.md` after upstream review. Two distinct fields:
|
||||
- `source:` — upstream provenance tracking (repo slug, commit SHA, files adopted with inline comments, updated date). Present only if content was adopted. Absence = self-authored.
|
||||
- `references:` — general citations (research papers, documentation, standard specifications). Present only if the skill cites external research.
|
||||
|
||||
Both fields live in `META.md` alongside the SKILL.md — not in frontmatter. See `META-TEMPLATE.md` in `.agents/skills/write-skill/` for the full schema.
|
||||
|
||||
**d. eval.yaml** (sub-agent)
|
||||
Invoke `write-eval` in two steps to preserve its confirmation gate:
|
||||
1. Sub-agent proposes test cases and returns the plan to the main conversation.
|
||||
@@ -152,37 +154,29 @@ If this skill produced a cross-cutting observation — a pattern that appeared a
|
||||
```yaml
|
||||
---
|
||||
name: skill-name
|
||||
description: <trigger description — written and tested first>
|
||||
version: "1.0"
|
||||
updated: YYYY-MM-DD
|
||||
when: <when this skill is invoked — e.g. "invoked by /skill-name trigger">
|
||||
description: <trigger description — routing only; written and tested first; max 1024 chars>
|
||||
metadata:
|
||||
category: <design|factory|implement|test|review|deploy|operate|cross-cutting|iac>
|
||||
source: # omit entirely if self-authored
|
||||
- repo: org/repo
|
||||
commit: abc1234
|
||||
files:
|
||||
- path/to/file.md # inline comment: what was taken
|
||||
updated: YYYY-MM-DD
|
||||
references: # omit if no external citations
|
||||
- <URL or citation>
|
||||
# allowed-tools: <add only when the skill has a narrow, well-defined tool surface; omit otherwise>
|
||||
---
|
||||
```
|
||||
|
||||
`when:` is added to all Chunk 3 skills now; full bidirectional reference convention (reverse map, reference scanner) is deferred to Chunk 4 for refinement.
|
||||
Frontmatter contains only these fields. `version`, `updated`, `when`, `source`, and `references` are provenance/audit fields — they are not used for routing or runtime execution. They live in `META.md` alongside the SKILL.md, loaded only when needed. See `META-TEMPLATE.md` in `.agents/skills/write-skill/` for the META.md schema.
|
||||
|
||||
`allowed-tools:` — optional field to restrict which tools the skill may invoke. Reduces token cost of tool definitions. Add when the skill has a narrow, well-defined tool surface.
|
||||
### Body sections
|
||||
|
||||
### Body sections (required, in this order)
|
||||
Use `.agents/skills/write-skill/SKILL-TEMPLATE.md` as the authoritative structure reference. The template defines the required sections, correct order, XML grouping, and placeholder comments for each section.
|
||||
|
||||
1. **Role** — one sentence: who the agent is when this skill is active
|
||||
2. **When to use / When not to use** — explicit inclusion and exclusion criteria; negative cases are as important as positive
|
||||
3. **Required inputs** — what must be present before the skill proceeds
|
||||
4. **Constraints** — non-negotiable rules; the highest-ROI section for preventing over-engineering
|
||||
5. **Process** — numbered steps (not bullets)
|
||||
6. **Output format** — exactly what the skill produces; structured if downstream workflow steps depend on it
|
||||
7. **Failure handling** — what to return if inputs are missing or a step fails; never silent failure
|
||||
8. **Self-check** — skill-specific correctness criteria the agent verifies before responding; must be concrete, not generic
|
||||
Summary (6 sections, in order):
|
||||
|
||||
1. **Required inputs** — what must be present before the skill proceeds
|
||||
2. **Constraints** — non-negotiable rules; the highest-ROI section for preventing over-engineering
|
||||
3. **Process** — numbered steps (not bullets)
|
||||
4. **Output format** — exactly what the skill produces; structured if downstream workflow steps depend on it
|
||||
5. **Failure handling** — what to return if inputs are missing or a step fails; never silent failure
|
||||
6. **Self-check** — skill-specific correctness criteria the agent verifies before responding; must be concrete, not generic
|
||||
|
||||
**Role** and **When to use / When not to use** are removed from the authoring standard. The description field carries trigger scope and negative cases (agentskills.io spec); Role is redundant when description + process provide adequate behavioral framing.
|
||||
|
||||
**Size:** body ≤500 lines. Use XML tags only for skills with ≥3 logical sections and 500+ tokens; default to prose.
|
||||
|
||||
@@ -236,6 +230,6 @@ Upstream review happens per-skill during step 2, not once at chunk start.
|
||||
|
||||
## Open decisions carried forward
|
||||
|
||||
- **`when:` full resolution** — Chunk 4 (bidirectional reference convention, reference scanner tooling)
|
||||
- **Bidirectional reference convention** — Chunk 4 (reference scanner tooling; reverse map "what files point to X?"). The `when:` field itself is resolved — it lives in `META.md` alongside every skill.
|
||||
- **PRD/issue template scope** — refined during `write-prd` (0020) and `write-issue-spec` (0019) implementation
|
||||
- **Merging `zoom-out` into architect role** — revisit at Chunk 5 grill
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
Current deployed state of this repo — what you get if you run `install.sh` today. Updated at the close of each chunk and in the same PR as any behavior change.
|
||||
|
||||
*Last updated: 2026-05-17 (issue 0018 phase 2)*
|
||||
*Last updated: 2026-05-18 (issue 0018 phase 1 refactor)*
|
||||
|
||||
## What is deployed
|
||||
|
||||
@@ -47,6 +47,8 @@ For chunk planning and open questions, see `docs/ROADMAP.md`.
|
||||
|
||||
## Recent changes
|
||||
|
||||
- 2026-05-18 — Issue 0018 phase 1 refactor complete: `write-skill` redesigned from scratch. New files added to skill directory: `SKILL-TEMPLATE.md` (authoritative 6-section template with XML blocks, human-usable), `META-TEMPLATE.md` (provenance schema with inline-commented YAML), `CATEGORIES.md` (self-contained category table), `META.md` (write-skill's own provenance). SKILL.md rewritten: 6 sections replacing 8 (Role and When/When not dropped — not in agentskills.io spec); frontmatter reduced to 3 fields (`name`, `description`, `metadata.category`); provenance fields (`version`, `updated`, `when`, `source`, `references`) moved to META.md (progressive disclosure — not loaded at startup). `docs/notes/skill-implementation-workflow.md` updated to reference SKILL-TEMPLATE.md as the authoritative template.
|
||||
|
||||
- 2026-05-17 — Issue 0018 phase 2 complete: `write-docs` skill written and deployed. First skill produced end-to-end by the factory (SKILL.md via `write-skill`, eval via `write-eval`). Category: implement. Key decisions: file-approval gate before reading (user names files or approves proposals); gap check before drafting (user fills what code doesn't explain); stage skipping allowed with logged reason; full revised section shown before confirmation gate; surgical edits only with per-round delta summary; Reader Testing via scoped sub-agent (doc + questions only, no source files); summary/overview sections written last. Sources: anthropics/skills doc-coauthoring (Reader Testing stage, surgical-edit constraint), mattpocock/skills write-a-skill (trigger pattern), bmad-code-org/BMAD-METHOD bmad-advanced-elicitation (confirmation gate). Open follow-up: documentation convention (file/folder/content structure, global vs repo-specific) — not yet defined.
|
||||
- 2026-05-17 — Issue 0018 phase 1 complete: `write-skill` bootstrap skill written and deployed. Hand-written (factory bootstrap). Self-authored — no upstream content adopted; agentskills.io best-practices and optimizing-descriptions docs cited as references. Speckit excluded (AGPL-3.0). Key decisions: new-skill + placeholder-conversion scope only (upgrades → `upgrade-skill`); trigger description tested against 3 cases before body written; `write-eval` invoked as step 7 in process; HITL prompt as step 8. Eval at `.agents/evals/factory/write-skill/eval.yaml`.
|
||||
- 2026-05-17 — Issue 0017 complete: `write-eval` bootstrap skill written and deployed. Two sections schema (`trigger_tests` + `output_tests`), provider-agnostic string assertions, show-plan-then-merge-on-rerun behaviour, conflict flagging (B model). Sources: agentskills/agentskills, darkrishabh/agent-skills-eval, bmad-code-org/BMAD-METHOD, mattpocock/skills. Hand-written eval at `.agents/evals/factory/write-eval/eval.yaml`.
|
||||
|
||||
Reference in New Issue
Block a user