@skill-graph/cli 0.5.6

package/docs/SKILL_METADATA_PROTOCOL.md

@@ -0,0 +1,609 @@
+# Skill Metadata Protocol
+
+> **Version:** 1.3.0 (schema_version 6, Skill Graph 0.6.0)
+> **Machine-readable schema:** `schemas/skill.v6.schema.json` (v4 and v5 schemas remain for back-compat reads via `normalizeFrontmatter()`)
+> **Migration from v5:** `docs/migrations/v5-to-v6.md`
+> **Migration from v4:** `docs/migrations/v4-to-v5.md`
+> **Detailed field reference:** `docs/field-reference.md`
+> **Full semantics + design rationale:** `docs/skill-metadata-protocol.md`
+
+This document is the top-level public contract for the Skill Metadata Protocol frontmatter format — the **normative spec**. It defines which fields are required, what each field means in operational terms, which fields are authored by humans vs computed by tooling, and how to migrate from older schema versions. Skill Graph is the library-level system that consumes this contract. The prose is terse and boundary-aware: every clause is a rule a consumer or author can verify against the schema and against `scripts/skill-lint.js`.
+
+**Companion docs by genre.** This contract is the *what*. The *why* — design rationale, archetype semantics, OntoClean rigidity, the eval-health triple's orthogonality, the JSON-LD W3C mappings, and the philosophical posture behind the field choices — lives in [`skill-metadata-protocol.md`](skill-metadata-protocol.md). The two docs are coordinated and grow together: a normative rule that lacks a "why" is fragile; a "why" that lacks a normative rule is vapourware. If you are authoring a SKILL.md, you read this file. If you are deciding whether to add a field to the schema, you read both.
+
+---
+
+## Contents
+
+1. [Overview](#overview)
+2. [Required vs Optional Fields](#required-vs-optional-fields)
+3. [Semantic Rules by Field Group](#semantic-rules-by-field-group)
+   - [Identity](#identity)
+   - [Classification](#classification)
+   - [Health and Drift](#health-and-drift)
+   - [Eval Health](#eval-health)
+   - [Activation and Routing](#activation-and-routing)
+   - [Relations](#relations)
+   - [Grounding](#grounding)
+   - [Portability and Standards](#portability-and-standards)
+4. [Authored vs Generated Fields](#authored-vs-generated-fields)
+5. [Migration Notes](#migration-notes)
+6. [Design Constraints](#design-constraints)
+
+---
+
+## Overview
+
+Every skill is a single `SKILL.md` file with a YAML frontmatter block. The frontmatter is validated by `skill-lint.js` against `schemas/skill.v6.schema.json`. The `generate-manifest.js` script reads frontmatter from all skill files and emits a single `skills.manifest.json`.
+
+The contract has one runtime model: one `SKILL.md` per skill, one manifest, one lint pass. There is no closed/open split, no private control plane, and no enterprise-only fields.
+
+---
+
+## Required vs Optional Fields
+
+### Required for all skills
+
+All thirteen fields in this group are required. A skill missing any of them fails lint with an error.
+
+| Field | Type | Purpose |
+|---|---|---|
+| `schema_version` | integer `6` | Signals the contract version. Must be `6` for all v6 skills. See `docs/migrations/v5-to-v6.md`. |
+| `name` | string | Stable identifier. Used for routing and `relations.*` targets. |
+| `description` | string (≥20 chars) | Routing contract — tells the router when to activate this skill. |
+| `version` | semver string | Skill content version (e.g. `1.2.0`). Bumped by the author. |
+| `type` | enum | One of: `capability`, `workflow`, `router`, `overlay`. |
+| `category` | enum | Browse facet. One of: `foundations`, `engineering`, `design`, `quality`, `agent`, `product`. See § Classification for the foundations-gate. |
+| `scope` | enum | One of: `codebase`, `reference`, `portable`. |
+| `owner` | string | Team, username, or tool that is responsible for keeping this skill current. |
+| `freshness` | ISO date | Date the skill body was last reviewed or updated. |
+| `drift_check` | object | Contains `last_verified` (ISO date) and optional `truth_source_hashes`. |
+| `eval_artifacts` | enum | One of: `none`, `planned`, `present`. |
+| `eval_state` | enum | One of: `unverified`, `passing`, `monitored`. |
+| `routing_eval` | enum | One of: `absent`, `present`. |
+
+### Conditionally required
+
+These fields are required only when a specific condition is met. The first three are enforced by JSON-Schema `allOf` rules; the `keywords` rule is enforced by `scripts/skill-lint.js` (lint check R1) rather than the schema, since the schema cannot reason about routability intent.
+
+| Field | Required when | Enforced by |
+|---|---|---|
+| `extends` | `type: overlay` | schema `allOf` |
+| `grounding` | `scope: codebase` | schema `allOf` |
+| `superseded_by` | `stability: deprecated` | schema `allOf` |
+| `keywords` | `scope: codebase` OR `routing_bundles` is set | `scripts/skill-lint.js` (lint check R1) |
+
+### Optional (strongly recommended)
+
+Not schema-required, but most useful skills include these:
+
+```yaml
+stability       # experimental | stable | frozen | deprecated
+license         # SPDX identifier (e.g. MIT, Apache-2.0)
+keywords        # string[] — semantic phrases for discovery
+triggers        # string[] — exact match activation phrases
+relations       # typed edges to sibling skills
+```
+
+### Optional (enrichment)
+
+These improve portability, discoverability, and health tracking but are not required for a valid skill.
+
+```yaml
+urn             # globally unique URN
+domain          # hierarchical domain path (e.g. "ecommerce/integrations/shopify")
+paths           # glob[] — code surfaces this skill governs
+examples        # string[] — positive activation prompts
+anti_examples   # string[] — negative activation prompts (wrong-skill training)
+workspace_tags    # string[] — project handles or semantic tags
+routing_bundles  # string[] — routing group memberships
+portability     # { readiness, targets }
+lifecycle       # { stale_after_days, review_cadence }
+runtime_telemetry  # { feedback_source, metrics }
+comprehension_state # absent | present
+# Understanding fields (v6+, flat) — required when comprehension_state: present
+mental_model    # string — primitives and their relationships
+purpose         # string — the problem this concept solves
+boundary        # string — what this concept is NOT (with mechanism, not just label)
+analogy         # string — one-sentence metaphor preserving the core mechanism
+misconception   # string — the wrong mental model people bring
+concept         # DEPRECATED in v6 — legacy v5 nested block; back-compat only
+# Health Block (v6+, flat) — written by the audit loop, not hand-authored
+last_audited    # ISO date — when `audit` last ran
+last_changed    # ISO date — when the SKILL.md was last edited
+audit_verdict   # PASS | PASS_WITH_FIXES | PARTIAL | FAIL | UNKNOWN
+eval_score      # number 0.0–5.0 — latest aggregate eval grade
+eval_failed_ids # string[] — failing eval IDs (empty when clean)
+lint_verdict    # PASS | FAIL | UNKNOWN
+drift_status    # OK | DRIFT | BROKEN | STALE | NO_BASELINE | EXTERNAL_UNHASHED | UNKNOWN
+eval_last_run   # { at, status, runner?, model?, receipt?, receipt_hash? }
+compatibility   # { runtimes, node, notes }
+allowed-tools   # space-separated tool allowlist
+```
+
+---
+
+## Semantic Rules by Field Group
+
+### Identity
+
+**`name`**
+- Pattern: `^[a-z0-9][a-z0-9-/:]*$` — lowercase alphanumerics, hyphens, forward slashes, and colons.
+- Must match the parent directory name when possible so plain `SKILL.md` export can use the directory as the canonical identifier.
+- Other skills reference this skill using the `name` value in their `relations.*` arrays.
+
+**`description`**
+- The routing contract, not a summary. Write for the router, not for a human reader.
+- Lead with a trigger clause: `"Use when…"` or `"Activates for…"`.
+- Include an explicit negative boundary: `"Do NOT use for…"`.
+- Keep this focused on routing. The `## Coverage` section inside the body carries the full scope detail.
+
+**`version`**
+- Semver format: `x.y.z`. Bumped when the skill's instructional content changes.
+- Independent of `schema_version` — the schema version signals the contract shape; the skill version signals the content revision.
+
+**`owner`**
+- A team handle, GitHub username, or tool name (e.g. `skill-bot`).
+- Consumers use this to route review requests and alert on stale skills.
+
+### Classification
+
+**`type`**
+- `capability` — a skill that describes knowledge or a repeatable technique.
+- `workflow` — a skill that describes a step-by-step process or procedure.
+- `router` — a skill that describes routing logic (which skill to activate for which query).
+- `overlay` — a skill that specialises another skill. Must have `extends: <parent-skill-name>`. Non-overlay types must NOT have `extends`.
+
+**`scope`**
+- `codebase` — repo-specific; requires the `grounding` block so consumers know which files anchor the skill's claims.
+- `reference` — general-purpose reference knowledge not tied to a specific codebase.
+- `portable` — cross-repo knowledge, intended for distribution via `portability.targets`.
+
+**`category`**
+- A browse facet — answers the single question: *Where should a human browse to find this skill first?*
+- Renamed from v3 `browse_category`; use `category` in all v4+ skills.
+- For hierarchical taxonomy, use the optional `domain` field with slash-delimited segments.
+- **Closed enum as of schema_version 5** (retained in v6); enforced at the schema level by `enum` constraint in `schemas/skill.v6.schema.json` AND at the lint level by `scripts/lint/check-category-enum.js`. Framed as a browse facet, not ontology truth. Cross-cutting truth lives in `relations.related`. The six values:
+
+  | Value | Definition |
+  |---|---|
+  | `foundations` | Epistemics, grounding, verification, context engineering, reasoning — preconditions of competent agent or engineering work. Reserved category — must justify membership against the foundations gate; cannot default here. Target size 8–15 skills. |
+  | `engineering` | Building software systems: APIs, data, infra, runtime, integrations. |
+  | `design` | Visual, interaction, IA, content, motion — design as a discipline. |
+  | `quality` | Cross-cutting non-functional properties: a11y, performance, security, type-safety, testing, observability. Properties of any artifact. |
+  | `agent` | Agent-specific concepts: tool design, prompt design, agent state, orchestration, eval-driven dev. |
+  | `product` | Prioritization, scope, MVP, PRDs, customer journey, positioning. |
+
+  **Disambiguation rules** (apply in order):
+  1. *Primary surface* — what the skill is *about*, not what it *enables*.
+  2. *Property vs subject* — properties (a11y, perf, security, testing, type-safety) → `quality`. How-to-build → `engineering` / `design` / `agent`.
+  3. *Cross-pollination* — multi-fit skills list secondary categories via `relations.related` (max 5). Never via the `category` field itself.
+  4. *`foundations` gate* — anti-junk-drawer. Membership requires (a) the skill teaches an epistemic precondition AND (b) it cannot be plausibly assigned to `agent`/`engineering`/`quality`/`design`. If `foundations` exceeds 20 entries, the gate has failed and the migration is misrouted.
+
+**`domain`**
+- Optional slash-delimited domain path (e.g. `design/ux`, `architecture/events`).
+- Renamed from v3 `category` / `category_path`; values are unchanged.
+- Complements `category`. Do not use it as a second flat shelf.
+
+**`stability`**
+- `experimental` — may change without notice; use with caution.
+- `stable` — follows semver; breaking changes bump `schema_version` or `version`.
+- `frozen` — no longer evolving; pinned for historical reference.
+- `deprecated` — replaced by another skill; `superseded_by` is required when this value is set.
+
+### Health and Drift
+
+**`freshness`**
+- ISO date of the last review or content update.
+- Not computed; the author sets it. It is an authored claim, not a hash.
+
+**`drift_check`**
+- Object with `last_verified` (ISO date, required) and `truth_source_hashes` (optional).
+- `last_verified`: when the skill was last verified against its truth sources.
+- `truth_source_hashes`: a map of normalized truth-source key -> SHA-256 hex digest at the time of last verification. Keys are `path` for whole-file sources, `path#Lstart-Lend` for line ranges, and `path#anchor` for anchor-only sources. Computed by `node scripts/skill-graph-drift.js --record --apply <skill-dir>` for local truth sources. The drift sentinel (`skill-graph drift`) reports `DRIFT` when a live hash differs from the recorded hash, `BROKEN` when a local truth source file is missing, `STALE` when today exceeds `last_verified + lifecycle.stale_after_days`, `NO_BASELINE` when local truth sources are declared but no hashes are recorded, and `EXTERNAL_UNHASHED` when a URL truth source is valid but is not fetched by the zero-dependency sentinel.
+
+**`lifecycle`**
+- Optional object: `{ stale_after_days, review_cadence }`.
+- `stale_after_days`: integer days after `drift_check.last_verified` at which the skill is flagged stale. Integration skills that wrap external APIs typically need shorter windows (30–90 days) than pure concept skills (180+ days).
+- `review_cadence`: one of `per-commit`, `weekly`, `quarterly`, `on-truth-source-change`.
+
+### Eval Health
+
+The three eval-health fields are orthogonal — they measure different dimensions.
+
+**`eval_artifacts`** — Does an evaluation artifact exist?
+- `none`: no evals defined.
+- `planned`: evals are planned but not yet written.
+- `present`: at least one eval file exists.
+
+**`eval_state`** — What is the current evaluation result?
+- `unverified`: evals exist but have not been run against a grader.
+- `passing`: evals have been run and pass.
+- `monitored`: evals are integrated into CI and are tracked.
+
+**`routing_eval`** — Does a routing-specific eval exist?
+- `absent`: no routing eval.
+- `present`: a routing eval exists (typically `evals/routing.json` or similar).
+
+**`comprehension_state`**
+- Optional comprehension-grading axis.
+- `absent` or omitted: no comprehension grading is declared.
+- `present`: the skill has comprehension grading and must populate either the **five flat Understanding fields** (`mental_model`, `purpose`, `boundary`, `analogy`, `misconception` — preferred in v6) OR the legacy nested `concept` block (v5 back-compat).
+- The v6 schema's `allOf` rule enforces this via an `anyOf` clause: at least one of the two shapes must be present. When both are present, the flat fields win.
+
+### Understanding (v6+, flat)
+
+Five flat top-level fields that teach the agent what the skill's subject *is*. They replace the v5 nested `concept` block (which retired the `definition` and `taxonomy` sub-fields: `definition` is now covered by `description`, `taxonomy` by `category` + `relations.broader`). The body's `## Concept Card` section is retired in v6 — the flat frontmatter fields are the canonical location.
+
+Required when `comprehension_state: present`. No protocol length cap on any of these — author each field as deeply as the concept requires.
+
+**`mental_model`**
+- Primitives and their relationships. Name the primitives. Name the relationships between them. Markdown permitted inside the string.
+- Graded by the comprehension grader's `mental_model` dimension (weight 1.5).
+- Distinct from `## Philosophy` in the body, which explains *why this skill file exists in this repo*; `mental_model` explains *what the subject is, universally*.
+
+**`purpose`**
+- What problem the concept solves AND the alternative it replaced. Concrete pain point + prior alternative.
+- Graded by the comprehension grader's `purpose` dimension (weight 1.0).
+
+**`boundary`** (the Understanding field — distinct from `relations.boundary`)
+- Things commonly confused with the concept but that are NOT it. Express each difference as a *mechanism* (different primitives, different purpose, different scope) — not just different names.
+- Graded by the comprehension grader's `boundary` dimension (weight 1.5).
+- Field-name collision with `relations.boundary` is intentional and disambiguated by nesting depth: top-level `boundary` is a string teaching the concept's edges; `relations.boundary` is an array of skill-name handoff targets.
+
+**`analogy`**
+- One-sentence analogy that preserves the core mechanism. Translate for a non-expert without breaking the structural relationship between primitives.
+- Graded by the comprehension grader's `analogy` dimension (weight 0.5).
+
+**`misconception`**
+- The wrong mental model people bring and why it misleads. Authored hint to inoculate the agent against the common error trap.
+- Not directly graded; complements `boundary`.
+
+**`concept`** (DEPRECATED in v6 — accepted for v5 back-compat)
+- Legacy nested teaching block with seven sub-fields: `definition`, `mental_model`, `purpose`, `boundary`, `taxonomy`, `analogy`, `misconception`.
+- Remains accepted for v5 skills not yet migrated. Lint emits a warning when `concept` is populated but the flat Understanding fields are absent and `schema_version: 6` is set.
+- The comprehension grader reads either location; flat fields win when both are present.
+
+**`eval_last_run`**
+- Optional evidence receipt for the most recent eval run.
+- Required sub-fields when present: `at` (ISO date-time) and `status` (`pass`, `fail`, or `mixed`).
+- Optional sub-fields: `runner`, `model`, `receipt`, `receipt_hash`.
+- Use this to support `eval_state: passing` or `eval_state: monitored` with a concrete scorecard, grader history, or CI receipt.
+
+### Health Block (v6+, flat — written by the audit loop)
+
+Seven flat top-level fields that record a skill's audit fingerprint in its own frontmatter, replacing the scattered log-file model of v5 (`eval-history.jsonl`, `routing-misses.jsonl`, `.opencode/progress/skill-audit-*`, `health-ledger.jsonl`, `findings/*.md`). The Skill Audit Loop reads these directly; no log-file crawl required.
+
+**Do not hand-author these fields.** They are stamped by `scripts/skill/skill-audit.js`, `scripts/skill/evaluate-skill.js`, and `scripts/skill-graph-drift.js` as the audit loop runs. Hand-edits will be overwritten on the next `audit` run.
+
+**`last_audited`**
+- ISO date (YYYY-MM-DD) the `audit` command last ran against this skill.
+- Loop priority uses this to pick the stalest skill next.
+- Distinct from `freshness` (the author's claim of content-level review) and `drift_check.last_verified` (the truth-source verification timestamp).
+
+**`last_changed`**
+- ISO date (YYYY-MM-DD) the SKILL.md body or frontmatter was last edited.
+- Written automatically by `improve` operations.
+- Distinct from `freshness` (review claim) — `last_changed` is the editor's footprint, `freshness` is the reviewer's footprint.
+
+**`audit_verdict`**
+- Aggregate result of the most recent `audit` run.
+- Enum: `PASS` | `PASS_WITH_FIXES` | `PARTIAL` | `FAIL` | `UNKNOWN`.
+- Combines `lint_verdict`, `drift_status`, and (when run with `--graded`) the seven dimension scores.
+- `UNKNOWN` is the initial state before any audit has run.
+
+**`eval_score`**
+- Latest aggregate eval grade on a 0.0–5.0 scale.
+- Written by `scripts/skill/evaluate-skill.js`.
+- When `evals/comprehension.json` exists, the comprehension grader's score lands here; otherwise the standard eval-suite score.
+
+**`eval_failed_ids`**
+- String array of eval IDs that failed in the most recent run. Empty array when clean.
+- Populated alongside `eval_score` by the eval runner.
+
+**`lint_verdict`**
+- Result of the most recent deterministic-lint pass.
+- Enum: `PASS` | `FAIL` | `UNKNOWN`.
+- `PASS` means zero lint errors; warnings do not flip the verdict.
+
+**`drift_status`**
+- Current truth-source drift status, mirroring `scripts/skill-graph-drift.js` sentinel verdicts.
+- Enum: `OK` | `DRIFT` | `BROKEN` | `STALE` | `NO_BASELINE` | `EXTERNAL_UNHASHED` | `UNKNOWN`.
+- Written by the drift sentinel; read by the loop to prioritise re-grounding work.
+
+### Activation and Routing
+
+**`keywords`**
+- Semantic phrases used by fuzzy/embedding-based routers.
+- Required when `routing_eval: present` — if you assert that routing evals pass, the skill must declare what it should activate on.
+
+**`triggers`**
+- Exact match strings. A router that supports exact triggers activates this skill when the user input exactly matches one of these strings.
+- Complement `keywords` (semantic) and `examples` (full prompts).
+
+**`paths`**
+- Glob patterns identifying the code surfaces this skill governs.
+- Patterns prefixed with `!` are negations (gitignore-style).
+- A list consisting only of negations matches nothing and is rejected by lint.
+
+**`examples`**
+- Positive-class activation examples — realistic user prompts this skill SHOULD activate for.
+- 2–5 entries recommended. Used as few-shot signal for embedding-based routers.
+
+**`anti_examples`**
+- Negative-class activation examples — realistic prompts that look related but a DIFFERENT skill should handle.
+- Pair with `relations.disjoint_with` to name the skill that should activate instead.
+
+**`workspace_tags`**
+- Literal project handles or semantic tags identifying which projects this skill is relevant to.
+- Absent means the skill is ambient (applies across all projects).
+- A workspace config at `.skill-graph/config.json` can map literal project handles to semantic tag sets.
+
+**`routing_bundles`**
+- String array of routing group memberships. Used by routers that dispatch to groups of skills rather than individual skills.
+
+### Relations
+
+The `relations` block contains typed edges to sibling skills. All targets are validated by lint — a broken target (skill that does not exist) is an error.
+
+```yaml
+relations:
+  related:        # symmetric co-read relation (skos:related). v3.1 preferred name.
+  boundary:       # routing-layer anti-ownership handoff (sg:disjointOwnership).
+  disjoint_with:  # formal class-disjointness assertion (owl:disjointWith).
+  verify_with:    # skills to co-load for verification (prov:wasInformedBy).
+  depends_on:     # skills this skill requires operationally or conceptually.
+  broader:        # this skill is a specialisation of the target skill (skos:broader).
+  narrower:       # this skill is a generalisation of the target (skos:narrower).
+```
+
+**`related`** (preferred) / `adjacent` (deprecated alias)
+- Symmetric associative relation. Use when two skills should be co-read because they cover the same surface from different angles.
+- Maximum 5 entries recommended to avoid hub-and-spoke clutter.
+- `adjacent` is a deprecated alias from v3.0. Use `related` in all new skills. Lint emits a warning on `adjacent`.
+
+**`boundary`** (the routing-layer field — distinct from the top-level Understanding `boundary` field)
+- Routing-layer anti-ownership handoff. Use to make explicit that this skill does NOT own the target concern and should hand near-miss prompts to another skill.
+- Items may be bare skill names or `{ skill, reason }` objects. Reasons are strongly recommended.
+- This is a Skill-Graph-specific routing predicate, not formal OWL class disjointness.
+
+**Runtime semantic — score-aware exclusion-on-tie.** The runtime router applies `relations.boundary[]` as `if (target.score >= declarer.score) skip target` — i.e. the declarer can exclude the target only when the declarer is *currently outscoring* it on the query. The semantic INVERTS the surface reading "I am NOT B; defer to B" — boundary entries protect the declarer's wins, not the target's wins. (Source: `skill-graph/scripts/skill-graph-route.js:548`.)
+
+**Cross-domain boundary doctrine — SAME-DOMAIN ONLY.** Codified 2026-05-17 after the Tier C″ empirical sweep across 8 Wave 6 skills:
+
+1. `boundary[]` entries should declare SAME-DOMAIN handoffs only (same `category` AND same `domain` sub-tree). Example: `engineering/frontend` ↔ `engineering/frontend` is fine; `engineering/frontend` ↔ `design/component-systems` is not.
+2. Cross-category or cross-sub-domain handoffs belong in `anti_examples` + `relations.related`, NOT in `boundary[]`. The `anti_examples` array preserves routing-visible documentation as wrong-use phrases; `relations.related` signals the semantic adjacency without invoking the score-aware exclusion mechanic.
+3. Empirical justification: removing 16 cross-domain `boundary[]` entries across 8 skills caused **0 top-1 routing changes** on the 30-query baseline; only 3/30 low-confidence unmaskings of legitimate alternatives at score 3 surfaced. The cross-domain entries were performing silent low-confidence exclusion only — exactly the silent-failure risk the doctrine prevents.
+
+Authors who introduce a cross-domain `boundary[]` entry must move it to `anti_examples` + `relations.related` instead. Lint (planned, not yet implemented) will warn on cross-domain boundary declarations.
+
+**`disjoint_with`**
+- Formal class-disjointness assertion. Use only when the two skill concepts are genuinely disjoint in the ontology sense.
+- Items may be bare skill names or `{ skill, reason }` objects.
+- Do not use it as a replacement for routing-layer `boundary`.
+
+**`verify_with`**
+- Skills to co-load when verifying claims in this skill. Maps to `prov:wasInformedBy`.
+- Keep to 1–3 high-signal verifiers.
+
+**`depends_on`**
+- Skills this skill requires. Items may be bare skill names or `{ skill, min_version }` objects for version-constrained dependencies.
+
+**`broader` / `narrower`**
+- Cross-skill generalisation/specialisation edges (SKOS). Use `broader` when this skill is a specialisation of another skill that is not its overlay parent. `narrower` is the inverse; tooling can infer it from other skills' `broader` edges.
+
+### Grounding
+
+Required when `scope: codebase`. Describes where the skill's claims are anchored in the codebase.
+
+```yaml
+grounding:
+  domain_object: string         # What the skill is about (e.g. "Shopify order sync")
+  grounding_mode: repo_specific | universal | hybrid
+  truth_sources:                # Files whose content the skill depends on
+    - path: src/path/to/file.ts
+      line_range: { start: 10, end: 80 }
+      note: "Primary implementation surface"
+  failure_modes:                # What goes wrong when the skill is applied incorrectly
+    - "Misapplied to a different integration"
+  evidence_priority: repo_code_first | general_knowledge_first | equal
+```
+
+- `grounding_mode: repo_specific` — the skill's claims are only valid in this repo.
+- `grounding_mode: universal` — the skill's claims are general and not repo-specific.
+- `grounding_mode: hybrid` — some claims are repo-specific, some are general.
+- `evidence_priority` — tells consumers how to resolve conflicts between the skill body and external knowledge.
+
+`truth_sources` accepts legacy string entries for whole resources and object entries with `path`, optional `line_range`, optional `anchor`, and optional `note`. Object entries are preferred for repo-backed claims because the drift sentinel can hash the exact source slice.
+
+### Portability and Standards
+
+**`portability`**
+- Declares the skill's export readiness.
+- `readiness`: `declared` (intent only), `scripted` (a transform exists), or `verified` (the export has been tested).
+- `targets`: array of export targets. Only `skill-md` is valid today.
+
+**`urn`**
+- Optional in v3; required in v4.
+- Format: `urn:skill:<repo-slug>:<skill-name>`. Example: `urn:skill:skill-graph:debugging`.
+- The `<skill-name>` segment must equal the `name` field exactly.
+- Consumers treat the URN as the stable identity across repos and federated registries.
+
+**`license`**
+- SPDX identifier (e.g. `MIT`, `Apache-2.0`).
+- Strongly recommended for any skill intended for distribution.
+
+**`compatibility`**
+- Object: `{ runtimes?, node?, notes? }`.
+- `runtimes`: array of target agent runtimes with optional version constraints (e.g. `claude-code>=2.0`).
+- `node`: Node.js version constraint (e.g. `>=18`).
+- `notes`: free-text notes. No protocol length cap.
+
+**`allowed-tools`**
+- Space-separated string of tool names the skill is authorized to invoke.
+- Inherited from the plain `SKILL.md` format.
+
+---
+
+## Authored vs Generated Fields
+
+### Authored in `SKILL.md` (human-written)
+
+The canonical fields in the frontmatter are authored by humans, with two exceptions: `drift_check.truth_source_hashes` is computed by the drift sentinel (`skill-graph drift --record --apply`), and the seven **Health Block** fields (`last_audited`, `last_changed`, `audit_verdict`, `eval_score`, `eval_failed_ids`, `lint_verdict`, `drift_status`) are stamped automatically by the Skill Audit Loop's `audit`, `improve`, and `evaluate` operations. Do not hand-author the Health Block — those values are owned by the loop.
+
+**Human-authored fields:**
+
+```
+schema_version, name, urn, description, version, type, category,
+domain, scope, owner, freshness, drift_check, eval_artifacts, eval_state,
+routing_eval, comprehension_state, eval_last_run, stability,
+superseded_by, license, compatibility, allowed-tools, extends, triggers,
+keywords, examples, anti_examples, paths, workspace_tags, routing_bundles,
+relations, grounding, portability, lifecycle, runtime_telemetry,
+# Understanding (v6+) — author these when comprehension_state: present
+mental_model, purpose, boundary, analogy, misconception,
+# Legacy v5 — accepted for back-compat
+concept
+```
+
+**Loop-written fields (v6+, Health Block):**
+
+```
+# Stamped by `audit` / `improve` / `evaluate` — do not hand-author
+last_audited, last_changed, audit_verdict, eval_score, eval_failed_ids,
+lint_verdict, drift_status
+```
+
+### Generated in `skills.manifest.json` (tooling-computed)
+
+The manifest generator (`scripts/generate-manifest.js`) reads the authored frontmatter and emits computed fields that do not exist in the source `SKILL.md`:
+
+- `id` — derived from the skill's path relative to `skills/` (e.g. `task-execution`, or `<project>/design-review` in a multi-root workspace).
+- `path` — relative path to the `SKILL.md` file.
+- `summary` — aggregate counts (`total_skills`, `by_type`, `by_category`, `by_scope`, `by_stability`).
+- `generated_at` — ISO timestamp of when the manifest was generated.
+- `activation` — compiled block merging `triggers`, `keywords`, `paths`, `examples`, and `anti_examples` from frontmatter.
+- `health` — compiled block merging `eval_artifacts`, `eval_state`, `routing_eval`, `comprehension_state`, `eval_last_run`, `freshness`, and `drift_check`.
+
+The manifest schema is at `schemas/manifest.schema.json`. For the complete authored-to-generated field rename map and loss policy, see `docs/manifest-field-mapping.md`.
+
+### Normalized during manifest generation
+
+Some legacy scope and type values are normalized by the manifest generator to the schema-valid enum. The normalization is deterministic and logged:
+
+| Legacy value | Normalized to | Reason |
+|---|---|---|
+| `operational` (scope) | `codebase` | Operational = repo-specific |
+| `overlay` (scope) | `portable` | Overlay skills are cross-repo |
+| `generic` (scope) | `portable` | Generic = cross-repo applicable |
+| `doctrine` (type) | `capability` | A doctrine skill is a capability |
+| `domain` (type) | `capability` | Domain knowledge is a capability |
+| `framework` (type) | `workflow` | Frameworks describe workflows |
+| `feedback` (type) | `overlay` | Feedback modifies other skills |
+
+---
+
+## Migration Notes
+
+### v5 -> v6 (current)
+
+Detailed migration guide: [`migrations/v5-to-v6.md`](migrations/v5-to-v6.md).
+
+The codemod for the schema_version bump (after authoring the flat Understanding fields):
+
+```bash
+cd /Users/jacobbalslev/Development/skills
+find skills -name SKILL.md -exec sed -i '' 's/schema_version: "5"/schema_version: "6"/g' {} +
+```
+
+| What changed | v5 form | v6 form |
+|---|---|---|
+| Schema version | `schema_version: 5` | `schema_version: 6` |
+| Schema file | `schemas/skill.v5.schema.json` | `schemas/skill.v6.schema.json` (v5 schema retained for back-compat reads) |
+| Concept teaching block | nested `concept: { definition, mental_model, purpose, boundary, taxonomy, analogy, misconception }` | five flat top-level fields: `mental_model`, `purpose`, `boundary`, `analogy`, `misconception`. `definition` is covered by `description`; `taxonomy` is covered by `category` + `relations.broader`. Body `## Concept Card` section retired. |
+| Health Block | absent — audit fingerprint scattered across `eval-history.jsonl`, `routing-misses.jsonl`, `health-ledger.jsonl`, `.opencode/progress/skill-audit-*`, `findings/*.md` | seven flat top-level fields stamped by the audit loop: `last_audited`, `last_changed`, `audit_verdict`, `eval_score`, `eval_failed_ids`, `lint_verdict`, `drift_status` |
+| `comprehension_state: present` rule | required nested `concept` block | requires EITHER the five flat Understanding fields OR (for v5 back-compat) the nested `concept` block — enforced via `anyOf` clause in v6 schema's `allOf` rule |
+| Cross-domain `relations.boundary[]` | implicit "I am NOT B; defer to B" reading | codified as silent-failure risk; cross-domain entries belong in `anti_examples` + `relations.related` (see § Relations § `boundary`) |
+
+The legacy nested `concept` block remains accepted in v6 for v5 skills not yet migrated. The comprehension grader reads either location; flat fields win when both are present.
+
+### v4 -> v5 (previous)
+
+Detailed migration guide: [`migrations/v4-to-v5.md`](migrations/v4-to-v5.md).
+
+The codemod for the schema_version bump (after re-routing categories):
+
+```bash
+cd /Users/jacobbalslev/Development/skills
+find skills -name SKILL.md -exec sed -i '' 's/schema_version: "4"/schema_version: "5"/g' {} +
+```
+
+| What changed | v4 form | v5 form |
+|---|---|---|
+| Schema version | `schema_version: 4` | `schema_version: 5` |
+| Schema file | `schemas/skill.v4.schema.json` (open-ended `category` string) | `schemas/skill.v5.schema.json` (closed `category` enum of 6 values) |
+| `category` enum | open-ended string; values included `knowledge`, `frontend`, `ai-engineering`, `integration`, `integrations`, `data`, `workflow`, `security` | closed enum: `foundations` \| `engineering` \| `design` \| `quality` \| `agent` \| `product` |
+| `foundations` gate | implicit | explicit anti-junk-drawer rule: target 8–15 skills; cannot default here; must clear epistemic-precondition test |
+| `quality` framing | one of several categories | promoted to 6th category for property-as-category (a11y, perf, security, testing, type-safety, observability) per A′ Rule 2 |
+| `agent` naming | also seen as `ai-engineering` | canonical `agent` |
+| Concept-shape adoption | "social recognition" criterion | 4-condition evidence-based: scope ∈ {portable, reference} AND type = capability AND ≥2 external grounding sources AND concept block contains no repo-specific nouns |
+| Skill name policy | banned-verb-prefix lint | head-noun glossary (`docs/head-noun-glossary.md`) + `allowed_exceptions` registry (`docs/name-exceptions.yaml`) with citations |
+
+The v5 category enum was already applied across 137 live skills in skill-graph commit `210ac69` (2026-05-16). The Phase 0b sample-migration review at `skill-graph/docs/migration-sample-review.md` (2026-05-16) recorded 86.67% reviewer-agreement, passing the 85% gate.
+
+### v3 -> v4 (historical)
+
+Run the codemod to migrate in place: `node scripts/migrate-skill-v3-to-v4.js <path>`
+
+| What changed | v3 form | v4 form |
+|---|---|---|
+| Schema version | `schema_version: 3` | `schema_version: 4` |
+| Flat browse shelf | `browse_category: engineering` | `category: engineering` |
+| Hierarchical path | `category: engineering/api-design` or `category_path: engineering/api-design` | `domain: engineering/api-design` |
+| Workspace relevance tags | `project_tags: [...]` | `workspace_tags: [...]` |
+| Activation bundles | `routing_groups: [...]` | `routing_bundles: [...]` |
+
+The generated manifest keeps `skills[].project` as generated project-root ownership from `.skill-graph/config.json`. Do not author `project` in portable skill frontmatter; use `workspace_tags` for semantic relevance.
+
+### v2 -> v3 (historical)
+
+Run the codemod to migrate in place: `node scripts/migrate-skill-v2-to-v3.js <path>`
+
+| What changed | v2 form | v3 form |
+|---|---|---|
+| `drift_check` shape | scalar ISO date string | object `{ last_verified, truth_source_hashes? }` |
+| `compatibility` shape | free-text string | object `{ runtimes?, node?, notes? }` |
+| `family` field name | `family: engineering` | `browse_category: engineering` |
+| New optional fields | (none) | `category`, `project_tags`, `lifecycle`, `runtime_telemetry` |
+| Relation predicate names | `adjacent` canonical | `related` preferred; `adjacent` remains valid with lint warning. `boundary` stays canonical for routing-layer asymmetric handoff; `disjoint_with` is a separate formal OWL class-disjointness relation. |
+
+### v1 -> v2 (historical)
+
+| What changed | v1 form | v2 form |
+|---|---|---|
+| `scope` enum | `generic` / `operational` | `portable` / `codebase` |
+| Eval health | single `eval_status` field | `eval_artifacts`, `eval_state`, `routing_eval` |
+| `portability` shape | `portability.level`, `portability.exports` | `portability.readiness`, `portability.targets` |
+| Route groups | `route_groups` | `routing_groups` |
+
+### Compatibility aliases
+
+Some preferred v3.1 aliases remain accepted in v4 for compatibility: `archetype`, `reviewed_at`, `allowed_tools`, nested `eval.*`, `grounding.subject`, `grounding.claim_scope`, `compatibility.agent_runtimes`, `compatibility.node_version`, `portability.export_targets`, and `drift_check.verified_at`. When both forms are present, values must match.
+
+---
+
+## Design Constraints
+
+The contract enforces the following invariants. Any change to the schema or tooling that violates these invariants is a breaking change requiring a `schema_version` bump.
+
+1. **One file, one skill.** Each skill lives in one `SKILL.md`. No split-source format. No per-environment variants.
+2. **One manifest.** All skills aggregate into one `skills.manifest.json`. No closed/open split manifest.
+3. **No private-only fields.** Every field in the schema is part of the public contract. There are no fields reserved for specific organisations or runtime environments.
+4. **No second runtime model.** The same frontmatter shape serves local development, CI, and federated registry export. Export to plain `SKILL.md` is a transform (`scripts/export-skill.js`), not a separate authoring format.
+5. **Strict schema.** `additionalProperties: false` on both the skill and manifest schemas. Unknown fields fail lint rather than being silently ignored.
+6. **Additive evolution only within a version.** New optional fields, new enum values that extend (not replace) an existing enum, and new lint warnings are non-breaking. Renamed fields, removed fields, retyped fields, tightened required-ness, and removed enum values require a `schema_version` bump.
+7. **Migration tooling ships with every breaking change.** The v3 bump ships `scripts/migrate-skill-v2-to-v3.js`; the v4 bump ships `scripts/migrate-skill-v3-to-v4.js`. Future bumps follow the same pattern.
+
+---
+
+*See `docs/skill-metadata-protocol.md` for full design rationale, overlay composition precedence, and schema versioning policy. See `docs/field-reference.md` for one section per field with examples. See `schemas/skill.v6.schema.json` for the machine-enforceable version of this contract.*