Template

<!-- ═══════════════════════════════════════════════════════════════════════════ SKILL TEMPLATE — agent-revamp-skills Copy this file into skills/<NN-phase>/<skill-id>/<skill-id>.md Replace every <<PLACEHOLDER>> with real content before marking status: stable. Do not delete any section heading or its comment block. ═══════════════════════════════════════════════════════════════════════════ -->

1. Purpose

<!-- WHAT TO WRITE One paragraph, 3–6 sentences, plain English. No bullet points. Answer three questions in order: (a) What problem does this skill solve? (b) Who runs it, and at what point in the migration? (c) What is the key constraint or risk it manages? COMMON MISTAKES - Describing HOW the skill works (belongs in Steps). - Listing what it needs (belongs in Inputs). - Writing "This skill migrates X" and nothing else — no context, no risk framing. EXAMPLE (one sentence each of a–c) "This skill extracts the authentication service from a Rails monolith into a standalone Rack app behind a shared JWT issuer. A backend engineer runs it once per authentication boundary, after the strangler-fig proxy is in place (Phase 3). The primary risk is session continuity: existing tokens must remain valid across both implementations during the dual-run window." -->

<<3–6 sentence description of purpose, who runs it, and the key risk it manages.>>

---

2. Trigger Conditions

<!-- WHAT TO WRITE Two explicit lists: "Use when" (positive triggers) and "Do NOT use when" (anti-triggers). Each item must be a concrete, observable signal — not a vague intention. COMMON MISTAKES - "Use when: you want to migrate something." — too vague; any skill matches this. - Omitting anti-triggers. Without them, skills get run at the wrong phase. - Listing the same condition in both lists. EXAMPLE trigger : "The Phase 3 strangler-fig proxy is deployed and health-checked." EXAMPLE anti-trigger: "The audit report (Phase 1) has not been completed for this unit." -->

Use when:

• <<Observable signal that this skill is appropriate — be specific.>>
• <<Observable signal 2.>>
• <<Observable signal 3 (add or remove rows as needed).>>

Do NOT use when:

• <<Condition that makes this skill wrong or dangerous to run.>>
• <<Condition 2 — include at least one phase-order anti-trigger.>>
• <<Condition 3 (add or remove rows as needed).>>

---

3. Inputs

<!-- WHAT TO WRITE Two tables: Required and Optional. For every input: the exact name used in Steps, its type, and a clear description. TYPES: file-path | string | boolean | enum(<values>) | json-file | integer COMMON MISTAKES - Listing an input as Optional when a missing value would break a Step. - Omitting the Default column for Optional inputs (every optional must have one). - Using vague names like "config" or "path" — be specific: "audit_report_path". EXAMPLE Required row : | `target_module` | string | The module name as it appears in the migration manifest. | EXAMPLE Optional row : | `--dry-run` | boolean | false | Preview changes without writing files. | -->

Required:

Input	Type	Description
<<input_name>>	<<type>>	<<What it is and where to get it.>>
<<input_name>>	<<type>>	<<What it is and where to get it.>>

Optional:

Input	Type	Default	Description
<<input_name>>	<<type>>	<<default>>	<<What it controls and when to override the default.>>
<<input_name>>	<<type>>	<<default>>	<<What it controls and when to override the default.>>

<!-- STOP CONDITION: If any Required input is absent at runtime, Claude must halt and ask: "I need <<input_name>> to proceed. <<Where the user can find it>>." Do not infer or guess required inputs. -->

---

4. Steps

<!-- WHAT TO WRITE Numbered, ordered, imperative instructions. This is the executable core of the skill. Each step is a direct command to Claude — written as if Claude is the subject. VOICE RULES - Correct : "Read <<file>>. Extract all exported function names." - Incorrect : "<<file>> should be read" / "You may want to look at <<file>>." STEP ANATOMY <number>. <imperative action> - If this fails: <recovery action or escalation> - → Hand off to `<agent-name>` (see Section 5. Agent Handoffs) COMMON MISTAKES - Steps that reference context not defined in Inputs ("use the config from earlier"). - Steps without failure handling on destructive or network-dependent actions. - Steps so coarse they hide ambiguity ("migrate the service") — each step must be unambiguous to a cold Claude session with no prior context. EXAMPLE "1. Read `<<audit_report_path>>`. Extract the list of exported symbols for `<<target_module>>`." "2. Search for every import of those symbols across `<<repo_root>>`. Write matches to `output/<<skill-id>>-symbol-map-<<timestamp>>.json`." " - If this fails: check that `<<repo_root>>` is accessible and retry once." -->

1. <<First step — read, load, or gather the inputs declared in Section 3.>>
2. <<Second step — perform the primary analysis or transformation.>>
   • If this fails: <<Recovery action — retry, fallback, or escalate to user.>>
3. <<Third step.>>
   • → Hand off to <<agent-name>> (see Section 5. Agent Handoffs) if <<condition>>.
4. <<Write all outputs to the paths declared in Section 7.>>
5. <<Run the Equivalence Tests defined in Section 6. Record results.>>
6. <<Evaluate every item in Section 9 Done Criteria. Report pass/fail for each.>>

---

5. Agent Handoffs

<!-- WHAT TO WRITE One block per sub-agent this skill delegates to. If the skill is self-contained, write "None — this skill is self-contained." with a one-sentence reason. Each block must include: - Agent file path (in agents/) - The Step number that triggers the handoff - A complete, self-contained prompt template using <<PLACEHOLDER>> syntax for values that are resolved at runtime from Inputs or prior Steps. COMMON MISTAKES - Copying the agent's system prompt here — don't. Reference the file; only supply the task-specific prompt template. - Using vague placeholders like {{stuff}} — every placeholder must match an Input name or a named output from a prior Step. - Forgetting to specify OUTPUT_FILE — agents must always write to a file. EXAMPLE ## code-archaeologist - **File:** `agents/code-archaeologist.md` - **Triggered by:** Step 3 - **Prompt template:** ``` TASK: Inventory all usages of <<target_module>> in <<repo_root>>. SCOPE: <<repo_root>>/src OUTPUT_FILE: output/<<skill-id>>-inventory-<<timestamp>>.md FORMAT: markdown ``` -->

<<agent-name | None>>

<!-- Replace the heading with the agent name, or keep "None" and delete this block. -->

• File: agents/<<agent-file>>.md
• Triggered by: Step <<N>>
• Prompt template:

  TASK:        <<Specific task for this invocation.>>
  REPO_ROOT:   <<repo_root>>
  SCOPE:       <<subdirectory or glob, or "all">>
  OUTPUT_FILE: output/<<skill-id>>-<<agent-name>>-<<timestamp>>.<<ext>>
  FORMAT:      <<markdown | json>>
  

---

6. Equivalence Tests

<!-- WHAT TO WRITE A table of behavioral tests that prove the migrated component is equivalent to the original. These tests are run in Step 5 and their results feed into Done Criteria. This section answers: "How do we know the new thing does what the old thing did?" It is NOT a test plan — it is a concrete, runnable specification. COLUMNS - Test Name : Short identifier, kebab-case. Used in Done Criteria to reference results. - Input : The exact stimulus — HTTP request, function call, CLI command, SQL query. - Expected Output: The exact response the migrated implementation must produce. - Tool : The Claude Code tool or external command used to run the test. Examples: Bash, WebFetch, Read, custom test runner command. COMMON MISTAKES - Vague Expected Outputs like "returns successfully" — specify status codes, shapes, values. - Omitting error-path tests — at least one row must test an invalid or edge-case input. - Using "manual" as the Tool with no description of what to do manually. - Having fewer than 3 rows (aim for coverage of: happy path, error path, edge case). EXAMPLE ROWS | auth-happy-path | POST /auth/login {user:"alice", pass:"correct"} | 200 {token: <jwt>} | Bash: curl -s ... | | auth-wrong-pass | POST /auth/login {user:"alice", pass:"wrong"} | 401 {error: "..."} | Bash: curl -s ... | | auth-missing-field | POST /auth/login {user:"alice"} | 400 {error: "..."} | Bash: curl -s ... | -->

Test Name	Input	Expected Output	Tool
<<test-happy-path>>	<<Exact input — request, call, command, or query.>>	<<Exact expected response — status, shape, value.>>	<<Bash | Read | WebFetch | <<command>>>>
<<test-error-path>>	<<An invalid or missing input that should trigger an error.>>	<<Expected error response — code, message.>>	<<Tool>>
<<test-edge-case>>	<<A boundary input — empty, max-length, concurrent, etc.>>	<<Expected output for this edge.>>	<<Tool>>
<<test-name-4>>	<<Input>>	<<Expected Output>>	<<Tool>>

<!-- Add more rows as needed. Remove placeholder rows that don't apply. Every test listed here must be referenced by name in Section 9 Done Criteria. -->

---

7. Outputs

<!-- WHAT TO WRITE A table of every artifact this skill writes to disk. Nothing goes only to stdout. COLUMNS - Artifact : Human-readable name. - Path Pattern : Relative path from repo root. Use <<timestamp>> to avoid collisions. - Format : markdown | json | yaml | shell | csv | other - Description : What the file contains and who consumes it next. COMMON MISTAKES - Listing outputs without <<timestamp>> in the path — causes overwrites on reruns. - Forgetting to list the equivalence test results file. - Describing what the file IS rather than what it CONTAINS and who USES it. EXAMPLE ROW | Migration log | `output/<<skill-id>>-log-<<timestamp>>.md` | markdown | Step-by-step record of changes made; reviewed by engineer before cut-over. | -->

Artifact	Path Pattern	Format	Description
<<Artifact name>>	output/<<skill-id>>-<<artifact>>-<<timestamp>>.<<ext>>	<<format>>	<<What it contains and who/what uses it next.>>
<<Artifact name>>	output/<<skill-id>>-<<artifact>>-<<timestamp>>.<<ext>>	<<format>>	<<What it contains and who/what uses it next.>>
Equivalence test results	output/<<skill-id>>-equiv-<<timestamp>>.md	markdown	Pass/fail results for every row in Section 6; required input for Section 9 Done Criteria.

---

8. References

<!-- WHAT TO WRITE A pointer list — internal skill paths, reference docs, and (sparingly) external URLs. This is a navigation aid, not a literature review. Keep it short. RULES - Always include the anti-patterns doc when the skill involves destructive operations. - Always include the strangler-fig doc when the skill touches traffic routing or dual-write. - Prefer internal paths over external URLs. External URLs rot. - One line per reference: `path or URL` — one-sentence description of what it adds. COMMON MISTAKES - Listing a reference that has nothing to do with this specific skill. - External URLs without a description of why they're relevant. - Linking to the template itself in a real skill (fine here; remove in copies). EXAMPLE - `references/strangler-fig-pattern.md` — dual-write and traffic-shifting mechanics -->

• skills/_template/SKILL.md — this template (remove this line in real skills)
• references/strangler-fig-pattern.md — <<remove if not applicable>>
• references/migration-anti-patterns.md — <<remove if not applicable>>
• references/stack-compatibility-matrix.md — <<remove if not applicable>>
• <<skills/<related-skill>/ — description of why it's related.>>
• <<external URL — one sentence on what it adds that internal docs don't cover.>>

---

9. Done Criteria

<!-- WHAT TO WRITE A binary checklist. Every item must be objectively pass/fail — no judgment calls. Claude evaluates each item and reports its verdict before declaring the skill complete. Minimum 5 items. A skill with all items checked is DONE; any unchecked item means NOT DONE. ITEM ANATOMY - [ ] <Gate description> — <how Claude verifies it (file exists / grep / test result / etc.)> MANDATORY ITEMS (keep all of these; add skill-specific items above them) - [ ] All output files exist at their declared paths in Section 7. - [ ] Every equivalence test in Section 6 has a recorded result (pass or fail). - [ ] No equivalence test in Section 6 is recorded as fail. - [ ] The output report includes a confidence level (High / Medium / Low). - [ ] The output report includes a numbered assumptions list. COMMON MISTAKES - "Code quality looks good" — not binary; cannot be objectively checked. - Duplicating an item from Section 6 Equivalence Tests without connecting it to a test name. - Fewer than 5 items — the mandatory items alone give you 5; add skill-specific ones on top. - Items that can only be checked by a human with no description of what they check. EXAMPLE SKILL-SPECIFIC ITEMS - [ ] `pre-migrate.sh` exited 0 for `<<target_module>>` in `<<env>>` — check hook log. - [ ] No references to the old module path remain in `<<repo_root>>/src` — grep confirms. -->

• <<Skill-specific gate 1>> — <<how Claude verifies this.>>
• <<Skill-specific gate 2>> — <<how Claude verifies this.>>
• <<Skill-specific gate 3 — e.g., pre-migrate hook exited 0.>> — check output/migration-run-log.jsonl.
• All output files listed in Section 7 exist at their declared paths — verify with file read.
• Every equivalence test in Section 6 has a recorded result in output/<<skill-id>>-equiv-<<timestamp>>.md.
• No equivalence test in Section 6 is recorded as fail — review results file.
• The output report includes a confidence level (High / Medium / Low) — grep for "Confidence:".
• The output report includes a numbered assumptions list — grep for "Assumptions:".