@skill-graph/cli 0.5.6

package/bin/skill-graph.js

@@ -0,0 +1,374 @@
+#!/usr/bin/env node
+/**
+ * Public CLI dispatcher for Skill Graph.
+ *
+ * Keeps the existing zero-dependency scripts as the implementation surface and
+ * exposes a stable installable command for users who do not want to clone the
+ * repo just to run one tool.
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const { spawnSync } = require('child_process');
+
+const REPO_ROOT = path.resolve(__dirname, '..');
+
+// ---------------------------------------------------------------------------
+// Subcommand → implementation map
+// ---------------------------------------------------------------------------
+//
+// Script paths are relative to REPO_ROOT. The `inline` key marks subcommands
+// implemented as inline Node code in this file rather than via a delegated
+// script (e.g. `init`).
+//
+// The optional `help` key provides a static help string that is printed when
+// `--help` / `-h` is passed. Use this for scripts that cannot handle --help
+// themselves (e.g. scripts that require positional args or have heavy init
+// that runs before arg-parsing).
+//
+// Spec subcommands (ordered as per SH-6134):
+//   init, add, lint, audit, route, drift, export, evolve
+//
+// Legacy subcommands (retained for backward compat):
+//   manifest, overlap, routing-eval, export-verify, marketplace-export, protocol-check
+
+const COMMANDS = {
+  // ─── Spec subcommands ────────────────────────────────────────────────────
+  init:    { inline: true },
+  add:     { script: 'scripts/marketplace-install.js' },
+  lint:    {
+    script: 'scripts/skill-lint.js',
+    help: `Usage: skill-graph lint [<skill>] [options]
+
+Validate SKILL.md files against the Skill Metadata Protocol schema and lint rules.
+
+Arguments:
+  [<skill>]              Path or name of a specific skill to lint. If omitted, lints all skills.
+
+Options:
+  --include-template     Also lint examples/protocol/skill-metadata-template.md.
+  --path <dir>           Override the skills root directory.
+  --json                 Emit JSON output.
+  --strict               Treat warnings as errors.
+
+Examples:
+  skill-graph lint
+  skill-graph lint my-skill
+  skill-graph lint --include-template
+`,
+  },
+  audit:   {
+    script: 'lib/audit/skill-audit.js',
+    help: `Usage: skill-graph audit <skill-name> [options]
+
+Seed or run a single-skill audit against a SKILL.md file.
+
+Arguments:
+  <skill-name>       Skill directory name (relative to workspace skill roots).
+
+Options:
+  --audit-root <path>   Output directory root (default: examples/audits/).
+  --force               Overwrite existing audit artifacts.
+  --graded              Enable the prompt-driven grader pass.
+  --grader-cli <cmd>    Grader command (default: claude -p). Requires --graded.
+  --grader-timeout <ms> Per-dimension grader timeout (default: 120000).
+
+Examples:
+  skill-graph audit my-skill
+  skill-graph audit my-skill --graded
+  skill-graph audit my-skill --graded --grader-cli "codex exec" --force
+`,
+  },
+  route:   {
+    script: 'scripts/skill-graph-route.js',
+    help: `Usage: skill-graph route <query> [options]
+
+Select and explain which skills are relevant for a natural-language query.
+
+Arguments:
+  <query>            Natural-language description of the task or topic.
+
+Options:
+  --project <name>   Filter to skills in a specific project.
+  --max <n>          Maximum number of skills to return (default: 5).
+  --manifest <path>  Path to compiled manifest (default: skills.manifest.json).
+  --json             Emit JSON output.
+  --min-eval-state   Minimum eval state filter (unverified|passing|monitored).
+
+Examples:
+  skill-graph route "audit my skills for schema conformance"
+  skill-graph route "debug a failing eval" --max 3
+`,
+  },
+  drift:   {
+    script: 'scripts/skill-graph-drift.js',
+    help: `Usage: skill-graph drift [skill] [options]
+
+Check whether grounding truth-source files have changed since the last recorded hash.
+
+Arguments:
+  [skill]            Skill name to check. If omitted, checks all skills.
+
+Options:
+  --record           Record current hashes as the new baseline.
+  --apply <skill>    Apply hash recording to a specific skill only.
+  --json             Emit JSON output.
+
+Examples:
+  skill-graph drift
+  skill-graph drift graph-audit
+  skill-graph drift --record --apply skills/graph-audit
+`,
+  },
+  export:  {
+    script: 'scripts/export-marketplace-skills.js',
+    help: `Usage: skill-graph export [options]
+
+Generate and validate the public marketplace export surface.
+
+Options:
+  --output <dir>    Marketplace output root (default: marketplace).
+  --check           Do not write; fail if generated files are missing or stale.
+  --validate-only   Alias for --check.
+
+Examples:
+  skill-graph export
+  skill-graph export --check
+`,
+  },
+  evolve:  {
+    script: 'lib/audit/skill-evolution-loop.js',
+    requires: ['lib/audit-shared/auto-improve.js'],
+    unmetMessage: `skill-graph evolve depends on lib/audit-shared/auto-improve.js, which is\n` +
+      `not yet bundled in this release. The script also reaches into parent-repo paths\n` +
+      `(scripts/run-skill-improvement-loop.js, scripts/skill-auto-create.js,\n` +
+      `scripts/dispatch-solver.js, agent-orchestration/logs/) that exist only in the\n` +
+      `source Development monorepo.\n\n` +
+      `Standalone-compatible refactor tracked in SH-6138 (parent EPIC SH-6132).\n` +
+      `Until then, run the loop from the source repo where these deps are available.`,
+    help: `Usage: skill-graph evolve [options]
+
+Run the continuous Karpathy-style skill-improvement loop.
+
+Options:
+  --top <n>               Process top n items per cycle (default: 5).
+  --max-cycles <n>        Maximum improvement cycles (default: 10).
+  --max-iterations <n>    Safety cap per cycle (default: 20).
+  --continuous            Auto re-analyze and repeat until convergence.
+  --auto-improve          Full Karpathy spine (analyze → triage → execute → verify).
+  --analyze-only          Produce analysis without executing improvements.
+  --resume                Resume from last checkpoint.
+  --cooldown <sec>        Seconds between continuous cycles (default: 0).
+  --min-priority <n>      Skip items below this priority score (default: 0).
+  --failure-budget <n>    Tolerated failures before aborting (default: 5).
+  --pilot <skill>         Run in bounded pilot lane for a single skill.
+  --actions <list>        Comma-separated action types to allow (default: all).
+
+Examples:
+  skill-graph evolve --top 5 --max-cycles 3
+  skill-graph evolve --continuous --max-cycles 20 --min-priority 5
+  skill-graph evolve --auto-improve --max-cycles 3 --failure-budget 5
+  skill-graph evolve --analyze-only
+  skill-graph evolve --resume
+
+Note: skill-graph evolve is not yet standalone-compatible. It depends on
+      lib/audit-shared/auto-improve.js and several parent-repo scripts that
+      do not yet ship with @skill-graph/cli. Tracking the standalone refactor
+      in SH-6138. Until then, run the loop from the source Development repo.
+`,
+  },
+
+  // ─── Legacy / additional subcommands (backward compat) ───────────────────
+  manifest:           { script: 'scripts/generate-manifest.js' },
+  overlap:            { script: 'scripts/skill-overlap.js' },
+  'routing-eval':     { script: 'scripts/skill-graph-routing-eval.js' },
+  'export-verify':    { script: 'scripts/verify-skill-md-export.js' },
+  'export:verify-skill-md': { script: 'scripts/verify-skill-md-export.js' },
+  'marketplace-export': { script: 'scripts/export-marketplace-skills.js' },
+  'marketplace:export': { script: 'scripts/export-marketplace-skills.js' },
+  'protocol-check':   { script: 'scripts/check-protocol-consistency.js' },
+};
+
+function printHelp() {
+  process.stdout.write(`Usage: skill-graph <command> [args]
+
+Commands:
+  init             Scaffold a new SKILL.md from the official template
+  add <slug>       Install a skill from the marketplace into your library
+  lint [skill]     Validate SKILL.md files against the schema and lint rules
+  audit <skill>    Seed or run a single-skill audit (stub or graded mode)
+  route <query>    Select and explain skills for a natural-language query
+  drift            Check or record grounding truth-source hashes (drift sentinel)
+  export           Generate and validate the public marketplace export surface
+  evolve           Run the continuous skill-improvement loop (Karpathy-style)
+
+Additional commands (retained for backward compatibility):
+  manifest         Generate or validate a skills.manifest.json
+  overlap          Detect duplicate activation signals across skills
+  routing-eval     Run routing examples / anti_examples through the router
+  export-verify    Verify exported skills against the plain SKILL.md export shape
+  marketplace-export
+                   Alias for export
+  protocol-check   Check cross-artifact protocol consistency
+
+Examples:
+  skill-graph init
+  skill-graph add debugging
+  skill-graph lint --include-template
+  skill-graph audit my-skill --graded
+  skill-graph route "audit my skills for schema conformance"
+  skill-graph drift --record --apply skills/graph-audit
+  skill-graph export
+  skill-graph evolve --top 5 --max-cycles 3
+`);
+}
+
+// ---------------------------------------------------------------------------
+// `init` — inline scaffolder
+// ---------------------------------------------------------------------------
+// Copies examples/protocol/skill-metadata-template.md into
+// skills/<slug>/SKILL.md in the caller's working directory (or SKILL.md in
+// the current directory if no slug is given).
+
+function runInit(args) {
+  const helpFlag = args.includes('--help') || args.includes('-h');
+  if (helpFlag) {
+    process.stdout.write(`Usage: skill-graph init [<slug>] [options]
+
+Scaffold a new skill from the official Skill Metadata Protocol template.
+
+Arguments:
+  <slug>          Name for the new skill directory (e.g. "my-skill").
+                  If omitted, writes SKILL.md in the current directory.
+
+Options:
+  --output <dir>  Override the output directory.
+  --force         Overwrite an existing SKILL.md.
+  --help          Show this help.
+
+Examples:
+  skill-graph init
+  skill-graph init my-skill
+  skill-graph init my-skill --output ./skills
+`);
+    process.exit(0);
+  }
+
+  const templateSrc = path.join(REPO_ROOT, 'examples', 'protocol', 'skill-metadata-template.md');
+  if (!fs.existsSync(templateSrc)) {
+    process.stderr.write(`Error: template not found at ${templateSrc}\n`);
+    process.stderr.write('Is REPO_ROOT set correctly? (' + REPO_ROOT + ')\n');
+    process.exit(1);
+  }
+
+  // Resolve output path.
+  let slug = null;
+  let outputDir = null;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--output' && args[i + 1]) { outputDir = args[++i]; }
+    else if (args[i] === '--force') { /* handled below */ }
+    else if (!args[i].startsWith('--')) { slug = args[i]; }
+  }
+  const force = args.includes('--force');
+
+  let destDir;
+  if (outputDir) {
+    destDir = slug ? path.resolve(outputDir, slug) : path.resolve(outputDir);
+  } else {
+    destDir = slug ? path.resolve(process.cwd(), 'skills', slug) : process.cwd();
+  }
+
+  const destFile = path.join(destDir, 'SKILL.md');
+
+  if (fs.existsSync(destFile) && !force) {
+    process.stderr.write(`Error: ${destFile} already exists. Use --force to overwrite.\n`);
+    process.exit(1);
+  }
+
+  fs.mkdirSync(destDir, { recursive: true });
+  fs.copyFileSync(templateSrc, destFile);
+
+  process.stdout.write(`Created: ${destFile}\n`);
+  if (slug) {
+    process.stdout.write(`\nNext steps:\n`);
+    process.stdout.write(`  1. Edit ${destFile} — fill in name, description, domain_context, etc.\n`);
+    process.stdout.write(`  2. Strip all "# TEMPLATE NOTE:" comments and "> **TEMPLATE NOTE:**" blockquotes.\n`);
+    process.stdout.write(`  3. Run: skill-graph lint ${slug}\n`);
+  } else {
+    process.stdout.write(`\nEdit SKILL.md and strip all template scaffolding before shipping.\n`);
+  }
+  process.exit(0);
+}
+
+// ---------------------------------------------------------------------------
+// Main dispatcher
+// ---------------------------------------------------------------------------
+
+function main() {
+  const args = process.argv.slice(2);
+  const command = args.shift();
+
+  if (!command || command === '--help' || command === '-h' || command === 'help') {
+    printHelp();
+    process.exit(0);
+  }
+
+  const entry = COMMANDS[command];
+  if (!entry) {
+    process.stderr.write(`Unknown command: ${command}\n\n`);
+    printHelp();
+    process.exit(1);
+  }
+
+  // Inline subcommands run in-process.
+  if (entry.inline) {
+    if (command === 'init') { runInit(args); }
+    // (future inline commands added here)
+    return;
+  }
+
+  // Intercept --help / -h before delegating to scripts that may not support it.
+  const wantsHelp = args.includes('--help') || args.includes('-h');
+  if (wantsHelp && entry.help) {
+    process.stdout.write(entry.help);
+    process.exit(0);
+  }
+
+  const scriptPath = path.join(REPO_ROOT, entry.script);
+  if (!fs.existsSync(scriptPath)) {
+    process.stderr.write(`Error: implementation script not found: ${entry.script}\n`);
+    process.stderr.write(`REPO_ROOT: ${REPO_ROOT}\n`);
+    process.exit(1);
+  }
+
+  if (Array.isArray(entry.requires) && entry.requires.length) {
+    const missing = entry.requires.filter((rel) => !fs.existsSync(path.join(REPO_ROOT, rel)));
+    if (missing.length) {
+      process.stderr.write(`Error: '${command}' is not standalone-compatible in this release.\n\n`);
+      if (entry.unmetMessage) process.stderr.write(`${entry.unmetMessage}\n\n`);
+      process.stderr.write(`Missing required file(s):\n`);
+      for (const rel of missing) process.stderr.write(`  - ${rel}\n`);
+      process.exit(1);
+    }
+  }
+
+  const result = spawnSync(process.execPath, [scriptPath, ...args], {
+    cwd: process.cwd(),
+    env: {
+      ...process.env,
+      SKILL_GRAPH_PACKAGE_ROOT: REPO_ROOT,
+      SKILL_GRAPH_WORKSPACE: process.cwd(),
+    },
+    stdio: 'inherit',
+  });
+
+  if (result.error) {
+    process.stderr.write(`Failed to run ${command}: ${result.error.message}\n`);
+    process.exit(1);
+  }
+  process.exit(result.status == null ? 1 : result.status);
+}
+
+main();

package/docs/ADOPTION.md

@@ -0,0 +1,117 @@
+# Adopting Skill Graph
+
+> Should you adopt Skill Graph for your AI agent skill library? This page is a 1-screen decision tree. For the full mental model, read [`PRIMER.md`](PRIMER.md). For the contract details, read [`skill-metadata-protocol.md`](skill-metadata-protocol.md).
+
+## Relevance probe
+
+> **Skill Metadata Protocol is for project-relevant skills; Skill Graph is for operating on a library of them.** If your skills are generic (no codebase grounding, no inter-skill relations, one project), plain `SKILL.md` covers it. If you've started authoring skills that reference real files in your repo, that need to coexist with related skills, or that should activate for some projects but not others, you need the protocol. If you then want indexing, routing, clustering, drift checks, and eval loops across the library, you are in Skill Graph territory. For progressive adoption levels, read [`CONFORMANCE.md`](CONFORMANCE.md).
+>
+> The pain test is the same idea, said differently: if you've ever said *"why did the agent load the wrong skill?"* or *"this skill was right last week but the code changed,"* those are the failure modes the contract addresses. Library size is a proxy — these failures usually become worth the extra metadata around 10-15 skills, earlier with multiple projects or grounded codebase skills, later for a single small library.
+
+## You don't have skills yet?
+
+If you have not yet authored any skills, start with plain `SKILL.md` files first. That is the on-ramp. **Pilot Skill Graph on one painful skill before migrating the whole library**: usually around 10-15 skills, or earlier if you have multiple projects, repo-grounded claims, or a real wrong-routing incident.
+
+## Quick yes/no
+
+You should adopt Skill Graph if your skill library has any of these properties:
+
+1. **Two or more skills cover overlapping territory** and the agent routes to the wrong one.
+2. **One skill is load-bearing for another** and you've silently broken the assumption.
+3. **One or more skills are grounded in specific repo files** that change frequently.
+4. **You run evals on skills** and want the router to respect quality.
+5. **You're authoring skills for multiple projects** that share some and diverge on others.
+6. **You need to verify a skill still matches reality** (drift detection on grounded claims).
+
+If none of these apply, stay on plain [`SKILL.md`](https://agentskills.io/specification). The extra fields are overhead without payoff until the library is large enough to produce the implicit graph.
+
+## The 5-minute decision
+
+| You have… | You want… | Recommendation |
+|---|---|---|
+| 0-9 skills, single project, no grounded skills, no wrong-routing incidents | A simple way to author and load instructions | Stay on plain `SKILL.md`; revisit when routing or grounding pain appears |
+| **10+ skills with one wrong-routing incident OR multi-project workspace OR any grounded skill** | Routing that respects relations + drift detection + project scoping | **Pilot Skill Graph on the painful skill first** |
+| Skills grounded in repo files | Drift detection when truth sources change | **Adopt Skill Graph** (drift sentinel) |
+| Multi-project workspace | Shared skills + project-specific overlays | **Adopt Skill Graph** (multi-root mode) |
+| Skills shipped externally | Compatibility with `SKILL.md` consumers | **Adopt Skill Graph + use export transform** |
+| Skills with formal evals | Honest routing claims (lint enforces) | **Adopt Skill Graph** (routing-eval check) |
+
+## Cost-benefit summary
+
+| You pay | Time investment per skill | You get (in outcomes) |
+|---|---|---|
+| 13 required frontmatter fields per skill (vs plain `SKILL.md`'s 2) | ~15-20 min first pass (use template) | Wrong-skill activation becomes debuggable |
+| SHA-256 baselines for grounded skills | ~5 min one-command baseline (`drift-check --record`) | Repo-specific skills stop silently rotting |
+| Cross-skill relation existence checks | ~10 min on day 1 (less afterward as relations stabilise) | Team conventions become auditable rather than tribal |
+| Time-boxed `freshness` claims | <1 min per re-verification | Credibility you can defend in code review |
+| Schema versioning discipline | One-time codemod per major bump | Smooth migration story across breaking schema bumps |
+| One export transform step before publishing externally | ~1 min one command | One-way compatibility with the plain `SKILL.md` format |
+
+**Total time per skill on day 1: ~20-30 min. Steady-state after the library settles: ~10-15 min per new skill.**
+
+The fields you pay for cluster into 8 semantic purposes (Identity, Classification, Health, Eval Health, Activation & Routing, Relations, Grounding, Portability). The full anatomy is in [`skill-metadata-protocol.md § Anatomy`](skill-metadata-protocol.md).
+
+## 5-minute quickstart
+
+> **Step 0 — pilot first, do not migrate the whole library.** Choose ONE skill currently most likely to misroute or drift. Add the required Skill Metadata Protocol fields, route a real query against it, record a drift baseline. Pay the contract once on a skill where the payoff is visible, before paying it 20 times across skills where it isn't yet. The 30-minute walkthrough in [`docs/QUICKSTART-30MIN.md`](QUICKSTART-30MIN.md) walks you through this with literal terminal output at every step.
+
+For the full conceptual primer read [`PRIMER.md`](PRIMER.md). To migrate your first skill from a valid plain `SKILL.md` file:
+
+1. **Copy the template** — `cp examples/skill-metadata-template.md skills/<your-skill>/SKILL.md`. The template is a real, valid, schema-conformant Skill Metadata Protocol skill whose subject is skill authoring itself; adapt by rewriting identity, description, body, and verification.
+2. **Add the 13 required Skill Metadata Protocol fields** — `schema_version: 4`, `version`, `type`, `category`, `scope`, `owner`, `freshness`, `drift_check`, `eval_artifacts`, `eval_state`, `routing_eval`, plus your existing `name` and `description`. The template inline-comments each field.
+3. **Strip the teaching annotations** — every `> **TEMPLATE NOTE:**` blockquote and `# TEMPLATE NOTE:` YAML comment must be removed before commit.
+4. **Validate locally:**
+   ```bash
+   node scripts/skill-lint.js                     # schema + relations + evals + sections
+   node scripts/check-protocol-consistency.js     # cross-artifact parity
+   node scripts/generate-manifest.js              # compile to a deterministic manifest
+   node scripts/skill-graph-route.js --query "your test query"  # see routing in action
+   ```
+5. **If the skill is grounded in repo files**, record the drift baseline:
+   ```bash
+   node scripts/skill-graph-drift.js --record --apply skills/<your-skill>
+   ```
+6. **If you need to publish externally**, project back to plain `SKILL.md` shape:
+   ```bash
+   node scripts/export-skill.js skills/<your-skill>
+   ```
+
+If any step fails, the error message names the rule and the file. Lint output is the primary debugging surface; it's deliberately verbose.
+
+## When to revisit your adoption decision
+
+Re-evaluate the cost-benefit when:
+
+- **Your library exceeds 20 skills.** Implicit graph density is hitting; explicit relations start paying back the authoring cost.
+- **You hit a routing failure** that descriptions alone can't fix. `relations.boundary` and `relations.disjoint_with` exist for exactly this.
+- **An eval reveals a quality gradient** you want to express in metadata. `eval_state` + `eval_artifacts` + `routing_eval` are the three orthogonal axes.
+- **A grounded skill claims something the codebase no longer supports.** The drift sentinel will surface this — but only if you adopted it before the drift accumulated.
+- **You start authoring skills for a second project** that shares some and diverges on others. Multi-root workspace mode + `workspace_tags` is built for this.
+
+## What Skill Graph is *not*
+
+To set expectations honestly:
+
+- **Not a router.** Skill Graph ships a *reference* router (`scripts/skill-graph-route.js`) to demonstrate why the metadata exists. Production routers should consume the manifest and apply their own scoring. The reference router is intentionally simple.
+- **Not a runtime.** Skill Graph defines the contract and ships the validators. It does not load skills into an agent at request time — that's the consumer's job.
+- **Not a full ontology framework.** The relations are typed (boundary, related, broader, narrower, depends_on, verify_with) but Skill Graph does not implement OWL inference, satisfiability checking, or formal class subsumption. Use `ontology-modeling` if you need that.
+- **Not a proprietary format.** The schema is JSON Schema; code and docs are Apache-2.0 and reusable skill content is CC-BY-4.0. The export transform projects protocol skills to the plain `SKILL.md` format.
+
+## Where to go next
+
+| You want to… | Read |
+|---|---|
+| Understand the conceptual model | [`PRIMER.md`](PRIMER.md) |
+| Choose an adoption level | [`CONFORMANCE.md`](CONFORMANCE.md) |
+| Verify `SKILL.md` export compatibility | [`SKILL-MD-FORMAT-COMPATIBILITY.md`](SKILL-MD-FORMAT-COMPATIBILITY.md) |
+| Measure routing quality | [`ROUTING-METRICS.md`](ROUTING-METRICS.md) |
+| Look up a specific field's semantics | [`field-reference.md`](field-reference.md) |
+| See a worked authoring example | [`../examples/skill-metadata-template.md`](../examples/skill-metadata-template.md) |
+| Read the architecture and authority tiers | [`SKILL_GRAPH.md`](../SKILL_GRAPH.md) |
+| See which skills are recommended for a starter library | [`recommended-skills.md`](recommended-skills.md) |
+| Set up CI integration | [`integrations/github-actions.md`](integrations/github-actions.md) |
+| Decide between four overlapping taxonomy axes | [`field-decision-guide.md`](field-decision-guide.md) |
+
+## Compatibility direction (one-paragraph honesty)
+
+A Skill-Metadata-Protocol-enriched `SKILL.md` is **not** the same as the plain export shape. The `compatibility` shape is structured, and protocol fields live at the top level while the export puts extension fields under `metadata:` as strings. Skill Metadata Protocol -> plain `SKILL.md` is automated via `scripts/export-skill.js`. Plain `SKILL.md` -> Skill Metadata Protocol is a manual rewrite: you must add the additional required fields. See [`SKILL-MD-FORMAT-COMPATIBILITY.md`](SKILL-MD-FORMAT-COMPATIBILITY.md) for the verifier contract.

package/docs/CONFORMANCE.md

@@ -0,0 +1,66 @@
+# Skill Graph Conformance
+
+> Read this if you need to decide how much Skill Metadata Protocol structure a
+> skill library should adopt, or if you need to explain compatibility with base
+> `SKILL.md`-compatible runtimes.
+
+Skill Metadata Protocol is an authoring and operations superset. Plain
+`SKILL.md` remains the runtime portability floor. Conformance is therefore layered:
+adopt the smallest level that pays for itself, then move up only when routing,
+grounding, evals, or team maintenance need the extra contract.
+
+## Format Map
+
+| Format | Purpose | Valid where |
+|---|---|---|
+| Plain `SKILL.md` skill | Portable runtime package | `SKILL.md`-compatible runtimes |
+| Skill Metadata Protocol skill | Authoring, routing, grounding, and governance | Skill Graph tooling |
+| Exported `SKILL.md` skill | Runtime artifact generated from Skill Metadata Protocol | `SKILL.md`-compatible runtimes |
+
+## Levels
+
+| Level | Name | Contract | Typical proof command |
+|---|---|---|---|
+| L0 | Portable Skill | Valid plain `SKILL.md`: `name`, `description`, optional base fields. | `skills-ref validate <skill-dir>` |
+| L1 | Routable Skill | Valid Skill Metadata Protocol frontmatter with enough activation metadata to route and explain selection. | `node scripts/skill-lint.js <skill-dir>` |
+| L2 | Grounded Skill | L1 plus `grounding.truth_sources`, `scope: codebase` when appropriate, and a drift baseline. | `node scripts/skill-graph-drift.js <skill-dir>` |
+| L3 | Audited Skill | L2 plus eval artifacts, routing examples / anti-examples, and receipts for claimed passing state. | `node scripts/skill-graph-routing-eval.js --skill <name>` |
+| L4 | Managed Skill | L3 plus CI, ownership, lifecycle cadence, workspace project mapping, and export verification. | `npm run verify` |
+
+## What Each Level Is For
+
+**L0 - Portable Skill.** Use this for small libraries, personal skills, and
+skills that need no cross-skill graph. Do not add protocol fields just to look
+complete.
+
+**L1 - Routable Skill.** Use this when descriptions alone are not enough:
+overlapping skills, ambiguous prompts, path-based activation, or explicit
+`relations.boundary` handoff.
+
+**L2 - Grounded Skill.** Use this when a skill makes claims about real repo
+files, APIs, schemas, or operational behavior. The drift hash proves evidence
+changed or did not change; it does not prove the skill is semantically correct.
+
+**L3 - Audited Skill.** Use this when `eval_state: passing`,
+`routing_eval: present`, or public reuse would otherwise be an unsupported
+claim. Lint should be able to find the artifact or receipt behind the metadata.
+
+**L4 - Managed Skill.** Use this for maintained team libraries. L4 is a library
+posture, not a requirement that every individual skill carry every optional
+field.
+
+## Adoption Rule
+
+Start with one painful skill: the one that misroutes most often, cites repo
+truth, or gets reused across projects. Bring that skill to L2 or L3 before
+migrating the whole library. The protocol is useful when the metadata changes a
+decision a tool can make.
+
+## Related Docs
+
+| Need | Read |
+|---|---|
+| Base-standard mapping and export rules | [`SKILL-MD-FORMAT-COMPATIBILITY.md`](SKILL-MD-FORMAT-COMPATIBILITY.md) |
+| First-skill decision tree | [`ADOPTION.md`](ADOPTION.md) |
+| Field-level authoring rules | [`field-reference.md`](field-reference.md) |
+| Routing metrics and scaling limits | [`ROUTING-METRICS.md`](ROUTING-METRICS.md) |