@skill-graph/cli 0.5.6 → 0.5.8

package/docs/_drafts/0.5.8-release-prep.md

@@ -0,0 +1,164 @@
+# 0.5.8 Release Prep — Review Before Commit/Publish
+
+> **Status:** DRAFT — not yet applied to `package.json` or `CHANGELOG.md`.
+> **Prepared:** 2026-05-19 by Karpathy-loop Phase 2 Item 34.
+> **Action required:** review the proposed CHANGELOG entry and version bump, then either apply directly via the commands at the bottom or hand-edit.
+
+## Proposed version bump
+
+`package.json`:
+
+```diff
+-  "version": "0.5.7",
++  "version": "0.5.8",
+```
+
+## Proposed CHANGELOG entry
+
+Insert as a new section between the existing `## [Unreleased]` header and the next `## [0.5.0]` section (the existing `[Unreleased]` block, currently containing pre-Phase-2 entries, should be **promoted** to the body of `## [0.5.8]`; a fresh empty `## [Unreleased]` header replaces it):
+
+```markdown
+## [Unreleased]
+
+## [0.5.8] — 2026-05-19
+
+The "Karpathy-loop Phase 2" release. Ships the deterministic-drift sentinels,
+the mirror-freeze linter, the generated status doc, the `doctor` subcommand,
+the first hermetic test fixture, and the positioning + onboarding rework that
+Phase 2 specified. All Phase 1 audit gates remained green throughout; the
+release also includes the 33 Phase 1 truth-repair commits.
+
+### Added
+
+- **`scripts/check-doc-drift.js`** — schema_version drift sentinel that
+  scans active docs for stale `schema_version: N` references and refuses
+  to teach an old contract as current. Reads the active version from
+  `schemas/skill.schema.json`; allowlists `_archived/`, `docs/migrations/`,
+  `examples/`, `CHANGELOG.md`, and `vN → vM` migration sections. Flags:
+  `--json`, `--quiet`, `--include-warn`.
+- **`scripts/check-mirror-freeze.js`** — fails on active-source / active-
+  package claims in the two docs-only deprecation mirrors
+  (`skill-metadata-protocol`, `skill-audit-loop`). Detects `@skill-graph/
+  protocol`, `@skill-graph/audit`, `src/`, `lib/schemas/`, `schemas/skill.v*.
+  schema.json`, and `evals/` references that contradict the post-ADR-0009
+  docs-only status. File-level banner detection skips files explicitly
+  stamped as historical / frozen / deprecation-mirror snapshots.
+- **`scripts/build-status-doc.js` + `docs/status.generated.md`** — single-
+  source-of-truth status snapshot that pulls live values from `package.json`,
+  the schema, the manifest, and the four deterministic check scripts.
+  Replaces hand-maintained "Latest release" lines and ad-hoc skill-count
+  claims. Flags: `--check`, `--stdout`, `--no-checks`.
+- **`skill-graph doctor`** — new CLI subcommand grouping all six deterministic
+  checks (links, protocol, drift, mirror-freeze, lint, manifest) into one
+  pass with a single summary table. Recommended first command for bug
+  reports. Flags: `--json`, `--bail`, `--skip <name>`.
+- **`examples/fixture-skills/`** — hermetic test fixtures for `@skill-graph/cli`
+  package tests. Ships `minimal-capability` (bare-minimum v6 frontmatter,
+  passes lint with zero errors). Three more planned (`with-grounding`,
+  `with-relations`, `comprehension-full`) are sketched in the directory
+  README; each will land as a separate commit when the sub-field shapes
+  are aligned with the lint's expectations.
+- **`docs/positioning.md`** — explicit positioning of Skill Graph in the
+  agent-skills ecosystem. Names what Skill Graph is **not** (a runtime,
+  a marketplace, a tool platform) before naming what it **is** (an
+  authoring + audit-time contract with a Karpathy keep-or-revert loop).
+  Compares against Anthropic Skills, the Agent Skills spec, MCP, A2A,
+  Smithery, Composio, and AGENTS.md. Includes the "60-second pitch",
+  the "what this is not" matrix, the "when to reach for Skill Graph"
+  gate, and the layered ecosystem map.
+- **README hero rework** — three new sections above the ecosystem
+  diagram: "Is this for me?" (yes-if / no-if qualifying signals for a
+  30-second visitor), "What makes this different" (Karpathy keep-or-revert
+  loop applied to skill libraries, with explicit citation), and a
+  surfacing of `docs/quality-doctrine.md` as the codified quality bar.
+- **README two-onboarding-paths framing** — explicit routing of authors
+  to `docs/QUICKSTART-30MIN.md` for hands-on first-skill authoring and
+  to `docs/PRIMER.md` for the conceptual model first. Synthesis Item 48
+  resolved as "link, do not merge" because they serve different reader
+  genres.
+
+### Changed
+
+- **`scripts/check-markdown-links.js`** — broken links in `_archived/`
+  paths now emit warnings instead of failing the build. Active docs
+  remain strict. New `--strict-archived` flag elevates archived warnings
+  to errors (useful when migrating an archive batch). Synthesis Item 49.
+- **README "External Context"** — replaced 5-bullet list of tangential
+  references with a "Where Skill Graph fits" section that links directly
+  to `docs/positioning.md` and surfaces the unique angle in one line.
+- **`bin/skill-graph.js`** — `evolve` subcommand labeled `[PREVIEW ·
+  monorepo-only]` in both the README quickstart and the CLI `--help`.
+  Aligns the discoverability surface with the dispatcher's existing
+  not-standalone-compatible error message.
+
+### Documented
+
+- **`docs/_archived/marketplace-publication-priority-2026-05-18.md`** —
+  the archived plan's broken `./adr/...` link was fixed to `../adr/...`
+  (Phase 1 Item 1).
+- **Mirror governance** — five mirror docs banner-stamped as frozen
+  deprecation snapshots: `skill-metadata-protocol/docs/{concept-map,
+  field-reference, field-reference.generated, skill-metadata-protocol}.md`
+  and `skill-metadata-protocol/CONTRIBUTING.md` + `skill-audit-loop/{
+  CONTRIBUTING, SKILL_AUDIT_LOOP, SKILL_AUDIT_CHECKLIST}.md` (Phase 1
+  Items 30, 25 + Phase 2 Item 36 follow-ups).
+- **`docs/plans/skill-graph-oss-docs-refresh.md`** (lives in the
+  Development workspace, not this repo) — banner-stamped as superseded
+  by ADR 0009 (Phase 2 Item 41).
+
+### Carried forward from earlier [Unreleased]
+
+[Move the existing pre-Phase-2 [Unreleased] entries here — i.e. the
+publication-classification ledger, the publish.yml workflow, the
+stability promotion lint check, the marketplace publication priority
+doc removal, the cross-repo version reconciliation, the schema_version 4/5/6
+changes, and the skill audit loop reframing.]
+```
+
+## Apply the diff (when ready)
+
+```bash
+cd /Users/jacobbalslev/Development/skill-graph
+
+# 1. Bump version
+sed -i '' 's/"version": "0.5.7"/"version": "0.5.8"/' package.json
+
+# 2. Hand-edit CHANGELOG.md per the proposed entry above. The mechanical
+#    steps are:
+#      - Move existing [Unreleased] body to "## [0.5.8] — 2026-05-19" with
+#        a "Carried forward from earlier [Unreleased]" sub-section.
+#      - Add the new Phase 2 entries from this draft.
+#      - Insert a fresh empty "## [Unreleased]" header above [0.5.8].
+
+# 3. Regenerate status doc so it reflects the new version
+node scripts/build-status-doc.js
+
+# 4. Verify everything's clean
+node bin/skill-graph.js doctor
+
+# 5. Commit with --only
+git commit --only -m "chore(release): cut 0.5.8 — Karpathy-loop Phase 2
+
+Promotes [Unreleased] to [0.5.8] and adds Phase 2 entries:
+drift sentinel, mirror-freeze linter, status doc, doctor subcommand,
+fixture-skills, positioning doc, README hero rework, evolve PREVIEW
+labeling, and the _archived/ link-check policy.
+
+Karpathy-loop Phase 2 item 34/55." -- package.json CHANGELOG.md docs/status.generated.md
+
+# 6. Tag + publish (only after committing and pushing)
+git tag v0.5.8
+git push origin main --tags
+# CI workflow .github/workflows/publish.yml publishes on tag push.
+```
+
+## Open questions for the user
+
+1. Should I keep all pre-Phase-2 [Unreleased] entries inside [0.5.8] (the
+   "kitchen-sink" choice), or split them into a separate intermediate version
+   (e.g. 0.5.6 / 0.5.7 / 0.5.8) to chronicle when they actually shipped?
+   The package.json version has already bumped 0.5.0 → 0.5.7 without
+   corresponding CHANGELOG entries, so there's accumulated drift.
+2. Confirm the release tag will trigger `.github/workflows/publish.yml`.
+   First-publish prereqs (npm org + `NPM_TOKEN` secret) are tracked in the
+   existing `## [Unreleased]` SH-6111 entry.

package/docs/adr/0009-sibling-repo-deprecation.md

@@ -0,0 +1,48 @@
+# ADR 0009 — Sibling Repo Deprecation (Consolidation Addendum)
+
+> Status: Accepted
+> Date: 2026-05-18
+> Linear: SH-6132 / SH-6137
+
+## Context
+
+Per the SH-6132 monolith decision, schemas and source code from two sibling repos were consolidated into `@skill-graph/cli`:
+
+- `skill-metadata-protocol` (`@skill-graph/protocol@1.3.0`) — JSON schemas, migration docs, examples, ADRs
+- `skill-audit-loop` (`@skill-graph/audit@0.2.0`) — audit scripts, graders, shared utilities, eval fixtures
+
+The consolidation shipped in `@skill-graph/cli@0.5.6` (commit `654b4df`, published 2026-05-18).
+
+## Decision
+
+Both sibling repos become **docs-only mirrors** as of 2026-05-18:
+
+- Source files (schemas/, src/, shared/, graders/, examples/, package.json) are removed from both repos.
+- Canonical documents (SKILL_METADATA_PROTOCOL.md, SKILL_AUDIT_LOOP.md, SKILL_AUDIT_CHECKLIST.md, READMEs) are preserved for historical reference and inbound-link stability.
+- Repos are NOT archived on GitHub (Option B) — they remain publicly readable.
+- Deprecation banners are added to both READMEs pointing to `@skill-graph/cli`.
+
+## Version source of truth (post-consolidation)
+
+The version source of truth for `schema_version` is now `@skill-graph/cli` — specifically the schemas bundled under `lib/schemas/` in the published package. ADR 0007 in `skill-metadata-protocol/docs/adr/0007-version-source-of-truth.md` documents the dual-versioning model; this ADR records the physical move.
+
+New consumers should install `@skill-graph/cli` and reference:
+- `https://github.com/jacob-balslev/skill-graph/blob/main/docs/SKILL_METADATA_PROTOCOL.md`
+- `https://github.com/jacob-balslev/skill-graph/blob/main/docs/SKILL_AUDIT_LOOP.md`
+- `https://www.npmjs.com/package/@skill-graph/cli`
+
+## Consequences
+
+- `skill-metadata-protocol` and `skill-audit-loop` repos stay alive as read-only mirrors with deprecation banners.
+- All new schema evolution and audit tooling development happens in `skill-graph`.
+- External links to the sibling repos' README and canonical docs files remain valid.
+- Links to source files (schemas/, src/) in the sibling repos become 404s — consumers must migrate to `@skill-graph/cli`.
+
+## Related
+
+- SH-6132 — Monolith consolidation decision
+- SH-6133 — Source consolidation into skill-graph
+- SH-6134 — Unified CLI dispatcher
+- SH-6136 — v0.5.6 publish
+- ADR 0007 in `skill-metadata-protocol/docs/adr/` — version source of truth (with 2026-05-18 addendum)
+- ADR 0008 — Skill surface split and curation policy

package/docs/diagrams/skill-graph-ecosystem.mmd

@@ -0,0 +1,17 @@
+%%{init: {'theme':'neutral','flowchart':{'curve':'basis','padding':20}}}%%
+graph TD
+  G["<b>skill-graph</b><br/><i>canonical monolith: spec, schemas, tooling, audit</i><br/>@skill-graph/cli — npm install -g"]
+  L["<b>skills</b><br/><i>public open-source skill library</i><br/>npx skills add jacob-balslev/skills"]
+  P["<b>skill-metadata-protocol</b><br/><i>deprecated · docs-only mirror</i><br/>SKILL_METADATA_PROTOCOL.md preserved"]
+  A["<b>skill-audit-loop</b><br/><i>deprecated · docs-only mirror</i><br/>SKILL_AUDIT_LOOP.md preserved"]
+
+  G -->|exports SKILL.md| L
+  G -. mirrors protocol spec to .-> P
+  G -. mirrors audit procedure to .-> A
+
+  classDef active fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d;
+  classDef tool fill:#fef3c7,stroke:#d97706,stroke-width:2px,color:#78350f;
+  classDef mirror fill:#f3f4f6,stroke:#9ca3af,stroke-width:1px,color:#4b5563,stroke-dasharray:4 3;
+  class G tool;
+  class L active;
+  class P,A mirror;

package/docs/field-reference.generated.md

@@ -1,11 +1,11 @@
 # Skill Graph Field Reference (Generated)
 
-> **Generated from** `schemas/skill.schema.json` on 2026-05-18 by `scripts/build-field-reference.js`.
+> **Generated from** `schemas/skill.schema.json` on 2026-05-19 by `scripts/build-field-reference.js`.
 > **Do not edit by hand.** The canonical prose reference is [`docs/field-reference.md`](field-reference.md).
 > **Predicate glossary:** [`docs/glossary.md`](glossary.md).
 > **JSON-LD @context:** [`schemas/skill.context.jsonld`](../schemas/skill.context.jsonld).
 
-Schema version: **6** · Field count: **52** · Required: **13**
+Schema version: **6** · Field count: **54** · Required: **13**
 
 ---
 
@@ -107,6 +107,16 @@ Hierarchical domain path using slash-delimited segments (e.g., `ecommerce/integr
 
 ---
 
+### `secondary_categories` *(optional)*
+
+**Type:** array of string
+
+Additive tags for cross-listing in marketplace collections. Primary `category` is MECE and decides folder placement; `secondary_categories` lets a skill that genuinely serves two audiences (e.g., `playwright-cli` is primarily `quality` but also relevant to `engineering`) appear in additional marketplace collections without affecting filesystem layout. Max 2 entries to prevent dilution. Drawn from the same closed 6-enum as `category`; MUST NOT include the primary `category` value.
+
+**Full reference:** [`docs/field-reference.md#secondary_categories`](field-reference.md#secondary_categories)
+
+---
+
 ### `scope` *(required)*
 
 **Type:** `codebase` | `reference` | `portable`
@@ -397,6 +407,16 @@ Lifecycle posture for consumers. `experimental` (subject to change), `stable` (p
 
 ---
 
+### `marketplace_tier` *(optional)*
+
+**Type:** `S` | `A` | `B` | `C`
+
+Publication priority for the public marketplace at `github.com/jacob-balslev/skills` / `skills.sh`. `S` = featured (top-of-README, individual hero copy). `A` = high-demand (named in collection tables). `B` = standard utility (included in collection tables). `C` = niche (collapsed 'More' section). Omit entirely for skills that should not be published. Sourced from `marketplace-publication-priority-*.md` and authored per skill. Lint validates the enum; consumers (export-marketplace-skills.js, generate-marketplace-readmes.js) filter and group on this field.
+
+**Full reference:** [`docs/field-reference.md#marketplace_tier`](field-reference.md#marketplace_tier)
+
+---
+
 ### `superseded_by` *(optional)*
 
 **Type:** string

package/docs/field-reference.md

@@ -13,7 +13,7 @@ The field reference is split across three coordinated documents. Use whichever f
 | Doc | Genre | When to read |
 |---|---|---|
 | [`field-reference.md`](field-reference.md) (this doc) | **Hand-curated prose reference.** Field-by-field, with worked examples, lint notes, and cross-cutting guidance. | When authoring or reviewing a SKILL.md and you want examples and "when to use" rules alongside the schema-canonical definition. |
-| [`field-reference.generated.md`](field-reference.generated.md) | **Auto-generated index.** Built from `schemas/skill.v4.schema.json` description strings by `scripts/build-field-reference.js`. Drift-free against the schema. | When you want the machine-guaranteed list of every field, every type, every pattern, every enum value. The fastest way to verify what the schema actually accepts today. |
+| [`field-reference.generated.md`](field-reference.generated.md) | **Auto-generated index.** Built from `schemas/skill.v6.schema.json` description strings by `scripts/build-field-reference.js`. Drift-free against the schema. | When you want the machine-guaranteed list of every field, every type, every pattern, every enum value. The fastest way to verify what the schema actually accepts today. |
 | [`field-rationale.md`](field-rationale.md) | **Hand-authored "why this field" rationale.** Covers the ~10 fields whose meaning is non-obvious from the schema description (`scope`, `eval_artifacts`, `eval_state`, `routing_eval`, `relations.depends_on`, `relations.verify_with`, `relations.broader`, `grounding.evidence_priority`, `lifecycle.review_cadence`, `portability.readiness`). | When you understand *what* a field stores but want to know *why the field exists at all* and *what the common confusion looks like*. |
 
 The schema is the single source of truth for shape; this doc is the source of truth for prose; `field-rationale.md` is the source of truth for design intent. Lint check C7 (in `scripts/check-protocol-consistency.js`) verifies the generated index stays in sync with the schema description strings — running `node scripts/build-field-reference.js --check` against the live schema must succeed before commit.
@@ -34,7 +34,7 @@ The schema is the single source of truth for shape; this doc is the source of tr
 
 **Example.**
 ```yaml
-schema_version: 4
+schema_version: 6
 ```
 
 **When to use.** Always — this is a required field.
@@ -227,6 +227,30 @@ category: integrations
 
 ---
 
+## `secondary_categories`
+
+**Purpose.** Additive cross-listing tags for marketplace collections. Primary `category` is MECE and decides folder placement; `secondary_categories` lets a skill that genuinely serves two audiences (e.g., `playwright-cli` is primarily `quality` but also relevant to `engineering`) appear in additional marketplace collections without affecting filesystem layout.
+
+**Rules.**
+
+- Optional. Omit if the primary `category` is sufficient.
+- Drawn from the same closed 6-enum as `category` (`foundations` | `engineering` | `design` | `quality` | `agent` | `product`).
+- Max 2 entries to prevent dilution.
+- MUST NOT include the primary `category` value.
+
+**Example.**
+
+```yaml
+category: quality
+secondary_categories: [engineering]
+```
+
+**When to use.** When a skill is genuinely useful in more than one browse bucket and you want it to surface in additional marketplace collections.
+
+**When NOT to use.** Do not stuff this field as a dumping ground for tags. Use `workspace_tags` or `routing_bundles` for non-marketplace classification.
+
+---
+
 ## `domain`
 
 **Purpose.** Hierarchical domain path as slash-delimited segments. Complements `category`: flat bucket and tree path answer different questions. A UI or docs site uses `domain` to render a folder tree; a filter UI uses `category` for quick grouping.
@@ -829,6 +853,33 @@ stability: stable
 
 ---
 
+## `marketplace_tier`
+
+**Purpose.** Publication priority for the public marketplace at `github.com/jacob-balslev/skills` / `skills.sh`. Drives which collection table or hero block a skill appears in. Omit entirely for skills that should not be published.
+
+**Rules.**
+
+- Optional. Omit on skills that are not publication candidates (the export pipeline filters those out).
+- Closed enum: `S` | `A` | `B` | `C`.
+- `S` — featured (top-of-README, individual hero copy).
+- `A` — high-demand (named in collection tables).
+- `B` — standard utility (included in collection tables).
+- `C` — niche (collapsed "More" section).
+
+**Example.**
+
+```yaml
+marketplace_tier: A
+```
+
+**When to use.** When you intend a skill to appear in the public marketplace and want explicit control over its placement. Sourced from `marketplace-publication-priority-*.md` and authored per skill.
+
+**When NOT to use.** For repo-internal skills, sales-hub-private skills, or skills with PII bindings. Omit and they will not be published.
+
+**Consumers.** `scripts/export-marketplace-skills.js` and `scripts/generate-marketplace-readmes.js` filter and group on this field.
+
+---
+
 ## `superseded_by`
 
 **Purpose.** Names the skill that replaces this one when `stability: deprecated`. Consumers and routers use this to follow a deprecation chain automatically instead of reading the body prose.

package/docs/images/skill-graph-ecosystem.svg

@@ -0,0 +1 @@
+<svg id="my-svg" width="100%" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" class="flowchart" style="max-width: 991.859px; background-color: transparent;" viewBox="0 0 991.859375 410" role="graphics-document document" aria-roledescription="flowchart-v2"><style>#my-svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#000000;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#my-svg .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#my-svg .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#my-svg .error-icon{fill:#552222;}#my-svg .error-text{fill:#552222;stroke:#552222;}#my-svg .edge-thickness-normal{stroke-width:1px;}#my-svg .edge-thickness-thick{stroke-width:3.5px;}#my-svg .edge-pattern-solid{stroke-dasharray:0;}#my-svg .edge-thickness-invisible{stroke-width:0;fill:none;}#my-svg .edge-pattern-dashed{stroke-dasharray:3;}#my-svg .edge-pattern-dotted{stroke-dasharray:2;}#my-svg .marker{fill:#666;stroke:#666;}#my-svg .marker.cross{stroke:#666;}#my-svg svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#my-svg p{margin:0;}#my-svg .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#000000;}#my-svg .cluster-label text{fill:#333;}#my-svg .cluster-label span{color:#333;}#my-svg .cluster-label span p{background-color:transparent;}#my-svg .label text,#my-svg span{fill:#000000;color:#000000;}#my-svg .node rect,#my-svg .node circle,#my-svg .node ellipse,#my-svg .node polygon,#my-svg .node path{fill:#eee;stroke:#999;stroke-width:1px;}#my-svg .rough-node .label text,#my-svg .node .label text,#my-svg .image-shape .label,#my-svg .icon-shape .label{text-anchor:middle;}#my-svg .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#my-svg .rough-node .label,#my-svg .node .label,#my-svg .image-shape .label,#my-svg .icon-shape .label{text-align:center;}#my-svg .node.clickable{cursor:pointer;}#my-svg .root .anchor path{fill:#666!important;stroke-width:0;stroke:#666;}#my-svg .arrowheadPath{fill:#333333;}#my-svg .edgePath .path{stroke:#666;stroke-width:1px;}#my-svg .flowchart-link{stroke:#666;fill:none;}#my-svg .edgeLabel{background-color:white;text-align:center;}#my-svg .edgeLabel p{background-color:white;}#my-svg .edgeLabel rect{opacity:0.5;background-color:white;fill:white;}#my-svg .labelBkg{background-color:rgba(255, 255, 255, 0.5);}#my-svg .cluster rect{fill:hsl(0, 0%, 98.9215686275%);stroke:#707070;stroke-width:1px;}#my-svg .cluster text{fill:#333;}#my-svg .cluster span{color:#333;}#my-svg div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(-160, 0%, 93.3333333333%);border:1px solid #707070;border-radius:2px;pointer-events:none;z-index:100;}#my-svg .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#000000;}#my-svg rect.text{fill:none;stroke-width:0;}#my-svg .icon-shape,#my-svg .image-shape{background-color:white;text-align:center;}#my-svg .icon-shape p,#my-svg .image-shape p{background-color:white;padding:2px;}#my-svg .icon-shape .label rect,#my-svg .image-shape .label rect{opacity:0.5;background-color:white;fill:white;}#my-svg .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#my-svg .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#my-svg .node .neo-node{stroke:#999;}#my-svg [data-look="neo"].node rect,#my-svg [data-look="neo"].cluster rect,#my-svg [data-look="neo"].node polygon{stroke:url(#my-svg-gradient);filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}#my-svg [data-look="neo"].node path{stroke:url(#my-svg-gradient);stroke-width:1px;}#my-svg [data-look="neo"].node .outer-path{filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}#my-svg [data-look="neo"].node .neo-line path{stroke:#999;filter:none;}#my-svg [data-look="neo"].node circle{stroke:url(#my-svg-gradient);filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}#my-svg [data-look="neo"].node circle .state-start{fill:#000000;}#my-svg [data-look="neo"].icon-shape .icon{fill:url(#my-svg-gradient);filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}#my-svg [data-look="neo"].icon-shape .icon-neo path{stroke:url(#my-svg-gradient);filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}#my-svg :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;}#my-svg .active&gt;*{fill:rgb(220, 252, 231)!important;stroke:rgb(22, 163, 74)!important;stroke-width:2px!important;color:rgb(20, 83, 45)!important;}#my-svg .active span{fill:rgb(220, 252, 231)!important;stroke:rgb(22, 163, 74)!important;stroke-width:2px!important;color:rgb(20, 83, 45)!important;}#my-svg .active tspan{fill:rgb(20, 83, 45)!important;}#my-svg .tool&gt;*{fill:rgb(254, 243, 199)!important;stroke:rgb(217, 119, 6)!important;stroke-width:2px!important;color:rgb(120, 53, 15)!important;}#my-svg .tool span{fill:rgb(254, 243, 199)!important;stroke:rgb(217, 119, 6)!important;stroke-width:2px!important;color:rgb(120, 53, 15)!important;}#my-svg .tool tspan{fill:rgb(120, 53, 15)!important;}#my-svg .mirror&gt;*{fill:rgb(243, 244, 246)!important;stroke:rgb(156, 163, 175)!important;stroke-width:1px!important;color:rgb(75, 85, 99)!important;stroke-dasharray:4,3!important;}#my-svg .mirror span{fill:rgb(243, 244, 246)!important;stroke:rgb(156, 163, 175)!important;stroke-width:1px!important;color:rgb(75, 85, 99)!important;stroke-dasharray:4,3!important;}#my-svg .mirror tspan{fill:rgb(75, 85, 99)!important;}</style><g><marker id="my-svg_flowchart-v2-pointEnd" class="marker flowchart-v2" viewBox="0 0 10 10" refX="5" refY="5" markerUnits="userSpaceOnUse" markerWidth="8" markerHeight="8" orient="auto"><path d="M 0 0 L 10 5 L 0 10 z" class="arrowMarkerPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"/></marker><marker id="my-svg_flowchart-v2-pointStart" class="marker flowchart-v2" viewBox="0 0 10 10" refX="4.5" refY="5" markerUnits="userSpaceOnUse" markerWidth="8" markerHeight="8" orient="auto"><path d="M 0 5 L 10 10 L 10 0 z" class="arrowMarkerPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"/></marker><marker id="my-svg_flowchart-v2-pointEnd-margin" class="marker flowchart-v2" viewBox="0 0 11.5 14" refX="11.5" refY="7" markerUnits="userSpaceOnUse" markerWidth="10.5" markerHeight="14" orient="auto"><path d="M 0 0 L 11.5 7 L 0 14 z" class="arrowMarkerPath" style="stroke-width: 0; stroke-dasharray: 1, 0;"/></marker><marker id="my-svg_flowchart-v2-pointStart-margin" class="marker flowchart-v2" viewBox="0 0 11.5 14" refX="1" refY="7" markerUnits="userSpaceOnUse" markerWidth="11.5" markerHeight="14" orient="auto"><polygon points="0,7 11.5,14 11.5,0" class="arrowMarkerPath" style="stroke-width: 0; stroke-dasharray: 1, 0;"/></marker><marker id="my-svg_flowchart-v2-circleEnd" class="marker flowchart-v2" viewBox="0 0 10 10" refX="11" refY="5" markerUnits="userSpaceOnUse" markerWidth="11" markerHeight="11" orient="auto"><circle cx="5" cy="5" r="5" class="arrowMarkerPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"/></marker><marker id="my-svg_flowchart-v2-circleStart" class="marker flowchart-v2" viewBox="0 0 10 10" refX="-1" refY="5" markerUnits="userSpaceOnUse" markerWidth="11" markerHeight="11" orient="auto"><circle cx="5" cy="5" r="5" class="arrowMarkerPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"/></marker><marker id="my-svg_flowchart-v2-circleEnd-margin" class="marker flowchart-v2" viewBox="0 0 10 10" refY="5" refX="12.25" markerUnits="userSpaceOnUse" markerWidth="14" markerHeight="14" orient="auto"><circle cx="5" cy="5" r="5" class="arrowMarkerPath" style="stroke-width: 0; stroke-dasharray: 1, 0;"/></marker><marker id="my-svg_flowchart-v2-circleStart-margin" class="marker flowchart-v2" viewBox="0 0 10 10" refX="-2" refY="5" markerUnits="userSpaceOnUse" markerWidth="14" markerHeight="14" orient="auto"><circle cx="5" cy="5" r="5" class="arrowMarkerPath" style="stroke-width: 0; stroke-dasharray: 1, 0;"/></marker><marker id="my-svg_flowchart-v2-crossEnd" class="marker cross flowchart-v2" viewBox="0 0 11 11" refX="12" refY="5.2" markerUnits="userSpaceOnUse" markerWidth="11" markerHeight="11" orient="auto"><path d="M 1,1 l 9,9 M 10,1 l -9,9" class="arrowMarkerPath" style="stroke-width: 2; stroke-dasharray: 1, 0;"/></marker><marker id="my-svg_flowchart-v2-crossStart" class="marker cross flowchart-v2" viewBox="0 0 11 11" refX="-1" refY="5.2" markerUnits="userSpaceOnUse" markerWidth="11" markerHeight="11" orient="auto"><path d="M 1,1 l 9,9 M 10,1 l -9,9" class="arrowMarkerPath" style="stroke-width: 2; stroke-dasharray: 1, 0;"/></marker><marker id="my-svg_flowchart-v2-crossEnd-margin" class="marker cross flowchart-v2" viewBox="0 0 15 15" refX="17.7" refY="7.5" markerUnits="userSpaceOnUse" markerWidth="12" markerHeight="12" orient="auto"><path d="M 1,1 L 14,14 M 1,14 L 14,1" class="arrowMarkerPath" style="stroke-width: 2.5;"/></marker><marker id="my-svg_flowchart-v2-crossStart-margin" class="marker cross flowchart-v2" viewBox="0 0 15 15" refX="-3.5" refY="7.5" markerUnits="userSpaceOnUse" markerWidth="12" markerHeight="12" orient="auto"><path d="M 1,1 L 14,14 M 1,14 L 14,1" class="arrowMarkerPath" style="stroke-width: 2.5; stroke-dasharray: 1, 0;"/></marker><g class="root"><g class="clusters"/><g class="edgePaths"><path d="M355.93,135.078L321.275,146.732C286.62,158.386,217.31,181.693,182.655,198.846C148,216,148,227,148,232.5L148,238" id="my-svg-L_G_L_0" class="edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link" style=";" data-edge="true" data-et="edge" data-id="L_G_L_0" data-points="W3sieCI6MzU1LjkyOTY4NzUsInkiOjEzNS4wNzg0Nzc2MDE4ODYxNn0seyJ4IjoxNDgsInkiOjIwNX0seyJ4IjoxNDgsInkiOjI0Mn1d" data-look="classic" marker-end="url(#my-svg_flowchart-v2-pointEnd)"/><path d="M495.93,168L495.93,174.167C495.93,180.333,495.93,192.667,495.93,206.333C495.93,220,495.93,235,495.93,242.5L495.93,250" id="my-svg-L_G_P_0" class="edge-thickness-normal edge-pattern-dotted edge-thickness-normal edge-pattern-solid flowchart-link" style=";" data-edge="true" data-et="edge" data-id="L_G_P_0" data-points="W3sieCI6NDk1LjkyOTY4NzUsInkiOjE2OH0seyJ4Ijo0OTUuOTI5Njg3NSwieSI6MjA1fSx7IngiOjQ5NS45Mjk2ODc1LCJ5IjoyNTR9XQ==" data-look="classic" marker-end="url(#my-svg_flowchart-v2-pointEnd)"/><path d="M635.93,135.078L670.585,146.732C705.24,158.386,774.549,181.693,809.204,198.846C843.859,216,843.859,227,843.859,232.5L843.859,238" id="my-svg-L_G_A_0" class="edge-thickness-normal edge-pattern-dotted edge-thickness-normal edge-pattern-solid flowchart-link" style=";" data-edge="true" data-et="edge" data-id="L_G_A_0" data-points="W3sieCI6NjM1LjkyOTY4NzUsInkiOjEzNS4wNzg0Nzc2MDE4ODYxNn0seyJ4Ijo4NDMuODU5Mzc1LCJ5IjoyMDV9LHsieCI6ODQzLjg1OTM3NSwieSI6MjQyfV0=" data-look="classic" marker-end="url(#my-svg_flowchart-v2-pointEnd)"/></g><g class="edgeLabels"><g class="edgeLabel" transform="translate(148, 205)"><g class="label" data-id="L_G_L_0" transform="translate(-61.8671875, -12)"><foreignObject width="123.734375" height="24"><div xmlns="http://www.w3.org/1999/xhtml" class="labelBkg" style="display: table-cell; white-space: nowrap; line-height: 1.5; max-width: 200px; text-align: center;"><span class="edgeLabel"><p>exports SKILL.md</p></span></div></foreignObject></g></g><g class="edgeLabel" transform="translate(495.9296875, 205)"><g class="label" data-id="L_G_P_0" transform="translate(-86.4375, -12)"><foreignObject width="172.875" height="24"><div xmlns="http://www.w3.org/1999/xhtml" class="labelBkg" style="display: table-cell; white-space: nowrap; line-height: 1.5; max-width: 200px; text-align: center;"><span class="edgeLabel"><p>mirrors protocol spec to</p></span></div></foreignObject></g></g><g class="edgeLabel" transform="translate(843.859375, 205)"><g class="label" data-id="L_G_A_0" transform="translate(-95.4453125, -12)"><foreignObject width="190.890625" height="24"><div xmlns="http://www.w3.org/1999/xhtml" class="labelBkg" style="display: table-cell; white-space: nowrap; line-height: 1.5; max-width: 200px; text-align: center;"><span class="edgeLabel"><p>mirrors audit procedure to</p></span></div></foreignObject></g></g></g><g class="nodes"><g class="node default tool" id="my-svg-flowchart-G-0" data-look="classic" transform="translate(495.9296875, 88)"><rect class="basic label-container" style="fill:#fef3c7 !important;stroke:#d97706 !important;stroke-width:2px !important" x="-140" y="-80" width="280" height="160"/><g class="label" style="color:#78350f !important" transform="translate(-100, -60)"><rect/><foreignObject width="200" height="120"><div style="color: rgb(120, 53, 15) !important; display: table; white-space: break-spaces; line-height: 1.5; max-width: 200px; text-align: center; width: 200px;" xmlns="http://www.w3.org/1999/xhtml"><span style="color:#78350f !important" class="nodeLabel"><p><b>skill-graph</b><br /><i>canonical monolith: spec, schemas, tooling, audit</i><br />@skill-graph/cli — npm install -g</p></span></div></foreignObject></g></g><g class="node default active" id="my-svg-flowchart-L-1" data-look="classic" transform="translate(148, 322)"><rect class="basic label-container" style="fill:#dcfce7 !important;stroke:#16a34a !important;stroke-width:2px !important" x="-140" y="-80" width="280" height="160"/><g class="label" style="color:#14532d !important" transform="translate(-100, -60)"><rect/><foreignObject width="200" height="120"><div style="color: rgb(20, 83, 45) !important; display: table; white-space: break-spaces; line-height: 1.5; max-width: 200px; text-align: center; width: 200px;" xmlns="http://www.w3.org/1999/xhtml"><span style="color:#14532d !important" class="nodeLabel"><p><b>skills</b><br /><i>public open-source skill library</i><br />npx skills add jacob-balslev/skills</p></span></div></foreignObject></g></g><g class="node default mirror" id="my-svg-flowchart-P-2" data-look="classic" transform="translate(495.9296875, 322)"><rect class="basic label-container" style="fill:#f3f4f6 !important;stroke:#9ca3af !important;stroke-width:1px !important;stroke-dasharray:4 3 !important" x="-157.9296875" y="-68" width="315.859375" height="136"/><g class="label" style="color:#4b5563 !important" transform="translate(-117.9296875, -48)"><rect/><foreignObject width="235.859375" height="96"><div style="color: rgb(75, 85, 99) !important; display: table; white-space: break-spaces; line-height: 1.5; max-width: 200px; text-align: center; width: 200px;" xmlns="http://www.w3.org/1999/xhtml"><span style="color:#4b5563 !important" class="nodeLabel"><p><b>skill-metadata-protocol</b><br /><i>deprecated · docs-only mirror</i><br />SKILL_METADATA_PROTOCOL.md preserved</p></span></div></foreignObject></g></g><g class="node default mirror" id="my-svg-flowchart-A-3" data-look="classic" transform="translate(843.859375, 322)"><rect class="basic label-container" style="fill:#f3f4f6 !important;stroke:#9ca3af !important;stroke-width:1px !important;stroke-dasharray:4 3 !important" x="-140" y="-80" width="280" height="160"/><g class="label" style="color:#4b5563 !important" transform="translate(-100, -60)"><rect/><foreignObject width="200" height="120"><div style="color: rgb(75, 85, 99) !important; display: table; white-space: break-spaces; line-height: 1.5; max-width: 200px; text-align: center; width: 200px;" xmlns="http://www.w3.org/1999/xhtml"><span style="color:#4b5563 !important" class="nodeLabel"><p><b>skill-audit-loop</b><br /><i>deprecated · docs-only mirror</i><br />SKILL_AUDIT_LOOP.md preserved</p></span></div></foreignObject></g></g></g></g></g><defs><filter id="my-svg-drop-shadow" height="130%" width="130%"><feDropShadow dx="4" dy="4" stdDeviation="0" flood-opacity="0.06" flood-color="#000000"/></filter></defs><defs><filter id="my-svg-drop-shadow-small" height="150%" width="150%"><feDropShadow dx="2" dy="2" stdDeviation="0" flood-opacity="0.06" flood-color="#000000"/></filter></defs><linearGradient id="my-svg-gradient" gradientUnits="objectBoundingBox" x1="0%" y1="0%" x2="100%" y2="0%"><stop offset="0%" stop-color="hsl(0, 0%, 83.3333333333%)" stop-opacity="1"/><stop offset="100%" stop-color="hsl(0, 0%, 88.9215686275%)" stop-opacity="1"/></linearGradient></svg>

package/docs/manifest-field-mapping.md

@@ -148,8 +148,8 @@ Three versions coexist in a manifest ecosystem:
 | Version | Lives in | Meaning |
 |---|---|---|
 | Authored skill `version` | Per-skill frontmatter `version` field | Version of the skill's content (e.g. `1.2.0` means the skill has been iterated twice since its initial publish). |
-| Authored schema version | Per-skill frontmatter `schema_version` field | Version of the `skill.schema.json` contract the skill was authored against. Currently `4` after the v4 naming cleanup. |
-| Manifest schema version | Manifest root `schema_version` field | Version of the `manifest.schema.json` contract the manifest was generated against. Currently `4`. |
+| Authored skill schema version | Per-skill frontmatter `schema_version` field | Version of the `skill.schema.json` contract the skill was authored against. The active value is `6` (skill schema, advanced through v5 to v6 marketplace fields). |
+| Manifest schema version | Manifest root `schema_version` field | Version of the `manifest.schema.json` contract the manifest was generated against. The active value is `4` — manifest contract shape has not changed since v4 even though skill schema has advanced. |
 
 ### When to bump `schema_version`
 
@@ -302,7 +302,7 @@ The `skill-metadata-template` starter (`examples/skill-metadata-template.md`) is
 
 ```yaml
 ---
-schema_version: 4
+schema_version: 6
 name: skill-metadata-template
 description: "Authoring template for new Skill Metadata Protocol skills. ..."
 version: 1.0.0

package/docs/marketplace-publication-queue.generated.md

@@ -1,6 +1,6 @@
 # Marketplace Publication Queue (generated)
 
-Generated: 2026-05-18T10:55:00.441Z
+Generated: 2026-05-18T13:56:43.757Z
 Schema: 2.0.0
 Generator: skill-audit-loop@0.3.0
 Source ledger: `skill-graph/data/publication-classification.json`
@@ -14,7 +14,7 @@ Source ledger: `skill-graph/data/publication-classification.json`
 - Publishable candidates: 136
 - Sales-Hub-bound (excluded): 53
 - Personal-infra (excluded): 27
-- Already published (in OSS export): 140
+- Already published (in OSS export): 142
 - Tier counts: S=18 A=29 B=42 C=47
 - Ledger entries total: 216
 

package/docs/plans/scripts-roadmap.md

@@ -77,14 +77,14 @@ Purpose:
 Shipping today. Two modes:
 
 1. **Stub mode** (default) — runs `scripts/skill-lint.js` and seeds `audits/<skill>/{findings,verdict,scorecard}.md` with lint-derived findings and human-TODO placeholders for the seven qualitative dimensions.
-2. **`--graded` mode** — on top of the stub, composes per-dimension prompts via `scripts/lib/audit-prompt-builder.js` and calls an external model CLI (`--grader-cli`, default `claude -p`) once per dimension. Each response must return a `<verdict>…</verdict>` JSON block matching the fixed schema (dimension / score / verdict / justification / findings[]). The runner parses, validates, and merges these into the artifact files, replacing TODO placeholders with structured PASS / PASS WITH FIXES / FAIL verdicts with evidence quotes.
+2. **`--graded` mode** — on top of the stub, composes per-dimension prompts via `scripts/lib/audit-prompt-builder.js` and calls an explicit external grader CLI (`--grader-cli "<command>"`) once per dimension. Each response must return a `<verdict>…</verdict>` JSON block matching the fixed schema (dimension / score / verdict / justification / findings[]). The runner parses, validates, and merges these into the artifact files, replacing TODO placeholders with structured PASS / PASS WITH FIXES / FAIL verdicts with evidence quotes.
 
 Related files:
 
 - `scripts/lib/audit-prompt-builder.js` — dimension registry, context collector, prompt composer, response parser, verdict aggregator
 - `scripts/lib/mock-grader.js` — deterministic canned-response grader for CI smoke-tests and reproducible examples (prints fixed `<verdict>` blocks per dimension)
 
-Grader CLI discipline: the runner NEVER embeds API keys. Auth is delegated to the external CLI on the host (see `.claude/rules/cli-first.md`). `--grader-cli "claude -p"` and `--grader-cli "codex exec"` both work when the respective CLIs are authenticated.
+Grader CLI discipline: the runner NEVER embeds API keys, never selects a default provider, and never writes model-routing metadata into Skill Graph project artifacts. Auth and provider choice are delegated to the explicit external CLI command supplied by the caller.
 
 ## Suggested Follow-on Scripts
 

package/docs/positioning.md

@@ -0,0 +1,88 @@
+# Positioning — Skill Graph in the Agent-Skills Ecosystem
+
+> **One-line:** Skill Graph is the **authoring contract + audit loop** for agent skills — it sits *above* plain `SKILL.md` files and *beside* protocols like MCP and A2A. It does not host, dispatch, or execute skills.
+
+## What this answers
+
+If you came in via the README hero and asked "where does this fit?", this doc names every adjacent project and draws the boundary. The goal is to make the
+unique angle of Skill Graph legible in under 60 seconds.
+
+## The 60-second pitch
+
+Most agent-skill projects answer one of these questions:
+
+1. **How does an agent find and load a skill?** (Anthropic Skills, agent-skills registries)
+2. **How does an agent call a tool?** (MCP)
+3. **How do agents talk to each other?** (A2A)
+4. **Where do skills get packaged and discovered?** (Smithery, marketplaces)
+5. **How does an agent author orchestrate skill calls in production?** (Composio, agent platforms)
+
+Skill Graph answers a **different** question: **how do you keep a library of skills correct over time?**
+
+It does this by giving every skill a structured contract (`SKILL.md` frontmatter), a graph of typed edges between skills (`relations.*`), a deterministic audit loop (`audit → improve → evaluate`), and a Karpathy-style keep-or-revert discipline for changes. The contract is portable; the audit loop is the unique mechanism.
+
+## The "what this is not" matrix
+
+Skill Graph is not a competitor to MCP, A2A, Anthropic Skills, Smithery, or Composio. They sit at different layers:
+
+| Project | What it is | What Skill Graph is in that frame |
+|---|---|---|
+| **[Anthropic Skills](https://docs.anthropic.com/en/docs/claude-code/skills)** | A discovery + loading convention: agent-runtime auto-loads `SKILL.md` files from a directory and decides what to invoke. | Skill Graph **extends** the `SKILL.md` shape with structured metadata (relations, grounding, eval health) so a library of 100+ skills stays coherent. A plain `SKILL.md` still loads everywhere; Skill Graph adds validation, drift checks, and graph queries on top. |
+| **[Agent Skills spec](https://agentskills.my/specification)** | A portable `SKILL.md` packaging format with a draft cross-runtime contract. | Skill Graph **emits** Agent-Skills-compatible exports (see [`skill-graph export`](../README.md#quick-start)). The Skill Metadata Protocol adds typed relations and audit fields the base spec does not require, but the export is plain. |
+| **[Model Context Protocol (MCP)](https://modelcontextprotocol.io)** | A *runtime* protocol: how an agent client calls a tool server (function calling, structured tools, resources, prompts). | Skill Graph is **build-time and authoring-time**, not runtime. Skills can describe how an agent should use an MCP server (in their body or `relations.depends_on`), but Skill Graph itself does not implement MCP. |
+| **[Agent-to-Agent (A2A)](https://google.github.io/A2A/latest/specification/)** | A *runtime* protocol: how one agent delegates a task to another agent and exchanges capability cards. | Skill Graph's metadata could serve as the capability descriptor an A2A agent advertises, but Skill Graph does not implement A2A delegation, transport, or task lifecycle. |
+| **[Smithery](https://smithery.ai)** | A *registry*: searchable directory of MCP servers and agent skills with install confidence and compatibility signals. | Skill Graph's marketplace export pipeline (`marketplace/skills/`) is one upstream that *feeds* a registry like Smithery; Skill Graph itself is the authoring source, not the registry. |
+| **[Composio](https://docs.composio.dev)** | An *agent tooling platform*: hosted integrations, auth, and tool execution for production agents. | Skill Graph and Composio operate at different layers entirely. A Composio agent could include Skill-Graph-published skills as part of its task brief; Skill Graph does not host or dispatch. |
+| **[AGENTS.md](https://agents.md)** | A *repository-local* convention for instructing coding agents (Claude, Cursor, Codex, etc.) on how to work in a specific repo. | Skill Graph can **ingest** an `AGENTS.md` as a context source for a codebase-scope skill's `grounding` field, but it does not compete with the convention. Skill Graph is repository-portable; AGENTS.md is repository-local. |
+
+## The Karpathy axis (what makes Skill Graph itself distinct)
+
+Most of the above projects are concerned with the *what* and *how* of agent skills. Skill Graph adds an **opinionated discipline** for the *when* — when a skill is changed:
+
+- **One field, one commit, one keep-or-revert decision** ([Karpathy's autoresearch](https://github.com/karpathy/autoresearch) loop, applied to skill libraries instead of training scripts).
+- Every change has a hard pass/fail gate (a deterministic check script that turns red or green).
+- Failed changes auto-revert. The lesson is recorded; the field's truth is preserved.
+
+That discipline is the unique angle. The metadata schema is the substrate that makes it possible — without typed fields, you can't have a deterministic gate. The audit loop is the mechanism. The result is a skill library that drifts less, even as it grows.
+
+## When to reach for Skill Graph
+
+Reach for it when:
+
+- You have **more than ~5 skills** and they have started to depend on, verify, or exclude one another.
+- You want **deterministic checks** for skill correctness (schema, paths, eval health) and not just LLM-as-grader.
+- You want **graph queries** over the library — "what skills depend on this one?", "what's the boundary between X and Y?", "which skills verify this one?"
+- You want a **single audit loop** that produces a fingerprint per skill (`audit_verdict`, `eval_score`, `drift_status`) you can ship in the skill's own frontmatter.
+
+Do NOT reach for it when:
+
+- You have 1–3 skills and a plain folder is enough.
+- You want a hosted skill marketplace (use Smithery, agentskills.io).
+- You want an agent runtime (use Claude Code, Cursor, Codex, etc.).
+- You want a tool execution platform (use Composio, your agent runtime's tool layer).
+
+## Where this puts Skill Graph
+
+In the ecosystem map, Skill Graph sits in the **author-time + audit-time** layer:
+
+```
+runtime layer            Anthropic Skills | MCP | A2A | Composio | Smithery
+                              ↑   ↑     ↑       ↑          ↑
+                              |   |     |       |          |  (consumes published skills)
+author/audit-time layer       └───┴─────┴───────┴──────────┘
+                                          ↑
+                              ┌───────────┴────────────┐
+                              |   Skill Graph (here)   |
+                              | + Karpathy audit loop  |
+                              └────────────────────────┘
+```
+
+The runtime layer answers "how does this skill execute?" The author/audit-time layer answers "how does this library stay correct?" Both are needed; both are different products.
+
+## Related reading
+
+- [`docs/SKILL_METADATA_PROTOCOL.md`](SKILL_METADATA_PROTOCOL.md) — the contract.
+- [`SKILL_AUDIT_LOOP.md`](SKILL_AUDIT_LOOP.md) — the four operations (audit, improve, evaluate, evolve).
+- [`docs/quality-doctrine.md`](quality-doctrine.md) — what "improve" means in this discipline.
+- [`docs/adr/0009-sibling-repo-deprecation.md`](adr/0009-sibling-repo-deprecation.md) — why the protocol, audit, and CLI live in one repo now.
+- [Karpathy autoresearch](https://github.com/karpathy/autoresearch) — the keep-or-revert loop applied to LLM training scripts that Skill Graph borrows for skill libraries.

package/docs/research/skill-comprehension-eval-research.md

@@ -53,7 +53,7 @@ The report does not propose a new schema version, does not redesign lint or drif
 
 ## 2. What the repo currently evaluates
 
-The Skill Graph's evaluation discipline is described in [`AGENTS.MD` § Evaluation Discipline (lines 143–189)](/Users/jacobbalslev/Development/skill-graph/AGENTS.MD). It names four layers, each with its own definition of "good":
+The Skill Graph's evaluation discipline is described in [`AGENTS.md` § Evaluation Discipline (lines 143–189)](/Users/jacobbalslev/Development/skill-graph/AGENTS.md). It names four layers, each with its own definition of "good":
 
 | Layer | Question | Surface | Deterministic? |
 |---|---|---|---|
@@ -171,7 +171,7 @@ The result: a skill author who fills the `concept` block does not know what a co
 
 ### 3.2 No verbatim-copy detector
 
-A failure mode the protocol's quality doctrine warns against — "evals that paraphrase the skill body back to itself" ([`AGENTS.MD` line 186](/Users/jacobbalslev/Development/skill-graph/AGENTS.MD)) — has no test. The current eval files frequently use prompts like:
+A failure mode the protocol's quality doctrine warns against — "evals that paraphrase the skill body back to itself" ([`AGENTS.md` line 186](/Users/jacobbalslev/Development/skill-graph/AGENTS.md)) — has no test. The current eval files frequently use prompts like:
 
 > "According to the X skill's Y section, what is the correct primitive…"
 > (e.g. [`examples/evals/a11y.json:8-16`](/Users/jacobbalslev/Development/skill-graph/examples/evals/a11y.json))
@@ -1045,7 +1045,7 @@ The 10 cases cover all 9 rubric dimensions:
 
 Transfer mix: 6 near-transfer (C1, C3, C4, C7-#1, C8, C9), 4 far-transfer (C2, C5, C6, C7-#2). The schema's heaviest-weighted dimensions (mental_model 1.5, boundary 1.5) both have far-transfer coverage. Misconception has two cases — one near (the Zod question, a domain-internal misconception) and one far (the C++ comparison, a cross-language misconception), exercising the misconception primitive across surface variations.
 
-The minimum threshold (`AGENTS.MD § Evaluation Discipline`: "≥7 realistic scenarios per skill") is exceeded; this file would also satisfy the existing audit-loop's Eval dimension if the grader is updated to accept the comprehension-extension keys.
+The minimum threshold (`AGENTS.md § Evaluation Discipline`: "≥7 realistic scenarios per skill") is exceeded; this file would also satisfy the existing audit-loop's Eval dimension if the grader is updated to accept the comprehension-extension keys.
 
 ### 6.4 What this worked example does NOT cover
 
@@ -1169,7 +1169,7 @@ Update [`SKILL_AUDIT_CHECKLIST.md`](https://github.com/jacob-balslev/skill-audit
 
 **Effort.** ~half day.
 
-**Change.** Add a new section to `docs/skill-metadata-protocol.md` and `docs/field-reference.md § concept` explaining the rubric. Cross-reference from `AGENTS.MD § Evaluation Discipline` so the protocol-level discipline is discoverable. Add the new optional eval-file keys (`comprehension_dimension`, `concept_field`, `transfer`, `expected_behaviors`) to `docs/field-reference.md` with the same field-level treatment as existing keys.
+**Change.** Add a new section to `docs/skill-metadata-protocol.md` and `docs/field-reference.md § concept` explaining the rubric. Cross-reference from `AGENTS.md § Evaluation Discipline` so the protocol-level discipline is discoverable. Add the new optional eval-file keys (`comprehension_dimension`, `concept_field`, `transfer`, `expected_behaviors`) to `docs/field-reference.md` with the same field-level treatment as existing keys.
 
 **Why this is leverage-8.** Without documentation, the rubric is folklore. With documentation in the canonical reference doc, authors discover it during their normal skill-authoring flow.
 
@@ -1397,7 +1397,7 @@ Recommendation, not decision: defer until R3 ships. Once the grader runs and pro
 
 This report examined the following **24 repo files** (23 inside `skill-graph/` plus 1 in the parent `Development/skills/` workspace, added in the 2026-05-16 revision):
 
-1. [`/Users/jacobbalslev/Development/skill-graph/AGENTS.MD`](/Users/jacobbalslev/Development/skill-graph/AGENTS.MD) — full read; especially §§ Evaluation Discipline, Skill Audit Loop, What the Skill Graph Is
+1. [`/Users/jacobbalslev/Development/skill-graph/AGENTS.md`](/Users/jacobbalslev/Development/skill-graph/AGENTS.md) — full read; especially §§ Evaluation Discipline, Skill Audit Loop, What the Skill Graph Is
 2. [`https://github.com/jacob-balslev/skill-metadata-protocol`](https://github.com/jacob-balslev/skill-metadata-protocol) — full read
 3. [`https://github.com/jacob-balslev/skill-audit-loop/blob/main/SKILL_AUDIT_LOOP.md`](https://github.com/jacob-balslev/skill-audit-loop/blob/main/SKILL_AUDIT_LOOP.md) — full read
 4. [`https://github.com/jacob-balslev/skill-audit-loop/blob/main/SKILL_AUDIT_CHECKLIST.md`](https://github.com/jacob-balslev/skill-audit-loop/blob/main/SKILL_AUDIT_CHECKLIST.md) — full read