feat(skill-sources): trusted external skill sources — design, §13, formats, validator (Phase A)

AGENTS.md

@@ -332,6 +332,18 @@ yields. When this document says a value comes from
 `<project-config>/project.md`, read it as "from `project.md`, else the
 project's organization, else the framework default".
 
+A project may also **pull skills from a trusted external source**. The
+committed `<project-config>/skill-sources.md` file is the install gate: it
+lists the source ids the adopter trusts and commits each pin (method + URL
++ ref + verification anchor). Where a skill directory would sit, a
+`skills/<name>/source.md` redirect (frontmatter `source:` / `organization:`
+/ `skill_path:` / `evals_path:`, **not** a `SKILL.md`) names the source;
+`/magpie-setup` fetches it into the gitignored snapshot and wires it in like
+a framework skill. Per [`PRINCIPLES.md` §13](PRINCIPLES.md#13-snapshot-plus-override-never-vendored-copies)
+this is the one external home that *installs* rather than being merely
+referenced — pinned, verified, and adopter-vouched. See
+[`docs/skill-sources/`](docs/skill-sources/README.md).
+
 ### Placeholder convention used in skill files
 
 Skill files, tool-adapter docs, and this file use a small set of

PRINCIPLES.md

@@ -124,7 +124,7 @@ Skills, tool adapters, and root docs use `<PROJECT>` / `<tracker>` / `<upstream>
 
 ## 13. Snapshot plus override, never vendored copies
 
-Adopters consume the framework as a gitignored snapshot at `.apache-magpie/`, pinned via a committed lock file, refreshed by one skill (`setup`). Project-specific modifications live as agent-readable markdown under `<project-config>/.apache-magpie-overrides/`, committed. No git submodules. No vendored copies of framework skills inside adopter repos. Marketplaces, indexes, and catalogs may exist for discovery, never for installation.
+Adopters consume the framework as a gitignored snapshot at `.apache-magpie/`, pinned via a committed lock file, refreshed by one skill (`setup`). Project-specific modifications live as agent-readable markdown under `<project-config>/.apache-magpie-overrides/`, committed. No git submodules. No vendored copies of framework skills inside adopter repos. Marketplaces, indexes, and catalogs exist for discovery. Installation is permitted only from a **trusted source** — an external organization or repository the adopter has explicitly vouched for by committing its pin (method + URL + ref + verification anchor) to the repo. Everything else stays discovery-only. A trusted install obeys the same snapshot-plus-pin discipline as the framework itself: a gitignored snapshot, a committed lock, a verified and deliberate fetch by the one `setup` skill — never a git submodule, and never an unpinned or unverified auto-fetch. See [`docs/skill-sources/`](docs/skill-sources/README.md) for the trusted-skill-source mechanism.
 
 ## 14. Skills are the unit of authorship
 

README.md

@@ -10,6 +10,7 @@
     - [Subsequent contributors](#subsequent-contributors)
     - [Drift detection](#drift-detection)
   - [Skill families](#skill-families)
+    - [External skill sources](#external-skill-sources)
   - [Maintenance](#maintenance)
   - [Cross-references](#cross-references)
 
@@ -176,6 +177,19 @@ means and which modes are still proposed vs. shipping today.
 | [**repo-health**](docs/repo-health/README.md) | Triage | Read-only repository-health audits: obsolete runner labels, Actions workflow security, dependency vulnerabilities, license/NOTICE compliance, flaky-test patterns. | 5 skills, [`docs/repo-health/`](docs/repo-health/) |
 | **utilities** | (meta) | Framework meta-skills: author or update skills (`write-skill`), restructure existing skills (`optimize-skill`), print a live index of all available skills (`list-skills`). | 3 skills |
 
+### External skill sources
+
+Beyond the in-tree families, an adopter can pull a skill or whole family
+from a **trusted external source** — a repo other than `apache/magpie` that
+ships Magpie-shaped skills (with their evals and tests). Where a skill
+directory would sit, a `skills/<name>/source.md` **redirect** names a
+pinned, verified source the adopter has vouched for; `/magpie-setup` fetches
+it into the gitignored snapshot and wires it in exactly like a framework
+skill. Nothing is fetched unless the adopter commits the pin — see
+[`docs/skill-sources/`](docs/skill-sources/README.md),
+[`PRINCIPLES.md` §13](PRINCIPLES.md#13-snapshot-plus-override-never-vendored-copies),
+and [`RFC-AI-0006`](docs/rfcs/RFC-AI-0006.md).
+
 ## Maintenance
 
 After the initial adoption, the same skill handles ongoing

docs/adapters/registry.md

@@ -28,6 +28,12 @@ the ones that ship in-tree, the open extension points, and links to
 > your `<project-config>/project.md` (or `organizations/<org>/`) at it,
 > exactly as you would a built-in one. An external link is a pointer for
 > humans to evaluate, not a supply-chain hook.
+>
+> This applies to the *adapter/organization* index on this page. Skills
+> are different: §13 permits **installing** a skill or skill-family from a
+> **trusted** external source — pinned, verified, and adopter-vouched.
+> That mechanism and its own discovery index live under
+> [`docs/skill-sources/`](../skill-sources/README.md).
 
 To author a new adapter, see [`authoring.md`](authoring.md).
 

docs/extending.md

@@ -34,6 +34,7 @@ indexes and catalogs exist for discovery, not installation.
 | Entity | What it is | Reference |
 |---|---|---|
 | **Skill** | a workflow the agent follows | [`PRINCIPLES.md` §14](../PRINCIPLES.md#14-skills-are-the-unit-of-authorship), [`write-skill`](../skills/write-skill/SKILL.md) |
+| **Skill source** | a trusted external repo a skill/family is *pulled* from | [`docs/skill-sources/`](skill-sources/README.md), [`RFC-AI-0006`](rfcs/RFC-AI-0006.md) |
 | **Tool / tool adapter** | the only layer that knows a vendor — a backend behind a capability contract | [vendor-neutrality § Tool adapters](vendor-neutrality.md#tool-adapters), [`adapters/authoring.md`](adapters/authoring.md) |
 | **Capability contract** | the stable verb set a skill depends on; the seam adapters plug into | [`tools/cve-tool/`](../tools/cve-tool/) and siblings |
 | **Organization** | governance vocabulary + backend bundle + identity, shared by an org's projects | [`organizations/README.md`](../organizations/README.md) |
@@ -65,6 +66,13 @@ discovery.
 - **Skills** — framework skills come from the snapshot; project tweaks
   live in `.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](../PRINCIPLES.md#13-snapshot-plus-override-never-vendored-copies)
+  and [`docs/skill-sources/`](skill-sources/README.md)).
 - **Tools / adapters** — selected per capability in
   `<project-config>/project.md` *Tools enabled*. The selected adapter may
   be an in-tree `tools/<name>/`, a directory you keep in your adopter

docs/index.md

@@ -121,6 +121,7 @@ from mailing lists, slack etc.
 | Understand the full vision | [MISSION.md](../MISSION.md) |
 | Understand how it stays vendor-neutral | [vendor-neutrality.md](vendor-neutrality.md) |
 | Find or author a backend adapter | [adapters/registry.md](adapters/registry.md) |
+| Pull a skill/family from a trusted external source | [skill-sources/README.md](skill-sources/README.md) |
 | Extend Magpie (project / org / individual) | [extending.md](extending.md) |
 | See what skills exist today | [modes.md](modes.md) |
 | Adopt in my project | [README → Adopting](../README.md#adopting-the-framework) |