Table of Contents generated with DocToc
Apache Magpie
Adopt a Magpie. Magpie is a curated set of skills for the AI agent you
already use — Claude Code, Codex, Antigravity, Copilot and others — that take
on the repetitive parts of running an open-source project: triaging issues and
pull requests, reviewing code, mentoring contributors, drafting fixes, and
handling security reports end to end.
Three things make it different from a folder of prompts:
- Nothing is sent in your name. Every comment, email, label and PR is
drafted by the agent and posted by a person. There is no autonomous mode.
- The agent is confined before it reads anything real. A filesystem and
network sandbox, a credential-stripped environment, and a deterministic
guard that inspects each shell command before it runs and denies the ones
that break a hard rule — not a prompt asking it nicely.
- It is an Apache project, not a product. Apache-2.0, vendor-neutral
across agents, no account and no service in the middle. Telemetry is opt-in
per project and off by default — install it and never run a skill, and it
generates no outbound traffic at all.
Magpie is currently in development for ASF projects + Python Core team
friendlies. Testers welcome!
See it in action
One security report, start to finish — installed from the marketplace, the
agent sandboxed and guarded, then the report imported, triaged against the
project's history, fixed, and published as a CVE:
Illustrative — a written transcript, rendered deterministically, not a
recording. The interactive version
on the project site steps through the same story with the full output of each
command.
[!IMPORTANT]
The motivation, scope, and design commitments behind this work
live in MISSION.md — the founding mission of the
Apache Magpie Top-Level Project, originally filed as its
establishment proposal. Read that for the why; this README is
the how once you've decided to install.
Install
Start here → Quick start — a handful of commands,
in the agent you already use. Nothing is written to your repository.
/plugin marketplace add apache/magpie # Claude Code
/plugin install magpie-setup@apache-magpie # install this one first
/plugin install magpie-vetted-ops@apache-magpie # always: the skills run on it
/plugin install magpie-agent-guard@apache-magpie # the baseline:
/plugin install magpie-utilities@apache-magpie # take all four
/plugin install magpie-pr-management@apache-magpie # + the families you need
Those first four are the baseline — and the same set a project commits as
its floor when it adopts Magpie, so taking them is taking what a project would
recommend to every contributor. After that, install one plugin per family you
actually want: every installed skill costs context on every turn, used or
not (~0.2–2.0k tokens a family), so there is deliberately no
install-everything plugin.
Once magpie-setup is in, you never type these again — ask in plain language
("install the Magpie families for PR review") and the setup skill runs the
installs for you.
Codex, VS Code / Copilot, Antigravity, Pi and Goose are short too — the
quick start has each of them, plus what to run next to put
the agent in its sandbox. Nothing is committed to your repository.
Fallback — the pinned snapshot install. Use it when a marketplace is not
an option or not enough: your agent has no plugin mechanism, you need the
signed ASF source release rather than a git clone, or the project wants every
contributor and CI job pinned to one committed version with drift detection.
- Download / pin a release
- Set up the symlinks and git-ignores — see
docs/setup/install-recipes.md
- Ask your agent to complete the install:
/magpie-setup:setup install
The two are complementary, not exclusive.
Usage
Magpie is used by interacting with your AI agents. You'll use plain-language
prompts like
review PR #5193
or
triage the latest security reports
or skill calls starting with a slash, like
/magpie-repo-health:dependency-audit
(the family-plugin form, assuming the recommended marketplace install above —
see Skill names differ by install method
if you're on the pinned-snapshot fallback instead).
Update / maintain
Marketplace install (the recommended path above):
/plugin marketplace update apache-magpie then
/plugin update <plugin>@apache-magpie — refresh the marketplace
metadata, then bump the installed plugin(s) to its latest.
Auto-update does the same in the background once enabled.- Reconciliation needs no extra step.
Each skill checks itself on its first run after an upgrade and proposes any fixes your configuration or overrides need.
To check the whole project at once, run
/magpie-setup:setup reconcile.
See Reconciliation when a skill first runs after an upgrade.
- If you use the secure agent setup, the same pre-flight proposes
/magpie-setup:isolated-setup-update after an upgrade that changed its files, and weekly otherwise.
Run it directly to check now.
See Automatic reminders from the pre-flight.
- Add or drop families by installing or uninstalling their plugin —
there is no separate "pick families" step once you're on a
marketplace install.
Pinned-snapshot install (the fallback):
/magpie-setup upgrade — refresh the snapshot to a newer
framework version + reconcile any overrides against the new
framework structure./magpie-setup verify — read-only health check (snapshot
intact, symlinks live, .gitignore correct, etc.)./magpie-setup:setup override <framework-skill> — open or
scaffold an override file for a framework skill.
Skill families
The following skill families ship in the framework, all at experimental or
stable, and each skill declares its family in a family: frontmatter
key. On the recommended marketplace install, you choose families by which
per-family plugin(s) you install (see Install above) — install
or uninstall a plugin at any time to add or drop a family. On the
pinned-snapshot fallback, /magpie-setup offers the opt-in families —
and the optional MCP servers (ponymail, apache-projects,
gmail-plaintext) — in a single install choice, and symlinks for the picked
families land in the skill directory. Either way, the two always-on
families (setup, utilities) are wired unconditionally and never prompted
for.
The Modes column maps each family to the MISSION agent-assistance
taxonomy — see docs/modes.md for what each mode
means and which modes are still proposed vs. shipping today.
| Family | Type | Modes | Purpose | Detail |
|---|
| setup | always-on | (infra) | Isolated agent setup, framework install + maintenance, shared-config sync. The prerequisite — at minimum the setup skill itself runs out of this family. | 12 skills, docs/setup/ |
| utilities | always-on | (meta) | Framework meta-skills: author skills (write-skill), restructure them (optimize-skill), reconcile skill state (skill-reconciler), report framework issues (report-framework-issue), and print a live index (list-skills). | 5 skills |
| security | opt-in | Triage, Drafting | 16-step security-issue handling lifecycle — from security@ import through CVE publication, including state sync — plus producing, verifying, and maintaining the project's own security model. Maintainer-only. | 16 skills, docs/security/ |
| pr-management | opt-in | Triage | Maintainer-facing PR-queue management — triage, stats, deep code review, stack review, express-lane merge, stale-sweep, reviewer routing, and pre-first-PR checks. | 9 skills, docs/pr-management/ |
| issue |
External skill sources
Skill families or individual skills can be pulled
from a trusted external source — a repo other than apache/magpie that
ships Magpie-shaped skills (with their evals and tests). Where a skill
directory would sit, a skills/<name>/source.md redirect names a
pinned, verified source the adopter has vouched for; /magpie-setup fetches
it into the gitignored snapshot and wires it in exactly like a framework
skill. Nothing is fetched unless the adopter commits the pin — see
docs/skill-sources/,
PRINCIPLES.md §14,
and RFC-AI-0006.
Acknowledgements
Apache Magpie was first developed and proven inside Apache Airflow, and was
maintained for a time as the apache/airflow-steward repository under the
Airflow PMC before being renamed and established as its own project. It also
incorporates early skill work contributed by way of the Apache Groovy
community. All of that code carries the same rightsholder — Copyright The Apache
Software Foundation, under the Apache License 2.0 — so it is not a third-party
inclusion; the required attribution lines from the originating projects' NOTICE
files are reproduced in NOTICE.
Cross-references
MISSION.md — founding mission of the established TLP: motivation, scope, design commitments, initial PMC composition target.docs/setup/agentic-overrides.md — the contract between adopters who write overrides and framework skills that read them.docs/prerequisites.md — what a maintainer needs installed before invoking any framework skill (Claude Code, Gmail MCP, GitHub auth, browser, uv, etc.).docs/source-release-contents.md — what ships in the signed apache-magpie-<version>-source.zip (and what is excluded), with the rationale for the repository-root metadata/config files it keeps.docs/release-management/manual-release-process.md — the concrete, as-executed runbook for cutting a Magpie release by hand on the current hybrid SVN-dist + ATR-vote backend (with the abstract per-backend runbooks and the 14-step lifecycle alongside it in docs/release-management/).AGENTS.md — agent instructions, placeholder convention, framework conventions.CONTRIBUTING.md — for framework contributors.
