apache · potiuk · Jul 3, 2026 · Jul 3, 2026
diff --git a/docs/skill-sources/README.md b/docs/skill-sources/README.md
@@ -188,6 +188,7 @@ only; it makes no guarantee and triggers no install.
 
 ## See also
 
+- [`authoring-a-source.md`](authoring-a-source.md) — the source-repo side: how a third-party org publishes skills for adopters to pull.
 - [`RFC-AI-0006`](../rfcs/RFC-AI-0006.md) — the design + trust + threat model.
 - [`docs/extending.md`](../extending.md) — the full extension model (what / where / who).
 - [`organizations/README.md`](../../organizations/README.md) — the organization layer and its `skill-sources.md` curation.

diff --git a/docs/skill-sources/authoring-a-source.md b/docs/skill-sources/authoring-a-source.md
@@ -0,0 +1,198 @@
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+- [Authoring a trusted skill source](#authoring-a-trusted-skill-source)
+  - [Step 1 — Lay out the repo in the two-tree shape](#step-1--lay-out-the-repo-in-the-two-tree-shape)
+  - [Step 2 — Author each skill in the Magpie shape](#step-2--author-each-skill-in-the-magpie-shape)
+  - [Step 3 — Keep the eval binding resolvable](#step-3--keep-the-eval-binding-resolvable)
+  - [Step 4 — Pick your organization identity](#step-4--pick-your-organization-identity)
+  - [Step 5 — Choose a distribution method + verification anchor](#step-5--choose-a-distribution-method--verification-anchor)
+  - [Step 6 — Write your source descriptor](#step-6--write-your-source-descriptor)
+  - [Step 7 — Get listed for discovery (optional, recommended)](#step-7--get-listed-for-discovery-optional-recommended)
+  - [Step 8 — Validate before you publish](#step-8--validate-before-you-publish)
+  - [Step 9 — Tell adopters how to pull it](#step-9--tell-adopters-how-to-pull-it)
+  - [Step 10 — Maintain the source](#step-10--maintain-the-source)
+  - [See also](#see-also)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+     https://www.apache.org/licenses/LICENSE-2.0 -->
+
+# 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`](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](README.md#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`](../../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](../../PRINCIPLES.md#13-snapshot-plus-override-never-vendored-copies)
+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:
+
+```text
+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](../../tools/skill-and-tool-validator/) enforces them:
+
+```yaml
+---
+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`](../extending.md) and
+[`AGENTS.md`](../../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](README.md#layout-contract--skills-evals-tests).
+
+## 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/`](../../organizations/_template/organization.md)),
+  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`](../../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](../setup/install-recipes.md) 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`.
+
+```yaml
+- 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](README.md#source-descriptor).
+
+## Step 7 — Get listed for discovery (optional, recommended)
+
+Open a PR to `apache/magpie` adding:
+
+- a row to [`registry.md`](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:
+
+```bash
+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:
+
+```text
+/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](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.
+
+## See also
+
+- [`README.md`](README.md) — the feature from the adopter's side (formats, trust model, security model).
+- [`registry.md`](registry.md) — the discovery index of known sources.
+- [`RFC-AI-0006`](../rfcs/RFC-AI-0006.md) — the design, trust, and threat model.
+- [`skills/setup/skill-sources.md`](../../skills/setup/skill-sources.md) — the `/magpie-setup skill-sources` fetch/pin/symlink flow.
+- [`docs/extending.md`](../extending.md) — the full extension model (what / where / who).