Skill Unification

Indexed Reference Map

• @[SKILL.md#L1-L101] Frontmatter, scope, trigger rules, SOP, output contract.
• @[references/INDEX.md#L1-L12] Reading order and doc map.
• @[references/QUICK_REFERENCE.md#L1-L22] Fast decision map and standard sequence.
• @[references/CORE_API.md#L1-L37] Merge model, lane model, cutover rules, and artifact contract.
• @[references/PATTERNS.md#L1-L24] Practical merge/cutover patterns and anti-patterns.
• @[references/EXAMPLES.md#L1-L13] Example prompts and expected deliverables.
• @[references/AI_WORKFLOW.md#L1-L14] Bounded AI workflow for running the skill.

Scope

• In-scope:
  • Merge two or more overlapping internal skills into one canonical skill.
  • Audit overlap, write merge map, patch canonical skill, self-audit, shadow test, and perform rollback-safe deprecation/cutover.
  • Remove stale config/runtime references after the unified skill is verified.
• Out-of-scope:
  • Blind deletion of legacy skills before the replacement is verified.
  • External/community skill installation from untrusted bundles.
  • Config mutation without schema check + verification.

Reading Order

1. references/INDEX.md
2. references/QUICK_REFERENCE.md
3. references/CORE_API.md
4. references/PATTERNS.md
5. references/EXAMPLES.md
6. references/AI_WORKFLOW.md

Coverage Matrix

• Overlap audit: required
• Merge map: required
• Canonical target selection: required
• Self-audit of unified skill: required
• Shadow test before cutover: required
• Rollback-safe deprecate/remove flow: required
• Config/runtime cleanup verification: required

Trigger Rules

• Positive:
  • User asks to merge, unify, consolidate, deduplicate, or replace overlapping internal skills.
  • User wants one canonical skill instead of multiple similar skills.
• Negative:
  • Do not trigger for ordinary edits to a single skill that do not involve multi-skill consolidation.
  • Do not trigger for external untrusted skills that first require static vetting.
• Escalation:
  • If config/runtime references must be changed, add schema-check + verification.
  • If the user wants immediate deletion, still require shadow verification before removing the old skill from live scan path.

SOP

1. Identify the candidate skills and choose the canonical target skill name.
2. Run overlap audit:
   • shared responsibilities
   • unique responsibilities
   • policy differences
   • output contract differences
3. Write a merge map with keep / merge / drop / rewrite decisions.
4. Patch the canonical target skill so it can cover all required lanes without losing existing safety boundaries.
5. Run self-audit on the canonical skill and fix stale references or governance drift until PASS.
6. Shadow test the unified skill on representative workloads (at minimum read/analysis plus any gated mutation-prep lane that matters).
7. Only after PASS:
   • remove old-skill config references
   • quarantine old skill tree into .ops/trash/<task-id>/
   • write a cutover manifest under .ops/state/<task-id>/
8. Verify:
   • canonical skill is Ready
   • deprecated skill is absent from live config and live scan path
   • rollback path exists
9. Report completed work with paths changed, verification results, rollback path, and remaining risk.

Error Handling

• If overlap is weak: stop and report that the skills should remain separate.
• If policy contracts conflict: prefer the stricter safety contract unless the user explicitly approves a policy reduction.
• If self-audit fails: fix governance debt before any cutover.
• If shadow test fails: do not deprecate/remove the old skill; keep both live and report the failure.
• If config cleanup fails after skill patching: stop at safe boundary and report exact stale references.

Output Contract

• Artifacts:
  • overlap audit summary
  • merge map
  • unified canonical skill files
  • self-audit result
  • shadow-test result
  • cutover manifest and rollback path (if cutover executed)
• Validation:
  • canonical skill PASS on self-audit
  • shadow-test PASS before removing old live skill
  • live config/path verification after cutover
• Compliance Verdict:
  • PASS when the merge is evidence-backed, rollback-safe, and the unified skill replaces the legacy skill without regression; otherwise PARTIAL or FAIL.