skill-migration-skill

/migrate-skill-to-engine — the dedicated skill-rewrite skill

Goal

• One reusable skill (user directive 2026-07-19) that moves an existing legacy skill/command onto the workflow engine using its classified smallest honest shape: stateful workflow, one-shot service, or context/reference capability. Existing test scenarios remain the conformance corpus.
• Methodical verbiage decontamination: every rewrite scans ALL prescriptive markdown (CLAUDE.md files, .claude/rules/**, the skill’s own body + references, sibling skills that cite it) for contradictory verbiage, old-state verbiage, and prose/historical verbiage about the old skill shape — any of which could mislead a weaker model — and cures them in the same rewrite.

Implementation sketch

• Author .claude/skills/migrate-skill-to-engine/ (role: tool; script-first: scripts/skill_migration_runtime/ owns the pipeline; the skill body only hands off decisions).
• The skill’s terminal deliverable per target skill is a SCAFFOLDED v7 MIGRATION PLAN (user directive 2026-07-19): the skill analyzes, then CREATES A PLAN (through scripts/create_plan_runtime — routing.md 1.0 sole creation path) whose sections carry the full rewrite for that skill; the plan executes through /continue-roadmap like any other. The skill never lands the rewrite inline.
• Analysis stages the runtime performs BEFORE scaffolding: (1) inventory — enumerate the surface’s declared behaviors, test scenarios, structured exits, semantic facts/owners, effects, human waits, callers, and every markdown surface that references it (grep-complete citation map); (2) fail-closed target-shape resolution from the exhaustive spec/migration-targets.md inventory and engine spec clause 13. A demonstrated mismatch reopens the inventory decision; it never defaults to a bespoke workflow.
• Plan sections the scaffold emits (per surface, parameterized): (a) implementation — stateful targets emit workflow JSON/components/catalog rows, one-shot targets emit/register the minimal service and ResultContract, and context/reference targets emit/register catalog/read-only lookup data without fake state; preserved scenarios are re-homed against the engine seam; (b) verify — applicable extension/catalog/spec conformance, scenario, client/context, replay/fault, and sec-11.4 performance gates green plus the public entrypoint replacement declaration; (c) verbiage/caller sweep — cure contradictory directives, stale state/path claims, historical prose that can control a weaker model, and bypass callers; (d) receipt/retirement — seal target shape/authority, evidence, public cutover, old-owner removals, and TerminalReceipt. Missing old-owner evidence leaves the surface adapter-wrapped.
• The sweep detector extends prose-lint.py label families where mechanical (old-skill-name-after-migration, retired-flag-reference) and emits a reviewer checklist for the judgment-only residue.
• Never edits locked designs without the unlock flag; never edits the engine core; single-skill-per-invocation.

Test strategy / acceptance

• Runtime pytest coverage for every pipeline stage (inventory completeness on a fixture skill, target-shape refusal on an unmapped skill, scaffolded-plan shape: sections a-d present with criterion probes, verbiage-sweep hit detection incl. contradictory-directive and stale-state fixtures, receipt schema).
• One REAL migration executed end-to-end as the production proof: /tp-help proves direct protocol_root one-shot service consumption after the paired authority reopen (conformance/performance green, public entrypoint cut over, scenarios re-homed, sweep report checked in, receipt sealed, old route retired).

Work Items

• Author scripts/skill_migration_runtime/ to inventory behavior/scenarios/exits/semantic owners/effects/human waits/callers/citations, resolve exactly one of the three target shapes from the exhaustive inventory, and scaffold implementation / applicable verification / verbiage-and-caller-sweep / receipt-and-retirement sections; reject missing/duplicate/dead inventory rows and any attempt to fabricate state for a one-shot/reference surface
• Author the verbiage-decontamination sweep: grep-complete citation map over CLAUDE.md files, .claude/rules/, .claude/skills/ for the target skill; classify contradictory-directive / stale-state / historical-prose hits; cure in place prescriptive-only; mechanical label families extended in prose-lint.py; scan report artifact
• Author .claude/skills/migrate-skill-to-engine/SKILL.md (role: tool, script-first thin body, @-includes routing/skill-template/skill-vocabulary SSOTs) consuming the runtime’s structured next_action envelopes
• Execute /tp-help end-to-end as the first protocol_root proof after the paired schema/vocabulary/verifier reopen: cut over the public entrypoint, run applicable conformance/scenario/replay/client/performance gates, retire the old dispatcher/context/result owners, and check in the sweep report plus sealed migration receipt

Intel dossier — pointer and tier disposition

Dossier: skill-migration-skill--s-9ab5aaa8.intel.md (this section’s content/intel/ sidecar)

Read that dossier from line 1 through EOF before acting on this section. This block is a pointer and an audit record, never a substitute: not the BLUF, not a summary, not selected tiers.