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
- `core/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

For each case, output an explicit **PASS** or **FAIL** result. Do not proceed to step b until all three show PASS. Including the description inside the section walk-through (step b) does not satisfy this gate — it must be a standalone test-then-proceed step with per-case verdicts. If any case fails, revise the description and re-test before continuing.

**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).

**d. Provenance — source and reference records**
Record provenance after upstream review. Two distinct kinds:
- Upstream provenance (repo slug, commit SHA, files adopted with inline comments, updated date). Present only if content was adopted. Absence = self-authored.
- General citations (research papers, documentation, standard specifications). Present only if the skill cites external research.

Both are recorded in the skill's own `references/sources.md`, keyed by the `source_keys:` its SKILL.md and reference files declare. `validate-provenance.sh` checks that chain.

**e. 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.
2. Human confirms the plan; then sub-agent writes the file.

Do not pass pre-designed test cases directly to a write agent — that collapses the plan-then-confirm gate into a single step, bypassing write-eval's own constraint. Co-located at `.agents/evals/<category>/<skill-name>/eval.yaml`. Must contain all five required test types (see Eval schema below).

**f. 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.

```markdown
## 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)

```yaml
---
name: skill-name
description: <trigger description — routing only; written and tested first; max 1024 chars>
metadata:
  category: <design|factory|implement|test|review|deploy|operate|cross-cutting|iac>
  version: <semver — mandatory for every skill; see ADR-0022>
# allowed-tools: <add only when the skill has a narrow, well-defined tool surface; omit otherwise>
---
```

### Body sections

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.

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.

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

- **Bidirectional reference convention** — Chunk 4 (reference scanner tooling; reverse map "what files point to X?").
- **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