Table of Contents generated with DocToc
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.
| 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 |
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.
.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/).<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.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.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.
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.
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.
Whatever the home you start with, upstreaming is one PR away and benefits every adopter:
write-skill + CONTRIBUTING.md;adapters/authoring.md;setup-override-upstream.docs/vendor-neutrality.md — the skills / tools / capabilities / organizations architecture.docs/adapters/registry.md — discovery index of in-tree and external adapters.organizations/README.md — the organization entity and its resolution order.