Table of Contents generated with DocToc

• How to use Magpie on a team where not everyone has adopted it
  • Overview
  • Prerequisites
  • Step 1 — Install Magpie at whole-user (global) scope
  • Step 2 — Add one .gitignore line to the shared repo
  • Step 3 — Create your personal config directory
  • Step 4 — Run skills as normal
  • What your teammates see (nothing)
  • What works vs what does not
  • Skills that assume every teammate has Magpie
  • If the team later adopts Magpie
  • Cross-references

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.

The mechanism is the same one used for unadopted repos: a whole-user install (so skills are available in every directory you work in) plus a .apache-magpie-local/ personal directory (gitignored, so it stays off the repo’s history). Your teammates open the same files and branches they always have; nothing about the repo changes from their point of view.

The recipe has four steps:

1. Whole-user install — make Magpie skills available in any repo.
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 — Install Magpie at whole-user (global) scope

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:

mkdir -p ~/.claude/skills
for skill_dir in ~/.magpie/.claude/skills/*/; do
    skill_name=$(basename "$skill_dir")
    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 skill:

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

The skills find the framework via the user-scope symlinks (Step 1), 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 adopt as normal; the one .gitignore line you added is already present and helps them.

What works vs what does not

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 adopt in the shared repo (see install-recipes.md) — this commits the bootstrap skill and lock, wires the skill symlinks under .agents/skills/ and .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 adoption 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.