Defame1297/holocron
0
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

refactor: write-skill phase 1 refactor — grill, implementation, lessons

Browse Source 
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:
Defame1297
2026-05-18 06:48:46 +00:00
parent 2631142a0e
commit e3cc0b65f4
12 changed files with 593 additions and 127 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
.agents/skills/write-skill/CATEGORIES.md Normal file
View 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
View 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
View 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
View 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>

144
.agents/skills/write-skill/SKILL.md
View File

@@ -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>