A step-by-step guide for a third-party repository or organization that wants Apache Magpie adopters to be able to pull its skills. It is the source-repo counterpart of README.md, which describes the same feature from the adopter's side.
Mental model. Your repo becomes a trusted skill source. Adopters do not copy your files. They add your source descriptor to their trust list, commit a pin (method + URL + ref + a verification anchor), and run /magpie-setup skill-sources (skills/setup/skill-sources.md), which fetches a verified, gitignored snapshot of your repo and symlinks your skills in so they run exactly like in-tree Magpie skills. Your job is to lay the repo out the way Magpie expects and to publish a descriptor plus a verifiable release. Per PRINCIPLES.md §13 nothing installs until an adopter vouches for you — being listed is discovery, never installation.
Magpie binds a skill to its eval suite by path, so keep the two roots it uses itself:
skills/<skill-name>/SKILL.md # the skill body (+ any helper files) tools/skill-evals/evals/<skill-name>/ # that skill's eval suite tools/<tool>/tests/ # unit tests, if a skill ships a tool
These are the defaults. If you must use different roots, declare them in the descriptor's layout: block (Step 5) — but keeping the defaults is the low-friction path.
Every SKILL.md must carry these required frontmatter keys — the skill validator enforces them:
--- name: <skill-name> description: <what it does / when to invoke it> license: Apache-2.0 # only Apache-2.0 is accepted capability: capability:<triage | resolve | …> ---
Optional keys: when_to_use, mode, status (and organization / source, which the framework fills in). Follow the framework authoring conventions in docs/extending.md and AGENTS.md — injection guards, the placeholder convention, no ASF-only coupling. Skill directory names must be globally unique: each becomes a magpie-<name> symlink in the adopter, so it must not collide with a framework skill or another source's skill.
Each eval step's fixtures/step-config.json uses a repo-relative skill_md: path. As long as skills/ and tools/skill-evals/evals/ stay sibling trees, the binding resolves after a fetch — the fetch pulls both trees plus any tool tests/ a skill depends on. See the layout contract.
The descriptor's organization: must name a directory under organizations/ in apache/magpie. Two paths:
organization: independent — the catch-all. Works out of the box, no change to Magpie.apache/magpie adding organizations/<your-org>/organization.md (mirror organizations/_template/), optionally with a skill-sources.md that curates your sources. Choose this if you want org-level branding and to vouch for your own sources at the org layer. See organizations/README.md.| Method | What adopters pin | Use when |
|---|---|---|
git-tag (recommended) | ref: <tag> + commit: <SHA> | Normal releases. Cut an immutable tag — never move a published tag; a moved tag fails the adopter's re-fetch guard as a supply-chain signal. |
svn-zip | ref: <version> + sha512: <hash> | You publish a released archive (optionally GPG-signed against a KEYS file). |
git-branch | ref: <branch> (no anchor) | WIP / preview only — no frozen anchor, tip-tracking. |
The fetch reuses the framework install recipes verbatim, so these are the same three methods and anchors the framework snapshot uses for itself.
This is the block an adopter (or your org's skill-sources.md) carries. Required keys: id, organization, name, method, url, ref, provides.
- id: acme-security-skills # unique, kebab-case — the handle pointers reference organization: independent # or your registered org name: "Acme Security Skills" maintainer: "Acme Sec Team / @acme-handle" method: git-tag url: https://github.com/acme/magpie-skills ref: v1.0.0 commit: <SHA the tag resolves to> # git-tag anchor (or sha512: <hash> for svn-zip) layout: # omit when you use the defaults skills_root: skills evals_root: tools/skill-evals/evals provides: - skill: acme-secret-scan # one skill… - family: acme-audit-* # …or a whole prefix-family
Full field reference: README.md § Source descriptor.
Open a PR to apache/magpie adding:
registry.md — the discovery index; and/ororganizations/<your-org>/skill-sources.md — org curation.Listing is discovery only — it never triggers an install. The adopter's <project-config>/skill-sources.md trust list is always the gate.
Run Magpie‘s own validator against your repo so your skills and descriptor pass the same checks an adopter’s CI runs:
git clone --depth=1 https://github.com/apache/magpie /tmp/magpie # from your source repo root: uv run --project /tmp/magpie/tools/skill-and-tool-validator skill-and-tool-validate
It checks SKILL.md frontmatter / naming / injection guards, descriptor shape (required keys, a supported method, a known organization), and flags any skill directory missing an eval suite.
An adopter adds your descriptor to <project-config>/skill-sources.md — by id alone if your org curates it, or in full otherwise — commits the pin, and runs:
/magpie-setup skill-sources
That fetches + verifies your source into .apache-magpie-sources/<id>/ and symlinks the skills you provide. The adopter side is documented in README.md § How a trusted skill is installed.
commit (or the new sha512). Adopters bump their pin deliberately; the bump shows up in their PR diff, exactly like a framework-lock bump.provides reach adopters on their next /magpie-setup upgrade, which re-fetches per the committed pin and refreshes the symlinks.README.md — the feature from the adopter's side (formats, trust model, security model).registry.md — the discovery index of known sources.RFC-AI-0006 — the design, trust, and threat model.skills/setup/skill-sources.md — the /magpie-setup skill-sources fetch/pin/symlink flow.docs/extending.md — the full extension model (what / where / who).