Migrate existing instructions

Move instructions into a hub when several people or repositories need the same guidance. A useful first migration gives one team a small, reviewed set of shared procedures while preserving the local context each project needs.

This guide covers adopting your first hub from scattered instructions. Begin with the scaffold from Set up your Instruction Hub, and work on a migration branch. Keep the original instructions available until you have tested the published plugins.

Inventory what you already use

List the source, owner, audience, and intended destination of each instruction. Include repository files, personal skills that teammates share, MCP configurations, and instructions copied into team documents.

Existing instruction	Decision	Destination in the Acme example
Documentation review procedure used by several teams	Share and assign an owner	assets/skills/review-docs/SKILL.md in docs
Bug investigation procedure	Share	assets/skills/investigate-bug/SKILL.md in dev
Commands for testing one service	Keep local	That service’s AGENTS.md or equivalent
Product terminology used across documentation	Share as reference material	The relevant skill’s references/ directory
A developer’s private API token in an MCP config	Replace with host-provided authentication	Reviewed config in assets/mcps/
Two conflicting versions of the same procedure	Reconcile with their owners	One canonical skill

Do not move an entire repository instruction file into a shared plugin just because some paragraphs apply broadly. Extract the reusable task and keep paths, build commands, and local conventions with the project.

Import one source at a time

From your hub checkout:

git switch -c migrate-instructions
pig scan --hub . --source /path/to/acme-docs
git status --short
git diff

pig scan leaves the source repository unchanged. Its imports are deliberately limited:

Source	What happens
Direct skill directories under .agents/skills/	Copies each skill and its supporting files into assets/skills/
First root file found in .mcp.json, mcp.json, mcp.yaml, mcp.yml order	Copies it as the repo-mcp asset
.cursor/mcp.json	Imports a Cursor-specific asset when it is not already covered by the root MCP configuration
Root AGENTS.md, CLAUDE.md, and GEMINI.md	Records an inventory in hub.repo-context.json; does not copy or convert their instructions
Other skill locations, rules, commands, agents, and hooks	Requires manual migration

Imported references are added to plugins/pig.yaml. Move those references into plugins/docs.yaml or plugins/dev.yaml when the instructions belong to that audience. Leave shared assets in pig, or include the same asset in several plugins when needed.

Caution

Scan replaces an existing skill with the same generated ID, and MCP imports use fixed IDs such as repo-mcp. It also replaces the repository-context inventory with the latest scan. Review and commit each source separately; scanning several repositories at once can overwrite earlier imports.

Before scanning another repository, give conflicting assets distinct IDs and update their plugin references. Skill IDs come from their directory names, normalized to lowercase letters, digits, and hyphens. To compare same-named skills, scan the second repository into a separate temporary hub. Copy only the reviewed result into the main migration branch.

Use git status to find new files as well as git diff to see changes to tracked files. Inspect new skill directories and MCP configurations directly. Record source repository names in your migration notes: hub.repo-context.json is an inventory of the most recent scan, not a migration ledger for all repositories.

Migrate instructions the scanner does not import

For a skill stored under a different host directory, copy its complete directory into assets/skills/<id>/, keeping SKILL.md and any relative references together. Replace machine-specific paths and commands with instructions that the intended audience can use. Add skill:<id> to the appropriate plugin.

For a shared passage in AGENTS.md or CLAUDE.md, write a focused skill with a description explaining when it applies. Keep the original repository file’s local instructions. The setup guide provides a starting format in its skill-authoring step.

Rules, commands, agents, and hooks need explicit target support metadata. For example, a Cursor rule in assets/rules/docs-style.mdc can use this adjacent docs-style.asset.yaml file:

support:
  cursor:
    mode: native

Add rule:docs-style to its plugin. This declaration distributes the native rule to Cursor; it does not make it a Claude or Codex rule. For guidance that must apply across agents, consider a portable skill. Review support modes before translating host-specific behavior.

Review scripts before sharing them and replace embedded credentials with the host’s supported authentication mechanism. Check that supporting files contain no private material outside the intended audience. The toolchain rejects symlinks; copy the actual reviewed files instead.

Validate and pilot the migration

pig validate --hub .
pig verify --hub .

Review the changes with the instruction owners, then publish the hub and install the plugins on a pilot machine. Try a representative task in each agent your team uses:

1. Confirm the intended plugin is installed and its skill is available.
2. Invoke the skill against a real draft or code change.
3. Check its reference files and helper scripts work from the installed location.
4. Confirm the agent still reads the project’s local instructions.
5. Check for duplicate skills or conflicting rules from old installations.

Treat compilation and host installation as separate checks. A portable source file can compile correctly while an instruction still assumes a tool or permission the receiving agent lacks.

Retire the duplicate sources

After the pilot succeeds, tell teammates which plugins to install and which earlier copies they replace. Remove only the shared instructions now delivered by those plugins. Retain project-specific files and any guidance the hub does not yet cover.

Keep the migration commit and original source history so you can restore the prior files if the pilot exposes a gap. Make subsequent changes in the hub and use normal pull-request review; avoid maintaining another copy by hand in each project.

The migration is complete when teammates can install the published release, complete the intended tasks, and identify where to propose the next instruction change. Trace collection is optional; add it later by planning an analyzer deployment and enrolling your hosts.