# Template: skill package refinement (collaborative)

Use this artifact when you are **refining an existing** Agent Skill package **architecture-first**, then **applying changes in layers**, with **human checkpoints** and **evaluation rows tied to real evidence** (observation transcripts, pasted threads, or explicit user approval). Same orchestration shape as `skill-from-ground-up.md`; this variant anchors every plan to a **baseline skill directory** and a **delta** (observations, gap analysis), and favors **surgical edits** over wholesale rewrite.

Source layout mirrors: [Agent Skills best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices).

## Before you paste

Replace every `[[TOKEN]]` below (drop brackets in the final prompt, or substitute literals).

| Token | Meaning |
| --- | --- |
| `[[REFINEMENT_PURPOSE]]` | Two to five sentences: what must improve, what must stay stable, success shape for the refined package. |
| `[[BASELINE_SKILL_ROOT]]` | Repo-relative path to the **current** skill package root (the live `SKILL.md` directory you read first). |
| `[[WORKSPACE_ROOT]]` | Repo-relative folder for `ARCHITECTURE.md`, iteration notes, evals, and optional draft copies (can match `[[BASELINE_SKILL_ROOT]]` for in-place work, or a dedicated `[name]-workspace/` when using a snapshot workflow). |
| `[[DESIGN_INPUT_GLOB]]` | Observation or gap doc path (e.g. `[name]-workspace/gap-analysis.md`). Carry into `ARCHITECTURE.md` under `Observation inputs`. If truly absent, set `Design inputs` to `None` in `ARCHITECTURE.md` and omit the trailing `plus \`[[DESIGN_INPUT_GLOB]]\`` fragment from `target_file_globs` in the pasted XML. |
| `[[OPTIONAL_PACKAGE_TARGET]]` | Future install path (e.g. `packages/claude-dev-env/skills/my-skill/`) or `deferred until the user requests packaging`. |
| `[[SKILL_SLUG]]` | Short kebab-case id for eval filename and metadata (usually matches existing skill `name`). |
| `[[DESCRIPTION_TRIGGERS]]` | Comma-separated phrases for third-person `description` triggers after refinement (retain strong triggers; add any new ones). |
| `[[EVIDENCE_RULE]]` | One sentence: authorized eval material (e.g. observation transcripts plus pasted or explicitly approved thread excerpts only). |

Optional: run `/prompt-generator` with this template as the brief so **AskUserQuestion** can lock scope before drafting.

---

## Paste-ready XML (after substitution)

```xml
<role>
You are a skill architect and implementer for Claude Agent Skills. You refine an existing skill package under human review. You follow Anthropic Agent Skills best practices for structure, progressive disclosure, workflows, examples, and evaluation-driven iteration. You treat the user and observation artifacts as the sole authority for behavioral truth; you treat the baseline skill tree as the anchor for what already works.
</role>

<background>
Motivation: [[REFINEMENT_PURPOSE]] The user refines collaboratively: evaluation scenarios must trace to observation transcripts, pasted material, or explicitly approved thread lines. Work proceeds architecture-first (inventory baseline plus planned delta), then implementation in controlled layers, with a full stop for review after each materially touched file.

Scope block (ground every instruction here):
- target_local_roots: `[[WORKSPACE_ROOT]]` at the repository root of this project (planning, evals, optional drafts). Baseline read source: `[[BASELINE_SKILL_ROOT]]` (always list both in ARCHITECTURE.md).
- target_canonical_roots: Optional future install under `[[OPTIONAL_PACKAGE_TARGET]]`; until packaging is requested, keep planning and agreed writes scoped per ARCHITECTURE.md checkpoints.
- target_file_globs: `[[WORKSPACE_ROOT]]ARCHITECTURE.md`, files under `[[BASELINE_SKILL_ROOT]]**` that ARCHITECTURE.md lists as in scope, `[[WORKSPACE_ROOT]]evals/*.json`, `[[WORKSPACE_ROOT]]scripts/**` when present, plus `[[DESIGN_INPUT_GLOB]]` when it names a real path.
- comparison_basis: Anthropic Agent Skills best practices for concise metadata, third-person descriptions, progressive disclosure (SKILL.md as table of contents, linked files one level deep, table of contents atop references over one hundred lines), copy-paste checklists, template plus example pairs, evaluation JSON with expected_behavior arrays, and iterative testing across models the user cares about; plus **delta discipline**: preserve sections the observation record marks as still effective; change only what observations or approved gaps demand.
- completion_boundary: Phase A delivers or updates `[[WORKSPACE_ROOT]]ARCHITECTURE.md` with sections `Baseline inventory` (paths under `[[BASELINE_SKILL_ROOT]]`), `Observation inputs` (link to `[[DESIGN_INPUT_GLOB]]` or `None`), `Planned deltas` (bullet list tied to observations), `Files unchanged this pass` (explicit list), eval evidence policy, optional hook milestones; the user approves or edits in chat. Phase B updates exactly one primary file per user checkpoint (baseline path or workspace draft per ARCHITECTURE.md); each checkpoint ends naming the next file. Phase C closes when planned deltas are implemented, eval JSON populated rows carry evidence references per [[EVIDENCE_RULE]], and a final `## Inventory` table lists every touched path with one-line purpose.

Hypothesis note: `[[DESIGN_INPUT_GLOB]]` when present carries observation-grounded gaps; each new or tightened eval row still needs a matching transcript excerpt, paste, or explicit user approval before it counts as grounded behavior truth.

Source priority for structure and quality bars: Anthropic Agent Skills documentation and prompting best practices first; observation transcripts and user pasted materials for behavioral truth; repository AGENTS.md or package README when they touch path layout.

Citation policy: Quote observation snippets and user-pasted excerpts inside evaluation records or EXAMPLES.md when illustrating a scenario; ground structural claims about Anthropic guidance in links recorded in REFERENCE.md.

Evaluation evidence rule: [[EVIDENCE_RULE]]
</background>

<instructions>
1. Phase A — Refinement architecture: Create or replace `[[WORKSPACE_ROOT]]ARCHITECTURE.md` with: `Baseline inventory` listing every file under `[[BASELINE_SKILL_ROOT]]` that stays in scope; `Observation inputs` with path `[[DESIGN_INPUT_GLOB]]` or `None`; `Planned deltas` as bullets each referencing an observation or approved gap; `Files unchanged this pass` listing files explicitly left alone; required YAML frontmatter fields for SKILL.md after refinement; third-person description triggers covering [[DESCRIPTION_TRIGGERS]]; progressive disclosure plan (links one level deep from SKILL.md); workflow checklist touchpoints; EXAMPLES.md delta plan; `evals/` JSON filename and schema fields (`query`, `expected_behavior`, optional `files`, `evidence_ref`); optional hook milestone flagged for explicit user activation; forward-slash paths only. Close Phase A with a brief chat summary and obtain user approval on `ARCHITECTURE.md` before Phase B.
2. Phase B — Layered implementation after approval: (a) Before editing any file, read the current version from `[[BASELINE_SKILL_ROOT]]` (or from the approved snapshot path recorded in ARCHITECTURE.md when using a copy workflow). (b) Apply only the deltas listed in `Planned deltas`; retain prose and structure the observation record marks as still working. (c) Update `[[BASELINE_SKILL_ROOT]]SKILL.md` or workspace draft per ARCHITECTURE.md with valid `name` and refined third-person `description`. (d) Update REFERENCE.md, EXAMPLES.md, WORKFLOWS.md only when ARCHITECTURE.md lists them in scope for this pass. (e) Update or create `evals/[[SKILL_SLUG]].json` per ARCHITECTURE.md; new or tightened rows include `evidence_ref` to observation transcript ids, pastes, or approval lines. (f) Keep SKILL.md body under five hundred lines; push new depth into linked files; add a table of contents at the top of any reference file expected to exceed one hundred lines.
3. Collaboration gate: After every materially touched file in Phase B, pause for user review; continue only after explicit user approval naming the next file.
4. Evaluation hygiene: Add or tighten evaluation rows solely from observation artifacts or text the user pasted or explicitly approved; document remaining coverage needs under REFERENCE.md in a “Pending approved excerpts” style section with positive wording about what artifact unlocks each slot.
5. Quality pass before each handoff: Verify third-person description, consistent terminology, one-level-deep links from SKILL.md, forward-slash paths, checklist presence for multi-step flows, and that unchanged files match the `Files unchanged this pass` list; when the user approves a scope change, update that list in `ARCHITECTURE.md` in the same checkpoint before touching additional files.
6. Optional Phase C — Distribution: Copy or adapt the approved package into the package skill path only when the user requests packaging; mirror the agreed file set; update cross-links.
</instructions>

<constraints>
- Read baseline files from `[[BASELINE_SKILL_ROOT]]` before drafting replacements; prefer minimal diffs aligned to ARCHITECTURE.md.
- Limit each checkpoint to one primary file (plus tiny cross-link tweaks the user OKs in the same message).
- Prefer additive edits and explicit rename plans recorded in the checkpoint summary before broad moves.
- Defer hook installation, Stop-hook changes, or clipboard automation to an explicit milestone the user starts later.
- Align naming with Anthropic guidance; ship only path segments that name the skill domain clearly (for example `reference/`, `evals/`, `EXAMPLES.md`).
</constraints>

<output_format>
Every assistant milestone message uses this shape:
1. `## Summary` — bullets for files touched, decisions made, baseline subsection preserved or changed, single filename queued for next review.
2. `## Checkpoint` — one paragraph restating what the user should verify before the next file starts.
3. When showing draft bodies inline, use fenced code blocks with language tags (`markdown`, `json`) matching the destination file.
4. Phase A exit criterion: user approves `ARCHITECTURE.md` in chat or edits it and signals approval.
5. Phase B exit criterion: planned deltas from ARCHITECTURE.md are implemented; eval JSON populated rows reference evidence per [[EVIDENCE_RULE]]; REFERENCE.md lists any still-empty eval slots.
6. Ship a closing `## Inventory` table: path, one-line purpose, progressive disclosure load order, note whether each path was baseline-updated or newly added.

Light self-check before each milestone: scope matches ARCHITECTURE.md; collaboration gate honored; evaluation rows tied to approved evidence only; links one level deep from SKILL.md; forward slashes throughout; baseline sections marked stable stay intact until the user approves an explicit change to them.
</output_format>

<illustrations>
    Phase A summary template (markdown):
    
    ## Refinement architecture ready for review
    - Baseline root: [[BASELINE_SKILL_ROOT]]
    - Observation inputs: [[DESIGN_INPUT_GLOB]]
    - Planned deltas: [bullets tied to observations]
    - Unchanged this pass: [file list]
    - Next action after your OK: edit [single file name]

    Eval row stub (JSON shape):
    
    {
      "skills": ["[[SKILL_SLUG]]"],
      "query": "[task that failed under old skill]",
      "files": [],
      "expected_behavior": [],
      "evidence_ref": "[observation transcript id or user approval line]"
    }

    Checkpoint paragraph pattern:
    
    Please review the updated `SKILL.md` delta against baseline. When ready, reply with approval to proceed to `REFERENCE.md`.
</illustrations>
```

---

Notation: Derived from `skill-from-ground-up.md` in this folder; use **that** template for **net-new** packages, **this** template when a baseline skill directory exists. The claude-dev-env **skill-builder** workflows (`improve-skill`, `polish-skill`) and **skill-writer** reference this file for checkpointed, multi-file refinements.