skills-vault/docs/migration-guide.md

Migration Guide

This guide is for migrating automation Skills from scattered non-CCPE folders into skills-vault.

Scope Gate

Before migrating, confirm:

• The source is outside C:\Users\wangq\Documents\Codex\ccpe-system.
• The artifact is an automation Skill or tool-like Skill.
• The artifact is not a CCPE agent, committee, runtime, model card, or existing CCPE Skill specification.

If the source is CCPE content, do not migrate it.

Migration Steps

1. Create a target directory:

   skills/<skill-name>/
   

2. Copy or reconstruct the Skill source:

   SKILL.md
   scripts/
   tests/
   fixtures/
   README.md
   

3. Preserve the original behavior first.

4. Add a short migration note to the Skill README:

   Original source:
   Migration date:
   Migration status:
   Behavior preserved:
   Known gaps:
   

5. Add or repair tests when practical.

6. Register the Skill in:

   registry/skills-index.md
   

7. If needed, install or sync the Skill into:

   C:\Users\wangq\.agents\skills\<skill-name>
   

8. Commit the migration.

Migration Status Values

Use these status values in the registry:

candidate
migrated
tested
installed
deprecated
archived

First-Pass Rule

The first migration pass should be conservative:

• keep the original behavior
• avoid style rewrites
• avoid unnecessary abstraction
• capture tests before refactoring

Refactor in a later commit after the Skill is stable in the vault.

CCPE Registration Rule

Do not create CCPE registrations during ordinary migration.

Only register a Skill in CCPE when a CCPE agent, runtime, or committee explicitly depends on it.