How to use Magpie on a team where not everyone has adopted it

Overview

You work on a repo with other people. You want to use Magpie skills — to triage issues, draft security responses, or review PRs — but your teammates have not adopted Magpie and are not interested in doing so yet.

This recipe shows how to run Magpie only for yourself against a shared repo, without committing any framework artefacts, without changing the project's settings files, and without asking teammates to do anything.

A marketplace plugin install already covers this: Claude Code keeps plugin state in one user-scope store, so the plugins you install are available in every repo you open, this shared one included — nothing project-specific is required and your teammates see nothing change. The rest of this recipe is the .apache-magpie-local/ personal directory (gitignored, so it stays off the repo's history) for your personal config layer.

The recipe has four steps:

1. Marketplace install (recommended) — install the plugins you want once; they are then available in every repo, this one included. A pinned-snapshot whole-user install is the fallback, for when a marketplace is not reachable.
2. Add one .gitignore line — keep your personal config untracked.
3. Create .apache-magpie-local/ — your personal config layer.
4. Run skills — invoke them against the shared repo normally.

Prerequisites

• Claude Code installed and working.
• You have at least read access to the shared repo (clone or existing working copy on your machine).
• Your teammates have not (and need not) install anything.

Step 1 — Marketplace install (recommended): covers every repo

Add the marketplace and install the plugins you want, exactly as in the quick start:

/plugin marketplace add apache/magpie
/plugin install magpie-setup@apache-magpie
/plugin install magpie-pr-management@apache-magpie

That's it. Claude Code's plugin state lives in one user-scope store, so the skills are now available in every repo you open on this machine, this shared one included — whether or not it has adopted Magpie. Skip to Step 2.

Fallback — pinned-snapshot whole-user install

Use this instead of Step 1 only when a marketplace is not reachable.

A per-project adoption wires Magpie skills as symlinks under the repo's .agents/skills/. In a mixed-adoption team you cannot commit those symlinks, so you need skills available at user scope instead — where Claude Code finds them in every directory you open.

Clone the framework to a stable personal location:

git clone --depth=1 --branch main \
    https://github.com/apache/magpie.git \
    ~/.magpie

Create user-scope skill symlinks so Claude Code finds the skills in any project. Link through the clone's canonical .agents/skills/ entries — the one home every agent-specific dir relays into (see agents.md) — not through a relay dir such as .claude/skills/, which would add a pointless third hop:

mkdir -p ~/.claude/skills
for skill_dir in ~/.magpie/.agents/skills/*/; do
    skill_name=$(basename "$skill_dir")   # already magpie-<skill>
    ln -sfn "$skill_dir" ~/.claude/skills/"$skill_name"
done

Install the secure agent setup at user scope. This wires the sandbox allowlist so the secure posture applies to every repo on your machine, not just adopted ones:

# From any directory:
/magpie-setup-isolated-setup-install

When prompted for scope, choose whole-user (global). If you have already done this for another Magpie-adopted project on this machine, the user-scope sandbox already covers new repos automatically — skip this sub-step.

Keeping skills current — pull the framework clone periodically:

git -C ~/.magpie pull --ff-only
# Symlinks stay valid; no re-linking needed.

Step 2 — Add one .gitignore line to the shared repo

Your personal config directory (.apache-magpie-local/) must not land on the repo's history. Add it to the repo's .gitignore:

echo '.apache-magpie-local/' >> .gitignore
git add .gitignore
git commit -m 'chore: ignore .apache-magpie-local (personal Magpie config)'

If the repo uses a per-user gitignore convention (~/.gitignore_global or git config core.excludesFile) and you prefer not to commit a .gitignore change, add .apache-magpie-local/ there instead. The directory will still stay untracked; it just will not be visible to teammates who clone the repo later.

If you do not want to commit a .gitignore change at all, add the directory to your global gitignore:

echo '.apache-magpie-local/' >> ~/.gitignore_global
# or wherever your core.excludesFile points

Either approach works. Committing the .gitignore line is friendlier to future adopters and makes the intent visible, so it is the recommended path.

Step 3 — Create your personal config directory

mkdir -p /path/to/shared-repo/.apache-magpie-local

The directory can stay empty. Framework skills check for it at startup; an empty directory is equivalent to "no personal overrides, use defaults."

Optional — add a project-context override so skills know where to look for the tracker, upstream repo, or security list:

# .apache-magpie-local/project.md
# Personal project context for <PROJECT> — not committed.
tracker: https://github.com/<ORG>/<PROJECT>
upstream: https://github.com/<ORG>/<PROJECT>

Replace <ORG> and <PROJECT> with the values for your shared repo. This is the same format as a committed projects/<project>/project.md; the personal version is just read from a different directory. See agentic-overrides.md for the full override syntax.

Step 4 — Run skills as normal

Open Claude Code in the shared repo's directory and invoke any installed skill. On the marketplace install (Step 1), use /<plugin>:<alias>:

/magpie-issue:triage
/magpie-pr-management:triage
/magpie-security:issue-import

On the pinned-snapshot fallback, use the single-token magpie- name instead:

/magpie-issue-triage
/magpie-pr-management-triage
/magpie-security-issue-import

Either way, the skills find the framework at user scope, read your personal context from .apache-magpie-local/ (Step 3), and proceed exactly as they would in a fully adopted repo.

What your teammates see (nothing)

From a teammate's perspective:

• The .gitignore change (if you commit it) adds one line. They can ignore it.
• The .apache-magpie-local/ directory is gitignored and never shows up in git status or PRs for them.
• No shared settings file changes. No committed skill symlinks. No .apache-magpie.lock file.
• Their own Claude Code sessions are unaffected — the user-scope skills live in your ~/.claude/, not theirs.

A teammate who later wants to adopt Magpie runs /magpie-setup install as normal; the one .gitignore line you added is already present and helps them.

What works vs what does not

Scenario	Works without full adoption?
Running any read-only skill locally (triage, stats, review)	Yes
Drafting outbound messages (email, comments) for human review	Yes
Using personal overrides from .apache-magpie-local/	Yes
Skill drift detection and upgrade checks	Yes (user-scope install)
Framework version pinning shared with the team	No — without a committed .apache-magpie.lock, each team member's install drifts independently. If consistent framework behaviour across team members matters, full adoption is the right next step.
Per-project committed overrides (.apache-magpie-overrides/)	Partial — you can read them from .apache-magpie-local/ if you copy them locally, but they are not committed. Any shared customisations that should be consistent across the team should go into .apache-magpie-overrides/ via full adoption.
Automated CI or bot runs using Magpie skills	No — CI needs a committed install.

Skills that assume every teammate has Magpie

Most Magpie skills only act on behalf of the person invoking them and do not require teammates to have the framework installed. A few skills, however, coordinate across contributors (for example, assigning reviewers from a configured roster, sending onboarding emails via the committer onboarding skill, or checking reviewer load). Those skills degrade gracefully when run personally: they operate on the data available to you but cannot read teammate configuration they cannot reach.

If a skill fails outright with a message like "no <project-config>/ found" or "adapter not configured", it means it is trying to read a committed project config that does not exist in the unadopted repo. The fix is either:

• Add a minimal project.md to your .apache-magpie-local/ to satisfy the lookup, or
• File the hard failure as a gap and open an issue against apache/magpie so the skill is fixed to degrade gracefully.

The mixed-adoption pattern is intended to work for read-heavy, local skills. Skills that write to shared project state (labels, PR assignments, roster files) work best in a fully adopted repo where the team has agreed to let the agent touch those surfaces.

If the team later adopts Magpie

When the project decides to adopt, the transition from your personal setup is straightforward:

1. Run /magpie-setup install in the shared repo (see install-recipes.md) — this commits the bootstrap skill and lock, wires the canonical skill symlinks under .agents/skills/ plus a relay into them from .claude/skills/, and adds the sandbox block to the shared .claude/settings.json.
2. Move any project context from .apache-magpie-local/project.md into the committed projects/<project>/project.md.
3. Move any personal overrides from .apache-magpie-local/ that should be shared into .apache-magpie-overrides/.
4. Keep .apache-magpie-local/ for anything that remains personal (your local clone paths, personal MCP servers).

The .gitignore line you added in Step 2 is already correct for the adopted setup — .apache-magpie-local/ stays gitignored even after full adoption.

Cross-references

• Agentic overrides — full contract for what you can put in .apache-magpie-local/ and .apache-magpie-overrides/, including enabling role-specific MCP servers just for yourself.
• Full install recipe — if the team later decides to adopt Magpie, this is the canonical install walkthrough.
• Secure agent setup — the full install reference including the user-scope sandbox.
• Setup skill family — overview of all setup skills and deep documentation pages.