Authoring a trusted skill source

Authoring a trusted skill source

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.

Step 1 — Lay out the repo in the two-tree shape

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.

Step 2 — Author each skill in the Magpie shape

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.

Step 3 — Keep the eval binding resolvable

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.

Step 4 — Pick your organization identity

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.
Register your org — open a PR to 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.

Step 5 — Choose a distribution method + verification anchor

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.

Step 6 — Write your source descriptor

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.

Step 7 — Get listed for discovery (optional, recommended)

Open a PR to apache/magpie adding:

a row to registry.md — the discovery index; and/or
your descriptor to organizations/<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.

Step 8 — Validate before you publish

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.

Step 9 — Tell adopters how to pull it

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.

Step 10 — Maintain the source

New release → cut a new tag and publish its commit (or the new sha512). Adopters bump their pin deliberately; the bump shows up in their PR diff, exactly like a framework-lock bump.
Keep the two-tree layout stable so eval bindings keep resolving after a fetch.
Additions to provides reach adopters on their next /magpie-setup upgrade, which re-fetches per the committed pin and refreshes the symlinks.