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

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>