Migrate existing instructions

Overview

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 and keeps the local context each project needs in that project.

This guide builds your first hub from scattered instructions. You take an inventory, import one source at a time, and migrate what the scanner skips. Then you pilot the result and retire the duplicates.

To hand the inventory and import to a coding agent, copy this prompt. Set up PIG with a coding agent covers the whole setup.

Migrate our existing agent instructions into our Instruction Hub. Follow
https://promptless.ai/docs/governance/get-started/migrate-existing-instructions.md
and phase 2 of https://promptless.ai/docs/governance/agent-setup-guide.md

Outcome: an inventory table of our instructions with a proposed decision for
each, then the approved instructions imported on a migration branch that
passes `pig validate` and `pig verify`.
Scope: read the source repositories without editing them. Change only the hub.

Inputs (discover these before you ask me):
- Hub: [hub repository URL or local path]
- Sources: [repositories or directories that hold our current instructions]

Show me the inventory and wait for my decisions before you import anything.
Flag conflicting instructions and possible secrets. Report what you imported,
what needs manual migration, and what you left in place.

Before you start

You need:

A hub scaffold from Set up your Instruction Hub, checked out locally with the pig toolchain installed.
Read access to each repository or directory that holds your current instructions.
The owners of those instructions, to decide what to share and to reconcile conflicts.

Keep the original instructions in place 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

When only some paragraphs of a repository instruction file apply broadly, extract the reusable task into the hub. Keep paths, build commands, and local conventions in the project.

Import one source at a time

From your hub checkout, create a migration branch, scan one source, and review what changed:

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. It handles each kind of source file as follows:

Source	What happens
Direct skill directories under `.agents/skills/`, `.claude/skills/`, and `.cursor/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

pig scan adds each imported asset to plugins/pig.yaml. Move a reference 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.

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 and git diff to see changes to tracked files. Inspect new skill directories and MCP configurations directly. Record the source repository names in your migration notes, because hub.repo-context.json holds only the most recent scan’s inventory.

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 that says when it applies. Keep the local instructions in the original repository file. The setup guide shows 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 only. For guidance that must apply across agents, use 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

Check the migrated hub:

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:

Confirm the intended plugin is installed and its skill is available.
Invoke the skill against a real draft or code change.
Check that its reference files and helper scripts work from the installed location.
Confirm the agent still reads the project’s local instructions.
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 and still assume a tool or permission that 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 the original source history so you can restore the earlier files if the pilot exposes a gap. Make later changes in the hub through normal pull-request review, and keep no hand-maintained copies in projects.

The migration is complete when teammates can install the published release, complete the intended tasks, and know where to propose the next instruction change.