Extending Magpie

July 7, 2026 · View on GitHub

Magpie is built to be extended without forking it. This page is the map: what you can extend, where an extension can live, and who typically owns each kind.

If you only remember one rule: extensions are discovered and wired in deliberately, never auto-installed — per PRINCIPLES.md §13, indexes and catalogs exist for discovery, not installation.

What you can extend

Entity	What it is	Reference
Skill	a workflow the agent follows	`PRINCIPLES.md` §14, `write-skill`
Skill source	a trusted external repo a skill/family is pulled from	`docs/skill-sources/`, `RFC-AI-0006`
Tool / tool adapter	the only layer that knows a vendor — a backend behind a capability contract	vendor-neutrality § Tool adapters, `adapters/authoring.md`
Capability contract	the stable verb set a skill depends on; the seam adapters plug into	`tools/cve-tool/` and siblings
Organization	governance vocabulary + backend bundle + identity, shared by an org's projects	`organizations/README.md`
Project config	one adopter's concrete values	`projects/_template/`
User config	one person's preferences (handle, governance membership, local clone paths)	`AGENTS.md` § user.md

Where an extension can live (the three homes)

Every extension — a skill, an adapter, or a whole organization — has the same three possible homes. They are not mutually exclusive: start local, upstream later.

Home	Where	Travels with	Licence	Best when
In-tree (upstream)	a PR into `apache/magpie`	the framework, to every adopter	Apache-2.0 (§17)	the extension is broadly useful — other projects share the backend/org
In your adopter repo	`<project-config>/` + `<project-config>/.apache-magpie-overrides/` (committed)	your repo	yours	it is specific to your project, or not ready to upstream
External (another repo)	a repo you (or a community) maintain, referenced from config	nothing automatically — you vendor/clone it in deliberately	the author's	a third party maintains it, or it is shared across your repos but not in Magpie

The middle home is the framework's snapshot + override model (§13): the framework is a gitignored snapshot; your additions and tweaks are committed agent-readable markdown alongside it. The external home is the same act of wiring-in as the middle one — you just keep the source in another repo and the registry lists it for discovery.

How each entity resolves across homes

Skills — framework skills come from the snapshot; project tweaks live in .apache-magpie-overrides/<skill>.md (consulted at run time); a wholly new skill you keep can live in your repo's agent-skill dir. A skill or skill-family maintained in another repo can also be pulled in from a trusted external source — a skills/<name>/source.md redirect that names a pinned, verified source the adopter has vouched for, fetched into the snapshot and wired in like a framework skill. This is the one external home that installs rather than merely being referenced (see PRINCIPLES.md §13 and docs/skill-sources/).
Tools / adapters — selected per capability in <project-config>/project.md Tools enabled. The selected adapter may be an in-tree tools/<name>/, a directory you keep in your adopter repo, or one you vendored from an external repo. Skills never branch on the choice. See adapters/authoring.md.
Organizations — organization: <org> in project.md resolves to an in-tree organizations/<org>/ first; if your organization is not in-tree, it resolves to an adopter-local org adapter you keep under <project-config>/.apache-magpie-overrides/organizations/<org>/ (copied from your own or another repo). Either way the resolution chain is project.md → organization → framework default.

Who extends what

A project (adopter)

Owns its <project-config>/: identity, per-skill config, and .apache-magpie-overrides/ for behaviour tweaks. A project may also keep a local organization or adapter in its override layer when no in-tree one fits — and upstream it later with setup-override-upstream.

An organization (foundation / company / collective)

Owns an organization adapter — the defaults every project under it inherits (CVE authority, mail/forwarder/archive backends, governance vocabulary, identity + logo). It can ship that adapter in-tree (contributed to apache/magpie, so all its projects and others reuse it) or maintain it in the organization's own repo and have member projects point at it. See organizations/README.md.

An individual

Owns their user.md (per-user preferences, resolved first-match across $APACHE_MAGPIE_USER_CONFIG → ~/.config/apache-magpie/user.md → <project-config>/user.md). An individual can also author any skill, adapter, or organization above and choose a home for it — contribute it upstream, keep it in their project's override layer, or maintain it in a personal repo and link it.

Contributing an extension back

Whatever the home you start with, upstreaming is one PR away and benefits every adopter:

a skill — write-skill + CONTRIBUTING.md;
a tool/adapter or organization — adapters/authoring.md;
an override you have been running — setup-override-upstream.