holocron/docs/notes/skill-implementation-workflow.md

Skill Implementation Workflow

Produced by: issue 0016 grill session, 2026-05-17
Applies to: all Chunk 3 skill issues (0017–0028)

---

Bootstrap sequence

The first two skills are hand-authored because the factory cannot build itself before it exists. Everything from step 3 onward uses the factory.

Step	Skill	SKILL.md	eval.yaml
1	write-eval	Hand-written	Hand-written
2	write-skill (phase 1 of issue 0018)	Hand-written	Via write-eval
3	write-docs (phase 2 of issue 0018)	Via write-skill	Via write-eval
4+	Everything else	Via write-skill	Via write-eval

Step 3 (write-docs) is the first real factory output — write-skill authors its own SKILL.md.

---

Per-skill process

Every skill — new or refactor — follows this sequence. Sub-agents are the default for research and writing steps to keep the main context lean.

Step 1 — Source discovery (sub-agent)

Spawn an Explore agent to:

• Check the issue and skills index for listed upstream sources
• Web search for additional sources not already listed
• For refactors: retrieve the current SKILL.md as one of the inputs

Return: list of sources with repo slugs and current HEAD commit SHAs.

Step 2 — Source review (sub-agent)

Spawn a research agent to read each source and extract relevant content. The agent must:

• Read relevant files from each upstream source
• Note the commit SHA at time of review
• Flag any changes since the last updated: date (for skills with an existing source: field)
• Apply the pull criteria below to recommend whether to incorporate each change
• Run a licence check: note the licence of each upstream repo; flag any copyleft (GPL, AGPL) material before adoption
• Flag any third-party skill files that appear unreviewed or have unusual structure (documented 36% prompt injection rate in community skill sets — treat unreviewed upstream skills as untrusted)

Return: extracted content per source, commit SHAs, licence notes, security flags.

Pull criteria:

Change type	Action
Trigger description or process sections changed	Always pull
New constraints or failure-handling cases added	Evaluate — pull if it closes a real gap
Formatting, wording, minor structural changes	Skip
Any upstream reviewed (pull or skip)	Update updated: date in source: regardless

Step 3 — Conflict check (sub-agent)

Spawn an agent to cross-check the extracted upstream content against:

• core/instructions/governance.md — hard prohibitions, data classification, HITL requirements
• docs/ai-constitution.md — scope discipline, deterministic execution preference, licence obligations, output volume constraint, transparency requirements

The agent flags conflicts and tensions as numbered items for the synthesis grill. It does not resolve them — that is the grill's job.

Common conflicts to check:

• Does any upstream pattern require the agent to take irreversible action without HITL? Flag.
• Does any adopted content handle Restricted-tier data (credentials, health data)? Flag.
• Does any upstream skip licence scanning before code commit? Flag.
• Does any upstream encourage repeated AI inference for a deterministic task? Flag — note deterministic execution preference.
• Does the upstream skill body exceed 500 lines or load excessive context at startup? Flag — note token architecture constraint.

Return: numbered conflict/tension list, or "no conflicts found."

Step 4 — Synthesis grill

Short grill session with the human covering:

• How to combine elements from the upstreams (what to take from each, what to leave)
• How to resolve any flagged conflicts from step 3
• Any open design questions specific to this skill

This is not a full grill-with-docs session — it is focused and bounded. If there are no conflicts and the combining decision is obvious, the grill can be a single confirmation exchange.

Step 5 — Co-write iteratively

Work through the following in order, iterating with the human. Sub-agents handle writing tasks where context accumulation is a risk.

a. Trigger description
Write the description: frontmatter field first. Test it against three cases before writing the body:

1. Explicit invocation — user says the trigger phrase directly
2. Implicit invocation — user describes the task without the trigger phrase
3. Negative case — adjacent task that must NOT activate this skill

Do not proceed to the body until all three pass.

b. Per-section options walk-through
Before writing anything, walk through each body section with the human. For each section:

• State what content is proposed and which upstream source it comes from
• Present alternatives where upstream sources offered different approaches
• Get explicit confirmation (or redirection) before moving to the next section

Do not write the SKILL.md until the human has confirmed every section. The synthesis grill decisions cover the eval schema and gating questions; this step covers how upstream content maps to each SKILL.md section. These are separate conversations — do not collapse them.

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:

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

d. eval.yaml (sub-agent)
Spawn an agent to produce the eval via write-eval. Co-located at .agents/evals/<category>/<skill-name>/eval.yaml. Must contain all five required test types (see Eval schema below).

e. HITL behavioral test
Human opens a fresh Claude session, invokes the skill with its trigger phrase, and verifies output. Do not batch more than 2–3 skills before running behavioral tests — output volume must stay within genuine human review capacity. An approval that cannot be meaningfully evaluated is not an approval.

Step 6 — Session handoff

After the behavioral test passes, close the skill session by appending a ## Handoff section to the skill's issue file. This is the entry point for the next session — write it assuming zero shared context.

## Handoff

**Status:** complete  
**Files produced:**
- `.agents/skills/<name>/SKILL.md`
- `.agents/evals/<category>/<name>/eval.yaml`

**Key decisions:**
- <any non-obvious choices made during synthesis or co-write — if obvious from the files, omit>

**Open threads:**
- <deferred items, follow-on issues, or unresolved tensions — if none, write "none">

**Next session start:**
- Load: `CONTEXT.md`, `docs/notes/skill-implementation-workflow.md`, next skill's issue file
- First action: Step 1 (source discovery) for `<next-skill-name>`

If this skill produced a cross-cutting observation — a pattern that appeared across two or more skills — add an entry to LESSONS.md now. Do not batch LESSONS.md updates to the end of the chunk; they lose precision.

---

Authoring standard

Frontmatter (required)

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

when: is added to all Chunk 3 skills now; full bidirectional reference convention (reverse map, reference scanner) is deferred to Chunk 4 for refinement.

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 (required, in this order)

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

Size: body ≤500 lines. Use XML tags only for skills with ≥3 logical sections and 500+ tokens; default to prose.

Refactor conventions

When refactoring an existing Pocock placeholder skill:

• The existing SKILL.md is one input to step 2 (source review)
• Use write-skill to produce the new SKILL.md — do not edit the old one in place
• Remove all dead references: setup-matt-pocock-skills, AGENT-BRIEF.md, OUT-OF-SCOPE.md
• Populate source: with the Pocock repo entry plus any other upstreams adopted
• Flat skill name may change (e.g. grill-with-docs → grill-me) — delete old directory, create new

---

Eval schema

Location: .agents/evals/<category>/<skill-name>/eval.yaml — committed to the repo.
Enforcement: CI gates are Chunk 6. The files document expected behaviour before then.

Every eval must contain all five required test types:

Type	Minimum count	Purpose
Explicit trigger test	≥1	User says the exact trigger phrase — skill must activate
Implicit trigger test	≥1	User describes the task without trigger phrase — skill must activate
Negative trigger test	≥1	Adjacent task that must NOT activate this skill
Deterministic output test	≥2	Schema/contains/regex assertions — blocking gates
LLM-rubric quality test	≥1	Quality catches that deterministic assertions cannot capture

Three eval categories (align language when writing evals):

• Trigger evals — does the description field activate correctly?
• Output evals — is the structured output correct and high-quality?
• Regression evals — did a model update break established behaviour? (run weekly in CI, Chunk 6)

When a human corrects a skill's output, that correction becomes a new eval test case. The eval suite grows from real failures.

---

source: pull criteria (upstream review, per-skill)

Upstream review happens per-skill during step 2, not once at chunk start.

Change type	Action
Trigger description or process sections changed	Always pull
New constraints or failure-handling cases added	Evaluate — pull if it closes a real gap
Formatting, wording, minor structural changes	Skip
Any upstream reviewed (pull or skip)	Update updated: date in source:

---

Open decisions carried forward

• when: full resolution — Chunk 4 (bidirectional reference convention, reference scanner tooling)
• 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