Table of Contents generated with DocToc
.gitignore line[!IMPORTANT] Skill names differ on this install. This page‘s recommended path is a marketplace plugin install, invoked
/<plugin>:<alias>— e.g./magpie-security:issue-triage. Its fallback path is the pinned-snapshot whole-user install, invoked as a single token —/magpie-security-issue-triage, not/magpie-security:issue-triage. There is no plugin namespace on the fallback; themagpie-prefix is the namespace there, and the name is the skill’s directory name. See Skill names differ by install method.
This is one of the two ways to use Magpie, and it asks nothing of anybody else. You install the plugins you want and run them against whatever repo you are working in — one that has adopted Magpie, one that has not, one whose maintainers have never heard of it, one where you are the only person on the team who uses it. Nothing is committed, no shared settings file changes, and no teammate has to do anything.
It is not a lesser path or a waiting room for adoption. Most people who use Magpie use it exactly like this, indefinitely.
Two situations it covers, which used to be documented separately because they looked different and are not:
A marketplace plugin install already covers this: Claude Code keeps plugin state in one user-scope store (~/.claude/plugins/), so a plugin you install once is available in every repo you open next, adopted or not — nothing project-specific is required. See Step 1 below. The rest of this recipe is the .apache-magpie-local/ personal override directory (added in the framework's override surface; see agentic-overrides.md): a gitignored directory that lives in the target repo and provides your personal config layer. Because it is gitignored (and contains no binaries), adding it to a repo you do not own is safe and non-intrusive.
The recipe has four steps:
.gitignore line — keep your personal config untracked..apache-magpie-local/ — optionally add your overrides.docs/prerequisites.md)./magpie-setup-isolated-setup-install with whole-user (global) scope once. This sets up the sandbox allowlist for every repo on your host, not just adopted ones. If you have already done this for another Magpie-adopted project on this machine, skip this sub-step — whole-user scope covers the target repo automatically.Add the marketplace for your agent if you have not already, then install the families you want:
/plugin install magpie-setup@apache-magpie /plugin install magpie-pr-management@apache-magpie
That‘s it — nothing else in this step. Claude Code’s plugin state lives in one user-scope store (~/.claude/plugins/), so the skills are now available in every repo you open on this machine, Project X included, whether or not Project X has adopted Magpie. Skip to Step 2.
Use this instead of Step 1 only when a marketplace is not reachable (no plugin mechanism for your agent, or the project wants the signed ASF source release rather than a git clone).
In a normal project adoption, Magpie's skills are installed as gitignored symlinks under .agents/skills/ (canonical) and .claude/skills/ (Claude Code relay). Those symlinks exist only in the adopted repo and its worktrees.
For a non-adopted repo you need the skills at user scope so Claude Code can find them regardless of what directory you are in.
Pick a directory that will not move — you are about to create symlinks that point into it. A common convention:
git clone --depth=1 --branch main \ https://github.com/apache/magpie.git \ ~/dev/magpie
You can use any local path. The depth --depth=1 keeps the clone small; re-clone (or git pull) to refresh later.
Claude Code reads skills from ~/.claude/skills/ (user scope) in every session, regardless of the project directory. Link all framework skills there:
mkdir -p ~/.claude/skills for skill_dir in ~/dev/magpie/skills/*/; do skill_name=$(basename "$skill_dir") target=~/.claude/skills/magpie-${skill_name} # Overwrite stale link on re-run; skip if the name somehow collides ln -snf "$skill_dir" "$target" done
Verify the links are in place:
ls ~/.claude/skills/ | grep ^magpie-
You should see entries like magpie-pr-management-triage, magpie-issue-triage, magpie-security-issue-import, etc. — one per framework skill.
Why not
~/.agents/skills/? Claude Code‘s native user-scope path is~/.claude/skills/. Other agents (Codex, Cursor, Gemini CLI, …) use~/.agents/skills/. Add a parallel~/.agents/skills/loop if you want the skills available user-scope in those agents too; the framework’s per-project canonical dir is.agents/skills/, but the user-scope equivalent is left to each user's dotfile setup.
When the framework publishes updates, pull and refresh the links:
cd ~/dev/magpie && git pull # Re-run the symlink loop (idempotent; ln -snf updates stale targets): for skill_dir in ~/dev/magpie/skills/*/; do skill_name=$(basename "$skill_dir") ln -snf "$skill_dir" ~/.claude/skills/magpie-${skill_name} done
The symlinks resolve through to the updated source files automatically — you only need to re-run the loop when new skills are added to the framework (so new magpie-* names appear) or when old ones are removed (so stale links are pruned).
.gitignore lineIn the target (unadopted) repo, tell git not to track your personal config:
echo '/.apache-magpie-local/' >> .gitignore
This is the only change to committed files that this recipe requires. You can omit it if you plan to add .apache-magpie-local/ to your global gitignore instead (~/.gitignore_global or equivalent); either approach keeps the directory untracked.
If you do not want to touch the repo's .gitignore at all, add the entry to your global gitignore:
git config --global core.excludesFile ~/.gitignore_global echo '/.apache-magpie-local/' >> ~/.gitignore_global
mkdir -p /path/to/target-repo/.apache-magpie-local
The directory may be empty. Magpie skills check for .apache-magpie-local/<skill-name>.md before applying framework defaults — if the file is absent, defaults apply without error.
If you need a Project-X-specific behaviour adjustment, write it as agent-readable Markdown in a file named after the skill:
cat > /path/to/target-repo/.apache-magpie-local/pr-management-triage.md <<'EOF' ### Override 1 — Require two approvals for merge This project requires two approving reviews before a PR is merged (team policy, not enforced by GitHub branch protection yet). Treat a PR as mergeable only when it has ≥ 2 approvals. EOF
Overrides follow the same additive-only contract as committed overrides: they may add project-specific context, adjust defaults, or enable an extra capability (e.g. a release-manager enabling an extra MCP) — they may not weaken the safety, confidentiality, or privacy baseline the framework always applies.
See agentic-overrides.md for the full override contract and example shapes (skip a step, replace a step, add a step, pre-empt a decision-table row).
Open the target repo's directory in Claude Code and invoke any installed skill. On the marketplace install (Step 1), use /<plugin>:<alias>:
/magpie-pr-management:triage /magpie-issue:triage /magpie-security:issue-import /magpie-release-management:audit-report
On the pinned-snapshot fallback, use the single-token magpie- name instead:
/magpie-pr-management-triage /magpie-issue-triage /magpie-security-issue-import /magpie-release-audit-report
Either way, the skills are at user scope, so Claude Code finds them regardless of what project you are in. The skill reads .apache-magpie-local/<skill-name>.md (if present) before applying framework defaults, so your personal overrides are honoured without any project-wide config.
You will see the skill's override disclosure at the top: it names the file it read and lists the override headlines, so you know exactly what personal adjustments are active before the skill does anything.
From a teammate's perspective:
.gitignore change (if you commit it) adds one line. They can ignore it..apache-magpie-local/ directory is gitignored and never shows up in git status or in a PR for them..apache-magpie.lock.Most skills act only on behalf of the person invoking them and need nothing from your teammates. A few coordinate across contributors — assigning reviewers from a configured roster, sending onboarding mail, checking reviewer load — and those degrade gracefully when run this way: they work from the data available to you, and cannot read teammate configuration they cannot reach.
If a skill instead stops with something like “no <project-config>/ found” and proposes /magpie-setup, that is its pre-flight: it is looking for a committed project config — .apache-magpie-overrides/ — that this repo does not have, and it stops rather than guess at every unresolved placeholder in its body. A personal .apache-magpie-local/ does not satisfy that check today; the pre-flight does not read it. So on an unadopted repo the honest options are to ask the project to adopt, to add a minimal .apache-magpie-overrides/project.md yourself if you may commit to the repo, or to report it so the skill is fixed to degrade gracefully instead.
Skills that write to shared project state — labels, PR assignments, roster files — are the ones that benefit most from the project having adopted Magpie, because then the team has agreed on what the agent may touch.
| Works | Does not work |
|---|---|
| Every install — marketplace or snapshot — works exactly as it does on an adopted repo | A workflow skill run with no project config at all: its pre-flight stops and proposes /magpie-setup rather than guessing. The install is fine; what is missing is the repo's configuration |
All workflow skills — security-*, pr-management-*, issue-*, release-*, mentoring-*, pairing-*, repo-health-* — once the repo has a .apache-magpie-overrides/ for them to read | /magpie-setup verify / upgrade — these read the committed lock and snapshot, which do not exist here |
Personal overrides via .apache-magpie-local/ | Shared overrides (.apache-magpie-overrides/) — the committed override directory requires the project to have adopted |
setup-isolated-setup-install / -verify / -doctor (the secure-setup skills are user-scope artefacts, not per-project) | Drift and floor detection — there is no .apache-magpie.lock to compare against, so the pre-flight falls through to the project-config check above |
| The full safety, confidentiality, and privacy baseline (always applied regardless of adoption state) | — |
If a skill raises an unexpected “adoption required” message on a step that ought to work without adoption, that is a gap — file it on the framework issue tracker so the step can be made adoption-optional.
Nothing you did here is undone by that, and you do not have to switch paths.
A floor is a minimum, never a ceiling. Once the repo has adopted, the pre-flight at the top of every framework skill you run there compares your machine against the project's .apache-magpie.lock and brings you up to the floor it names if you fall short — installing or updating only the plugins the floor lists, then stopping so you can restart — and nothing more. If you are already at or ahead of the floor, a newer Magpie release, extra families installed, or both, the pre-flight changes nothing and says nothing: your own installs and versions are always left alone.
Adoption commits a recommendation: a default set of families that a contributor gets on clone, plus the repo's shared overrides. If you already have those families installed, nothing changes for you. If you do not, you can take the defaults or keep your own selection — the committed set is a floor, not an allowlist.
Your .apache-magpie-local/ keeps working either way. It sits at the top of the override lookup chain (.apache-magpie-local/ → .apache-magpie-overrides/ → framework default), so your personal overrides still win. Once the project has adopted, anything in there that everyone would want is worth moving into the committed .apache-magpie-overrides/ — and anything genuinely personal should stay where it is.
If the project also takes the pinned snapshot install — a separate decision from adopting — its project-scope skills will shadow any user-scope symlinks you set up under the fallback path in Step 1.
agentic-overrides.md — the full contract for .apache-magpie-local/ and .apache-magpie-overrides/, including override shapes and hard rules.secure-agent-setup.md — the secure-agent harness, worth running whether or not any repo has adopted Magpie.install-recipes.md — install methods, if you need the pinned snapshot rather than the marketplace.setup-status skill — reports what is installed and wired here, including whether .apache-magpie-local/ is present.