Table of Contents generated with DocToc
When Magpie ships no adapter for your backend — a forge, a CNA tool, a chat system, a mail archive, a VCS, or a whole organization profile — you author one. The skills stay agnostic: they target a capability, and your adapter supplies the concrete backend. This guide is the how-to; the registry is the index of what already exists.
| In-tree (upstream) | In your adopter repo | External (another repo) | |
|---|---|---|---|
| Where it lives | a PR into apache/magpie | <project-config>/.apache-magpie-overrides/ | a repo you/the community maintain |
| License | Apache-2.0 (§17) | yours | the author's |
| Who reuses it | every adopter on that backend | your project | anyone who wires it in |
| Discovery | shipped in-tree | committed in your repo | optionally listed in the registry |
| Install | part of the snapshot | committed override | you wire it in deliberately — never auto-fetched (§13) |
All three are first-class. Contribute upstream when the backend is one other projects share; keep it in your adopter repo when it is specific to your project; keep it external when a third party maintains it or it is shared across your repos but not in Magpie. See docs/extending.md for the same model applied to every extension type.
A tool adapter fulfils a capability contract for one backend.
tools/<contract>/ whose capability you are implementing (e.g. tools/cve-tool/ for a CNA tool, tools/mail-archive/ for an archive). Its README enumerates the methods/verbs your adapter must provide. If no contract exists for the capability, propose one first.tools/<contract>-<backend>/ (in tree) or a directory in your own repo (external). Implement the contract's operations.tools/AGENTS.md):**Capability:** contract:NAME (or substrate:NAME) line in the README;## Prerequisites section (runtime, CLIs, credentials, network);**Organization:** <org> line if the adapter belongs to a specific organization.<project-config>/project.md Tools enabled manifest (or the relevant capability key, e.g. cve_authority.tool) at the adapter. Skill bodies never change.tools/skill-evals/evals/ so the adapter's behaviour is graded, not just demoed.The write-skill flow and CONTRIBUTING.md walk the conventions in detail; skill-and-tool-validate enforces the capability + prerequisites lines.
An organization groups governance vocabulary + capability→adapter selections + identity for every project under one governing body. To add one, copy organizations/_template/ to organizations/<org>/, fill in organization.md (identity incl. logo, governance vocabulary, and the backend bundle), and point projects at it with organization: <org>. See organizations/README.md.
/magpie-setup upgrade, the adapter is available to everyone.