@skill-graph/cli 0.5.6

package/docs/plans/v4-schema-bump.md

@@ -0,0 +1,160 @@
+# v4 Schema Bump — Historical Reference
+
+> **Status:** Shipped and superseded by v5 (2026-05-16). v4 landed earlier in 2026; v5 closed the `category` field to a 6-value enum (`foundations` / `engineering` / `design` / `quality` / `agent` / `product`) and reframed it as a browse facet. See `docs/migrations/v4-to-v5.md` (in `skill-metadata-protocol`) for the v4→v5 migration matrix and `docs/plans/skill-taxonomy-v5-and-gap-fill.md` (in the Development repo) for the strategy that drove v5.
+>
+> The v4 bump itself was implemented via `scripts/migrate-skill-v3-to-v4.js` with pinned schema copies (`schemas/skill.v4.schema.json`, `schemas/manifest.v4.schema.json`) and migration notes in `docs/manifest-field-mapping.md`. The current pinned-version copies are `schemas/skill.v5.schema.json` and `schemas/manifest.v5.schema.json`.
+>
+> **Original status text (2026-04, pre-ship):** Planned. Not shipped. All items below require coordinated implementation, a codemod (`scripts/migrate-skill-v3-to-v4.js`), pinned schema copies, migration notes, and a full library sweep.
+>
+> **Why a plan doc, not direct changes (2026-04 rationale):** v3 shipped 2026-04-18. A second breaking bump within the same release window burns consumer trust — each bump costs re-tooling downstream. Ship these as a bundle under v4 after v3 settles.
+
+## Scope
+
+Five breaking changes that came out of the Opus + Gemini 3.1 Pro + GPT-5.4 v1 + GPT-5.4 v2 audit (see `.artifacts/` in this repo for the full audit artifacts):
+
+## Public naming candidates from the open-source docs pass
+
+These are naming changes only; do not ship them piecemeal. They need alias handling in v3.x, a codemod in v4, generated-manifest migration notes, and a full starter/template sweep.
+
+| Current v3 name | Candidate v4 name | Why |
+|---|---|---|
+| `type` | `archetype` | The docs and ADRs already teach "archetype"; `type` is too generic for a public schema. |
+| `category` | `domain` | Makes the slash-delimited hierarchy explicit and separates it from flat `category`. |
+| `freshness` | `reviewed_at` | Names the actual authored claim: the skill was reviewed on a date. |
+| `allowed-tools` | `allowed_tools` | Aligns the protocol schema with the rest of its snake_case field names; the SKILL.md export can still emit `allowed-tools`. |
+| `eval_artifacts`, `eval_state`, `routing_eval` | `eval.artifacts`, `eval.content_state`, `eval.routing_coverage` | Groups the eval-health axes and makes the routing axis clearer. |
+| `grounding.domain_object` | `grounding.subject` | Removes DDD jargon; a newcomer can predict what "subject" means. |
+| `grounding.grounding_mode` | `grounding.claim_scope` | Names the semantic axis instead of calling it a mode. |
+| `compatibility.node` | `compatibility.node_version` | Avoids graph-node ambiguity. |
+| `compatibility.runtimes` | `compatibility.agent_runtimes` | Distinguishes agent runtimes from Node/container runtimes. |
+| `portability.targets` | `portability.export_targets` | Names what the target is for. |
+| `drift_check.last_verified` | `drift_check.verified_at` | Aligns date fields with the `_at` convention. |
+
+### 1. `name` pattern → kebab-case only
+
+**Current (v3):** `^[a-z0-9][a-z0-9-/:]*$` — allows `/` and `:` for hierarchical/namespace-style names (e.g., `codex:codex-rescue`).
+
+**v4:** `^[a-z0-9][a-z0-9-]*$` — strict kebab-case. No `/`, no `:`.
+
+**Rationale:** `skills/naming-conventions/SKILL.md:85-95` says *"Every identifier falls into exactly one casing bucket"* and skill directories are kebab-case matching `name:`. Allowing `/` and `:` violates the repo's own naming doctrine and breaks the parent-directory-matches-name invariant that lint already enforces. Portability transforms already normalize to kebab-case on export, so the lenient authored pattern serves no real use case.
+
+**Migration:** All 8 shipped starters already comply. Any downstream consumer using `name: some/thing` or `name: foo:bar` must rename. Codemod emits WARN and suggests a `s/[/:]/-/g` rewrite; manual review recommended for semantic integrity.
+
+---
+
+### 2. `grounding.truth_sources` → object array `{path, start_line?, end_line?}`
+
+**Current (v3):** `string[]` — file paths only.
+
+**v4:**
+
+```yaml
+grounding:
+  truth_sources:
+    - path: src/integrations/shopify/client.ts
+      start_line: 45
+      end_line: 120
+    - path: docs/skill-metadata-protocol.md   # whole-file grounding still valid (omit line range)
+```
+
+Schema:
+```json
+"truth_sources": {
+  "type": "array",
+  "items": {
+    "type": "object",
+    "additionalProperties": false,
+    "required": ["path"],
+    "properties": {
+      "path": { "type": "string", "minLength": 1 },
+      "start_line": { "type": "integer", "minimum": 1 },
+      "end_line": { "type": "integer", "minimum": 1 }
+    }
+  }
+}
+```
+
+**Rationale:** Two independent findings converge:
+- GPT-5.4 v2 doctrine audit: `skills/skill-scaffold/SKILL.md:609-610` requires code-grounded skills to list `## Key Files` with line ranges. Skill Graph's `truth_sources` is the frontmatter equivalent but lacks ranges.
+- Opus + DeepDocs research: whole-file SHA-256 hashes in `drift_check.truth_source_hashes` are too coarse. A 1-line edit to an unrelated function invalidates the hash. Symbol/line-range granularity fixes the noise-to-signal ratio.
+
+**Migration:** Codemod rewrites each bare string `"file"` → `{"path": "file"}`. Authors manually add `start_line`/`end_line` after the mechanical rewrite, based on what each skill actually depends on. `drift_check.truth_source_hashes` then hashes only the referenced range (computed from start_line/end_line), dramatically reducing drift noise.
+
+**Impact on `scripts/skill-graph-drift.js`:** rewrites hash computation to slice the file content by line range before hashing. Line-range keys become `"path#L<start>-<end>"` in `truth_source_hashes`.
+
+---
+
+### 3. `extends` bidirectional enforcement → via schema, not just lint
+
+**Current (v3):** Schema enforces `type: overlay → extends required`. The reverse (non-overlay → no `extends`) is enforced by `scripts/skill-lint.js` (v0.5.0, this session) via an allOf `not` clause. Works, but schema-level + lint-level both belt-and-suspenders is cleaner if the schema itself guarantees the invariant.
+
+**v4:** Keep the allOf rule from v0.5.0 in the v4 schema file explicitly, and remove the lint-level duplicate to reduce drift risk.
+
+**Rationale:** Belt-and-suspenders is correct for v0.5.0 (lint catches the case even if a consumer uses a validator that mis-handles `allOf` + `not`). v4 is the point to consolidate to schema-only enforcement since v4 consumers are expected to use Ajv or equivalent.
+
+---
+
+### 4. `paths` all-negation rejection → schema-level
+
+**Current (v3):** Lint rejects lists of only-negation patterns (v0.5.0 addition). Schema allows it.
+
+**v4:** Schema-level rejection via a JSON Schema pattern-list constraint:
+
+```json
+"paths": {
+  "type": "array",
+  "minItems": 1,
+  "items": { "type": "string", "minLength": 1 },
+  "not": {
+    "items": { "pattern": "^!" }
+  }
+}
+```
+
+The `not` clause rejects arrays where EVERY item starts with `!`.
+
+**Rationale:** Same as #3 — v4 is the consolidation point where lint-only rules move into the schema for tighter consumer contracts.
+
+---
+
+### 5. `activation.paths` gitignore negation → actually implemented in the router
+
+**Current (v3):** `docs/field-reference.md:562-581` and `schemas/skill.schema.json:138-145` describe gitignore-style negation (`!pattern`). `scripts/skill-graph-route.js:121-128` (v3) explicitly states mixed positive/negative lists are NOT implemented.
+
+**v4:** Implement the documented behavior in the router. A path list `["src/**", "!src/generated/**"]` should include everything under `src/` EXCEPT `src/generated/**`. Add test cases in a dedicated `examples/tests/paths-negation.json` that the router consumes as golden fixtures.
+
+**Rationale:** This is not a schema change — the schema already allows it. But it IS a contract change: v3 documented a feature that v3 didn't ship. v4 delivers what v3 promised.
+
+---
+
+## Sequence for the v4 bump (when it ships)
+
+1. Copy current `skill.schema.json` + `manifest.schema.json` to `skill.v3.schema.json` + `manifest.v3.schema.json` (already done in this session as part of v3 pinning).
+2. Apply changes 1–5 above to the unversioned schemas.
+3. Ship pinned `skill.v4.schema.json` + `manifest.v4.schema.json` (content-identical to unversioned).
+4. Write `scripts/migrate-skill-v3-to-v4.js`:
+   - Normalize `name` to kebab-case, WARN on any `/` or `:` replacement so authors review.
+   - Rewrite `grounding.truth_sources` from `string[]` → object-array with `{path}` only; authors add line ranges manually.
+   - Leave `paths` untouched; lint already rejects all-negation in v0.5.0.
+5. Update `docs/manifest-field-mapping.md` with a new § "Migration Note — v3 → v4" containing the transformations above.
+6. Update `docs/field-reference.md` for the changed fields.
+7. Update `SKILL_AUDIT_CHECKLIST.md` schema_version check.
+8. Bump `CHANGELOG.md` root `schema_version` reference to `4`.
+9. Run migrate on all 8 starters + template. Regenerate manifest. Re-run drift sentinel with new hash key scheme.
+10. Run full lint + manifest validation + audit sweep.
+
+## Out of scope for v4 (deferred further)
+
+- `utterances[]` / `examples[]` (v0.5.0 additive, shipped this session).
+- `superseded_by` (v0.5.0 additive, shipped this session).
+- Typed audit artifact schemas (`findings.schema.json`, `verdict.schema.json`, `scorecard.schema.json`) — design doc at `docs/plans/audit-artifact-schemas.md` (to be written).
+- `activation.must_activate_for[]` / `must_not_activate_for[]` as hard routing assertions — subsumed by `examples`/`anti_examples` in v0.5.0. Reconsider if routing evaluation shows gaps.
+- `instructions` vs `description` split — rejected after Gemini + GPT-5.4 v2 both disagreed; body H2 sections already serve the instructions role.
+- Symbol-level drift (`truth_source_symbols`) — v4 line-range approach on `truth_sources` subsumes the motivation.
+
+## Related artifacts in this repo
+
+- `.artifacts/gpt54-audit.md` — v1 audit (schema/lint bugs)
+- `.artifacts/gemini-audit.md` — Gemini 3.1 Pro audit (additional semantics gaps)
+- `.artifacts/gpt54-audit-v2.md` — doctrine-grounded audit (canon fork, process gaps)
+- `.artifacts/audit-brief.md` — the brief used for all three external audits

package/docs/plans/wave-2-extraction.md

@@ -0,0 +1,122 @@
+# Wave 2 Extraction Plan
+
+Status: retained as sequencing rationale. The current repository has already shipped the universal Tier A and Tier B recommendations from `docs/recommended-skills.md`; this plan explains the broader extraction strategy that informed those choices.
+
+## Goal
+
+Wave 2 was the expansion from a small starter set into a library large enough to demonstrate Skill Graph's actual value:
+
+- Multiple archetypes, not only `capability`.
+- Multiple scopes, including portable, reference, and codebase skills.
+- Enough relation density for routing, verification, and boundary behavior to matter.
+- Enough domain variety that `category`, `category`, `workspace_tags`, and `routing_bundles` are visibly different axes.
+
+The goal was not to maximize skill count. The goal was to make the protocol's graph shape observable in real authored skills.
+
+## Selection Axes
+
+Wave 2 candidates were evaluated against four axes:
+
+| Axis | Question |
+|---|---|
+| Universal utility | Would a broad set of developers or agents benefit immediately? |
+| Graph value | Does this skill create useful `relations`, `grounding`, or routing boundaries? |
+| Archetype coverage | Does it exercise `capability`, `workflow`, `router`, or `overlay` behavior? |
+| Scope coverage | Does it prove the difference between portable, reference, and codebase skills? |
+
+The final OSS recommendation split these concerns:
+
+- `docs/recommended-skills.md` optimizes for universal adopter utility.
+- This Wave 2 plan optimizes for expressive coverage and graph density.
+
+## Candidate Clusters
+
+### Core Library Operations
+
+These skills make a Skill Graph library self-maintaining:
+
+- `skill-router`
+- `skill-scaffold`
+- `graph-audit`
+- `skill-infrastructure`
+- `documentation`
+
+### Everyday Engineering
+
+These skills earn broad utility across most software projects:
+
+- `debugging`
+- `testing-strategy`
+- `refactor`
+- `code-review`
+- `version-control`
+- `database-migration`
+- `webhook-integration`
+- `error-tracking`
+
+### AI-Native Engineering
+
+These skills address agent-era work directly:
+
+- `prompt-craft`
+- `context-engineering`
+- `tool-call-strategy`
+- `agent-engineering`
+- `agent-orchestration`
+- `agent-observability`
+
+### Knowledge Organization
+
+These skills demonstrate the protocol's semantic and taxonomic range:
+
+- `taxonomy-design`
+- `ontology-modeling`
+- `semantics`
+- `knowledge-modeling`
+- `knowledge-graph`
+- `bounded-context-mapping`
+
+### Design And UX
+
+These skills demonstrate non-codebase expertise while still benefiting from routing groups and boundaries:
+
+- `a11y`
+- `task-analysis`
+- `user-research`
+- `research-synthesis`
+- `journey-mapping`
+- `layout-composition`
+- `visual-hierarchy`
+- `typography-system`
+- `color-system-design`
+- `interaction-patterns`
+- `form-ux-architecture`
+- `microcopy`
+
+### Doctrine And Strategy
+
+These were treated as advanced, demand-driven candidates because they need stronger body prose and clearer routing boundaries:
+
+- `theory-of-constraints`
+- `ooda-loop`
+- `shape-up`
+- `wardley-mapping`
+- `domain-driven-design`
+
+## Extraction Order
+
+1. Ship the original eight starters as the minimal specimen set.
+2. Close universal Tier A utility: authoring, review, naming, prompting, security, and accessibility.
+3. Add Tier B operational skills that most projects eventually need.
+4. Add one specialized cluster at a time only when the cluster demonstrates a new protocol behavior or clear adopter demand.
+5. Use routing evals and overlap checks after every batch; do not let graph density become duplicate activation noise.
+
+## Exit Criteria
+
+Wave 2 is done when the library has:
+
+- A credible universal baseline for everyday engineering and AI-agent work.
+- At least one strong example of every shipped archetype.
+- Relation edges that are useful to routing and verification, not decorative.
+- Drift and eval metadata that reflect real maintenance posture.
+- Documentation that explains why the current inventory exists without relying on private synthesis notes.

package/docs/positioning-vs-marketplaces.md

@@ -0,0 +1,175 @@
+# Positioning — Skill Graph vs Marketplaces, Rules, and Always-On Conventions
+
+> **Audience.** A working developer who has heard of Skill Graph and is mentally placing it on the AI-coding-context shelf alongside Cursor rules, Claude skills, GitHub Copilot custom instructions, AGENTS.md, skillsmp.com, and skills.sh. This document is a single-source reference for how Skill Graph relates to each.
+>
+> **Status.** Stable. Updated when a new context tool is named in the skill-library landscape (open an issue if a tool is missing).
+>
+> **Last updated.** 2026-05-06.
+
+**Skill Metadata Protocol's job is project-relevance metadata for AI SKILL.md. Skill Graph's job is library-level operation over that metadata.** The protocol asks: which area is this skill for, which angle does it take, which project or stack does it fit, which taxonomy / semantic cluster does it belong to, which methodology or framework does it encode, and how should it be tested or reverified? Skill Graph asks how to index, route, cluster, audit, and reverify a library of skills that expose those declarations. Every comparison below is framed against that split.
+
+## Categories on the shelf
+
+There are five categories of AI-coding context tool, and they solve different problems:
+
+| Category | Examples | What it does |
+|---|---|---|
+| **Open standard for skill packaging** | [Anthropic SKILL.md](https://www.claude.com/skills) | The base format for procedural-knowledge folders an agent can discover and load |
+| **Project-relevance metadata protocol on top of the standard** | **Skill Metadata Protocol** | The skill-level contract that makes skills indexable by area, angle, taxonomy, semantics, project fit, methodology, framework, and verification loop |
+| **Library-level system over skill metadata** | **Skill Graph** (this repo) | The index, router, cluster map, lint/eval harness, drift sentinel, and manifest pipeline that works with Skill Metadata Protocol records |
+| **Public skill libraries / registries** | [skillsmp.com](https://skillsmp.com), [skills.sh](https://skills.sh) | The discovery and installation surface — find a skill, install it |
+| **Always-on repo conventions** | CLAUDE.md, AGENTS.md, Cursor rules, Continue rules, GitHub Copilot custom instructions | Per-repo behavior rules the agent reads at session start (always loaded, not on-demand) |
+
+Skill Metadata Protocol sits in the second category. Skill Graph sits in the third row above. Neither competes with SKILL.md (the protocol is interoperable with SKILL.md via the export transform), public libraries (those help you find skills; the protocol makes chosen skills relevant; Skill Graph makes them indexable, clusterable, routable, and testable inside a project), or always-on repo rules (those are repo behavior rules; Skill Graph is skill-library structure).
+
+---
+
+## Pros and cons per neighbor
+
+### Anthropic SKILL.md
+
+[claude.com/skills](https://www.claude.com/skills) — *"Teach Claude your way of working"*, *"Build once, use everywhere"*, *"Stack skills for complex work"*.
+
+| Axis | Anthropic SKILL.md | Skill Metadata Protocol + Skill Graph |
+|---|---|---|
+| **Required fields** | 2 (`name`, `description`) | 13 in Skill Metadata Protocol; `name` and `description` remain the base bridge to SKILL.md |
+| **Relevance model** | Mostly lexical retrieval over `description` and tag fields | Area, angle, taxonomy, semantic relations, project fit, grounding, eval state, and file/path relevance |
+| **Drift detection** | None — staleness is invisible to the standard | SHA-256 baselines on `truth_sources`; the drift sentinel reports DRIFT / BROKEN / STALE / NO_BASELINE |
+| **Project scoping** | Folder structure or naming hacks | `workspace_tags` + workspace `semantic_tags` matching, no folder gymnastics |
+| **Eval awareness** | Not standardised | `eval_artifacts` + `eval_state` + `routing_eval` triple; routers can gate by quality |
+| **Inheritance** | None | `type: overlay` + `extends` for specialisation with schema-level body-section enforcement |
+| **Round-trip compatibility** | N/A | One-way export to base SKILL.md via `scripts/export-skill.js`; round-trip back requires re-authoring the lost fields |
+
+**When to use both:** when you want Skill Metadata Protocol metadata for authoring and the broader runtime support of SKILL.md' format simultaneously. Author with the protocol; use Skill Graph for library-level operations; export to SKILL.md shape via `scripts/export-skill.js` for runtimes that read only the simpler format. The two contracts are peers, not parent-child.
+
+**When this is overhead, not benefit:** library size below ~3 skills, single project, no grounded skills, no eval pipeline. Skill Metadata Protocol's richer required field set and Skill Graph's tooling are pure tax until at least one of those pressures appears — plain SKILL.md covers the simple case.
+
+---
+
+### skillsmp.com
+
+[skillsmp.com](https://skillsmp.com) — *"Discover open-source agent skills from GitHub."*
+
+| Axis | skillsmp.com | Skill Metadata Protocol + Skill Graph |
+|---|---|---|
+| **What it does** | Public agent-skill library / marketplace that indexes skills from GitHub repositories | Skill Metadata Protocol describes imported or local skills; Skill Graph operates over the resulting library |
+| **Surface** | Discovery and installation (find a skill to install) | Relevance, structure, clustering, routing, testing, and re-verification inside your project |
+| **Hosted** | Yes — independent community-run service | No — the protocol and Skill Graph reference scripts run in your own repo |
+| **Per-skill structure** | Whatever the source repo authored | The 13 required + ~20 optional Skill Metadata Protocol fields |
+
+**When to use both:** install a skill from skillsmp.com -> adopt it into your library -> annotate the frontmatter with area, angle, taxonomy, project tags, relations, grounding, and eval metadata -> benefit from lint, routing, clustering, drift checks, and Karpathy-style iteration loops on top of the imported skill. In the other direction, syndicate the full Skill Graph starter library through plain `SKILL.md` exports so SkillsMP can discover the repo while the canonical Skill Metadata Protocol source stays here. The operating plan is [`docs/marketplace-syndication.md`](marketplace-syndication.md).
+
+**Mental model:** *skillsmp answers "what skills exist?"; Skill Metadata Protocol answers "what is this skill relevant for?"; Skill Graph answers "how can that relevance be indexed, routed, clustered, tested, and reverified?"*
+
+---
+
+### skills.sh
+
+[skills.sh](https://skills.sh) — *"The Open SKILL.md Ecosystem."* The hero copy: *"Skills are reusable capabilities for AI agents. Install them with a single command to enhance your agents with access to procedural knowledge."*
+
+Same category as skillsmp.com. Same distinction: discovery / installation surface vs Skill Metadata Protocol plus Skill Graph. The two public libraries differ in their cataloging conventions and ranking surface (skills.sh leads with a popularity leaderboard, skillsmp leads with GitHub-source provenance), but neither tells a local project which area, angle, taxonomy cluster, semantic relation, methodology, framework, or verification loop a skill belongs to.
+
+**When to use both:** install a popular skill from skills.sh -> adopt the imported folder into your library -> upgrade the frontmatter to Skill Graph spec so it becomes relevant, indexable, clusterable, and testable in your project. In the other direction, export and publish the full Skill Graph library to the plain `SKILL.md` shape, use examples only as entry points, and keep provenance metadata pointing back to the canonical repo.
+
+---
+
+### Cursor rules
+
+[cursor.com/docs](https://cursor.com/docs) — `.cursor/rules/*.mdc` files the IDE applies to every Cursor agent action.
+
+| Axis | Cursor rules | Skill Graph |
+|---|---|---|
+| **What it does** | Repo-behavior guardrails ("always treat this folder as auth-critical", "never modify schemas without a migration") | Skill-library structure (typed relations between many skills, drift detection, eval state) |
+| **Loading model** | Always-on for the IDE's agent — every action consumes the rule context | On-demand — the router selects skills per query, only the selected ones load |
+| **Granularity** | Behavior constraints | Procedural knowledge packages |
+| **Per-runtime** | Cursor IDE specifically | Any agent runtime that supports SKILL.md |
+
+**Take a position:** Cursor rules are repo-behavior guardrails. Skill Graph is skill-library structure. They solve different problems and complement each other in the same repo. A repo can have `.cursor/rules/*.mdc` for IDE-wide behavior rules AND a Skill Graph library at `skills/**` for on-demand skill packaging — these do not compete; they layer.
+
+**When to use both:** always, in a Cursor-using repo with a non-trivial skill library.
+
+---
+
+### Continue rules
+
+`.continue/rules/*` — the [Continue](https://continue.dev) IDE's analog of Cursor rules. Same shape as Cursor: per-repo behavior constraints applied always-on to agent actions.
+
+Same distinction as Cursor: behavior rules vs library structure. Use both.
+
+---
+
+### GitHub Copilot custom instructions
+
+`.github/instructions/*` — per-repo prompt augmentation that ships with every Copilot completion request.
+
+| Axis | Copilot custom instructions | Skill Graph |
+|---|---|---|
+| **What it does** | Inline prompt content prepended to every Copilot request | Routable, validatable, droppable skill-library contract |
+| **Loading model** | Always — every Copilot completion includes the custom instructions | On-demand — only selected skills load |
+| **Routing** | None — Copilot does not load skills dynamically | The router selects per query, with auditable reasoning |
+| **Token impact** | Constant overhead per completion | Variable (depends on which skills the router picks) |
+
+**The honest constraint:** Copilot does not load skills dynamically — Skill Graph assumes a runtime that does (Claude Code, agent runtimes that read SKILL.md). For Copilot specifically, custom instructions and Skill Graph are complementary: custom instructions for the prompt context Copilot always sees, Skill Graph for the on-demand skills a more capable runtime would route to.
+
+**When to use both:** in a Copilot-primary repo where you also use Claude Code or another Skill-Graph-aware runtime — custom instructions handle the always-on baseline, Skill Graph handles the on-demand depth.
+
+---
+
+### CLAUDE.md and AGENTS.md
+
+Plain-text repo-level conventions that Claude Code or generic agent runtimes read at session start.
+
+| Axis | CLAUDE.md / AGENTS.md | Skill Graph |
+|---|---|---|
+| **What it does** | Always-on repo context (small, opinionated, ~100-500 lines typically) | On-demand skill packaging (many, structured, routable, ~50-300 lines per skill) |
+| **Cardinality** | Usually 1 file per repo (sometimes 2-3 with descendant loading) | Many — usually 10+ skills per library |
+| **Update cadence** | Slow (changes when repo conventions shift) | Per-skill (changes when the specific skill's domain or truth source changes) |
+| **Loading** | Read once per session | Per query, by the router |
+
+**When to use both:** AGENTS.md for non-negotiable repo rules (security policies, commit conventions, banned patterns); Skill Graph for the skills the agent reaches for when those rules don't cover the specific task. Together they form a two-layer context: always-on rules + on-demand skills.
+
+---
+
+## What Skill Graph deliberately is not
+
+For symmetry with the README's negative framing:
+
+- **Not a marketplace.** Skill Graph does not host or distribute skills. Use skillsmp.com or skills.sh for that.
+- **Not a runtime.** Skill Graph can feed agent runtimes; it is not one. Claude Code, custom agent harnesses, or any runtime that reads SKILL.md can consume a Skill Graph library at whatever level of awareness it chooses.
+- **Not a prompt library.** The skills' content is your team's procedural knowledge, authored by you; Skill Metadata Protocol structures the relevance metadata around it, not the prose inside it.
+- **Not a competing format.** Skill Metadata Protocol enriches SKILL.md and can be exported to base SKILL.md via `scripts/export-skill.js`.
+- **Not always-on context.** Skills managed by Skill Graph are loaded on-demand by a router; they are not appended to every agent request the way CLAUDE.md or Copilot custom instructions are.
+
+---
+
+## Decision shortcut
+
+If you're trying to decide which tool to reach for:
+
+| You want to… | Reach for |
+|---|---|
+| Find a community-authored skill to install | skillsmp.com or skills.sh |
+| Author a procedural-knowledge folder for an agent | Anthropic SKILL.md (the base standard) |
+| Make a multi-skill library project-relevant, indexable, and testable | **Skill Graph** |
+| Apply repo-wide behavior constraints to every IDE agent action | Cursor rules / Continue rules |
+| Prepend always-on context to every Copilot completion | Copilot custom instructions |
+| Document repo conventions for any agent at session start | CLAUDE.md / AGENTS.md |
+| Detect when a skill's truth source has silently moved | **Skill Graph** (drift sentinel) |
+| Express that one skill depends on another | **Skill Graph** (`relations.depends_on`) |
+| Share some skills across two projects but not all | **Skill Graph** (multi-root workspace mode + `workspace_tags`) |
+
+If your need is in the **Skill Graph** rows, this contract is for you. If your need is in any other row, the named tool is the right primary fit; Skill Graph still complements it where the use cases overlap.
+
+---
+
+## Source URLs (verified 2026-05-06)
+
+- Anthropic SKILL.md: https://www.claude.com/skills
+- Anthropic engineering on Skills: https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
+- Cursor docs: https://cursor.com/docs
+- Continue: https://continue.dev
+- skillsmp.com: https://skillsmp.com
+- skills.sh: https://skills.sh
+- SKILL.md open standard: https://agentskills.io/specification
+
+Each was reachable at the time of writing. URL drift is monitored via the sources cited in the README's positioning table.

package/docs/proposals/skill-audit-loop-positioning.md

@@ -0,0 +1,160 @@
+# Skill Audit Loop — Positioning Proposal
+
+> Type: Proposal
+> Status: Draft for review
+> Date: 2026-05-14
+> Scope: Documentation and positioning only. No schema, field, script, or CLI changes.
+
+## Why this proposal exists
+
+The Skill Audit Loop is currently documented as a maintenance workflow —
+something a library maintainer runs to keep a growing collection of skills
+healthy. That description is accurate but it undersells what the loop does. It
+describes the loop's cadence and outputs without stating its purpose.
+
+This proposal supplies the missing purpose statement and proposes where it goes.
+It does not change the loop, the protocol, or the graph. It changes how two
+documents introduce the loop.
+
+## 1. The conceptual frame
+
+### What the loop is for
+
+A portable capability skill ships as a contract about a subject. The contract
+states what the skill is for, what grounds it, what it must not own, and how it
+should be checked. But the contract is inert on its own. It is a frame, not an
+answer. It becomes useful only when an agent applies it to a specific situation,
+and it stays useful only while the things it was written against still hold.
+
+Two of those things move. The first is the user's codebase: files get renamed,
+patterns get replaced, the truth sources a skill points at drift out from under
+it. The second is the subject itself: specifications get revised, conventions
+shift, the guidance a skill encodes goes from current to dated. A skill written
+against either moving target will, given enough time, describe a world that no
+longer exists.
+
+The Skill Audit Loop is the mechanism that re-grounds a skill against both. It
+is not an optional polish step layered on top of skills that already work — it
+is what keeps a skill working at all once time has passed. A maintainer running
+the loop across their own library is one instance of this. An adopter running
+the loop against their own repository is another instance of the same loop.
+Both are doing the same thing: checking a skill's declared grounding against
+current reality and recording the result.
+
+This is not a new capability. The protocol fields that make the loop possible —
+`grounding.truth_sources`, `grounding.failure_modes`, `freshness`, and
+`drift_check` — already exist and already carry this meaning. The loop has
+always been a re-grounding mechanism. The current documentation describes the
+activity, auditing many skills on a cadence, without naming the purpose:
+keeping each skill true to what it was grounded against.
+
+### The two axes of re-grounding
+
+The loop re-grounds along two independent axes. Both are already expressed in
+protocol fields; neither needs a new term.
+
+| Axis | What moves | Protocol fields that express it | How the loop checks it |
+|---|---|---|---|
+| **Codebase** | The repo the skill is grounded in — renamed files, replaced patterns, moved code. | `grounding.truth_sources` with `path:` entries, `grounding_mode: repo_specific`, `evidence_priority: repo_code_first`, `drift_check.truth_source_hashes` | The drift sentinel hashes each local truth source and reports `DRIFT` or `BROKEN`. Loop Step 5 classifies a mismatch as skill drift, code drift, or documentation drift. |
+| **World** | The subject the skill describes — revised specs, shifted conventions, updated guidance. | `grounding.truth_sources` with URL entries, `grounding_mode: universal`, `grounding.failure_modes`, `freshness`, `lifecycle.review_cadence: on-truth-source-change` | The sentinel marks URL sources `EXTERNAL_UNHASHED` — valid but unfetched, so a human must re-check them. `freshness` is the authored claim that the body was last checked against current understanding on a given date. |
+
+A skill grounded only in local code drifts when the code moves. A skill grounded
+in an external standard drifts when the standard moves. Most real skills are
+`grounding_mode: hybrid` and drift along both axes. The loop is the single
+procedure that checks both, because both are declared in the same `grounding`
+block.
+
+## 2. Where the frame goes
+
+### 2a. README.md — Skill Audit Loop section (proposed rewrite)
+
+Keep the section in its current position. Keep both reference links. Open with
+the frame, then the mechanics.
+
+> ## Skill Audit Loop
+>
+> A skill is a contract about a subject. The contract is inert on its own — it stays useful only while the things it was written against still hold. Two of those things move: the codebase the skill is grounded in, and the subject the skill describes. The Skill Audit Loop re-grounds a skill against both. It is what keeps a skill true to its declared `grounding.truth_sources` once time has passed — whether a maintainer runs it across a whole library or an adopter runs it against their own repo.
+>
+> The loop adapts two useful patterns:
+>
+> - From [Karpathy's `autoresearch`](https://github.com/karpathy/autoresearch): a tight loop with a constrained action surface, a fixed experiment, a measurable result, and keep-or-revert pressure.
+> - From [Stanford d.school design thinking](https://dschool.stanford.edu/resources/design-thinking-bootleg) and [IDEO's design thinking framing](https://designthinking.ideo.com/faq/isnt-design-thinking-a-set-step-by-step-process): human-centered iteration through discovery, framing, ideation, prototyping, testing, and loop-back when evidence changes the problem.
+>
+> For skills, the loop is:
+>
+> 1. Pick a skill or project area.
+> 2. Gather evidence: the `SKILL.md`, eval files, manifest entry, related skills, and `grounding.truth_sources`.
+> 3. Run deterministic checks first: schema lint, relation integrity, manifest validation, routing evals, overlap checks, and drift checks.
+> 4. Audit the skill as a contract: activation, boundaries, taxonomy, grounding, examples, anti-examples, and verification partners.
+> 5. Fix the skill or its metadata when the evidence supports the change.
+> 6. Re-run checks and record the new state.
+> 7. Move to the next skill or loop back if the fix changed the graph.
+>
+> This is not "self-improving skills" as a slogan. It is a re-grounding loop with evidence, constraints, and repeatable checks.
+
+Changes from current text: one new opening paragraph before "The loop adapts
+two useful patterns"; the closing line changes "maintenance loop" to
+"re-grounding loop" to match the frame. The two bullet references and the
+seven-step list are unchanged.
+
+### 2b. SKILL_AUDIT_LOOP.md — opening (proposed rewrite)
+
+The current opening goes straight to scope ("This document standardizes the
+repeatable loop..."). Establish purpose first.
+
+> # Skill Audit Loop
+>
+> A skill is a contract about a subject, and the contract is only true while the things it was written against still hold. The codebase a skill is grounded in changes. The subject a skill describes changes. The Skill Audit Loop is the procedure that re-grounds a skill against both — it checks a skill's declared `grounding.truth_sources` against current reality and records the result.
+>
+> This document standardizes that procedure so it can be run repeatably across many skills.
+>
+> ## Goal
+>
+> The loop exists to keep each skill true to what it was grounded against, and therefore to keep a skill library healthy over time.
+>
+> It should continuously detect:
+>
+> - metadata drift
+> - routing drift
+> - relation drift
+> - stale grounding
+> - weak eval coverage
+> - portability hazards
+
+Changes from current text: two new paragraphs before "This document
+standardizes..."; the Goal sentence is extended to name the per-skill purpose
+ahead of the library-health outcome. The six drift types are unchanged.
+
+## 3. How the loop relates to the other two layers
+
+Short paragraph, suitable for inclusion in README.md or SKILL_GRAPH.md:
+
+> The three layers divide the work cleanly. The Skill Metadata Protocol declares what each skill is grounded against — its `truth_sources`, `grounding_mode`, and `failure_modes`. The Skill Graph operates across the whole library of those declarations, compiling, routing, clustering, and checking them. The Skill Audit Loop is the part of the Skill Graph that re-grounds each skill against its declared sources on a cadence, so the declarations the protocol captured stay true to the reality they point at.
+
+The loop stays inside the Skill Graph layer. It is not promoted to a fourth
+layer and not raised above the protocol.
+
+## 4. What does not change
+
+This repositioning is prose only. Explicitly, it does **not**:
+
+- **rename anything** — Skill Metadata Protocol, Skill Graph, and Skill Audit Loop keep their names.
+- **change the three-layer model** — SKILL.md format → Skill Metadata Protocol → Skill Graph is unchanged. The loop remains a function of the Skill Graph layer.
+- **promote the loop** — the loop is not raised above the protocol or the graph, and the loop is not the product.
+- **add or change schema** — no new fields, no new enum values, no `schema_version` bump.
+- **add scripts or CLI verbs** — `skill-audit.js`, the five loop phases, and the `skill-graph` binary are untouched.
+- **introduce new terms** — the frame is stated entirely in existing protocol vocabulary (`grounding.truth_sources`, `grounding_mode`, `failure_modes`, `freshness`, `drift_check`, `lifecycle`). In particular it does not introduce "concept-shaped skill" or any other new skill category.
+- **replace the protocol** — the loop checks declarations; it does not define them. The protocol is still where grounding is declared.
+- **claim "self-improving skills"** — the existing disclaimer stays. The loop is a re-grounding procedure with evidence and constraints, not an autonomous improver.
+- **change the loop mechanics** — the five phases, the Karpathy and d.school/IDEO references, the cadence table, the artifact contract, and the non-goals are all unchanged.
+
+## 5. Voice check
+
+The proposed prose was checked against the existing README voice:
+
+- **Short declarative sentences.** "The contract is inert on its own." "Two of those things move." Matches the README's "The distinction matters." and "Tags are not a global ontology."
+- **"This is not X" disclaimers preserved.** The "self-improving skills" disclaimer is kept verbatim; the new "not an optional polish step" line follows the same pattern.
+- **No exclamation, no slogans.** None used.
+- **Restraint about novelty.** The frame is explicitly stated as "not a new capability" — consistent with the README's habit of underclaiming ("not a guarantee that every skill is correct").
+- **Tables for structured comparison.** The two-axis table follows the existing README pattern of one concept per row.
+- **Existing terminology only.** Every field name used (`grounding.truth_sources`, `grounding_mode`, `freshness`, `drift_check`, `failure_modes`, `lifecycle.review_cadence`, `evidence_priority`) appears verbatim in SKILL_METADATA_PROTOCOL.md.