@skill-graph/cli 0.5.6

package/schemas/skill.v3.schema.json

@@ -0,0 +1,827 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://skillgraph.dev/schemas/skill.v3.schema.json",
+  "title": "Skill Graph Skill Frontmatter (v3, pinned)",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "name",
+    "description",
+    "version",
+    "type",
+    "browse_category",
+    "scope",
+    "owner",
+    "freshness",
+    "drift_check",
+    "eval_artifacts",
+    "eval_state",
+    "routing_eval"
+  ],
+  "properties": {
+    "schema_version": {
+      "oneOf": [
+        {
+          "type": "integer",
+          "const": 3
+        },
+        {
+          "type": "string",
+          "const": "3"
+        }
+      ],
+      "description": "Major contract shape version. Integer for v3+; string '3' tolerated for back-compat with hand-rolled YAML. Bumps when shape changes break consumers (additive minor changes do not bump). v4 is the next breaking-change horizon — see CHANGELOG.md and docs/skill-metadata-protocol.md § Schema Versioning Policy."
+    },
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9-/:]*$",
+      "description": "Stable display-layer skill identifier. Lowercase kebab-case; allows `/` and `:` for hierarchical/namespaced names. Must equal the parent directory name (skills/<name>/SKILL.md). The URN at `urn` is the long-term globally-unique identifier; `name` is the local handle."
+    },
+    "urn": {
+      "type": "string",
+      "pattern": "^urn:skill:[a-z0-9][a-z0-9-]*:[a-z0-9][a-z0-9-/:]*$",
+      "description": "Optional globally-unique persistent identifier in the `urn:skill:<repo>:<skill-name>` form (RFC 8141). Consumers treat the URN as the stable identity across repos and federated registries; `name` is the display-layer handle. The `<skill-name>` segment MUST equal the `name` field."
+    },
+    "description": {
+      "type": "string",
+      "description": "The routing contract: tells a router whether this skill should activate for a given query. Pushy, specific, boundary-aware. Should include an explicit negative boundary so the router does not over-activate. No protocol length cap."
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
+      "description": "Skill content version (semver). Bumps when the SKILL.md body or contract changes meaningfully. Distinct from `schema_version` (the contract shape). Used by `relations.depends_on` for `min_version` constraints."
+    },
+    "type": {
+      "type": "string",
+      "enum": [
+        "capability",
+        "workflow",
+        "router",
+        "overlay"
+      ],
+      "description": "Archetype classifier — what kind of skill this is. `capability` (knows how to do something), `workflow` (orchestrates a sequence), `router` (dispatches to other skills), `overlay` (specialises a parent via `extends`). `archetype` is the v3.1 preferred alias and becomes canonical in v4."
+    },
+    "archetype": {
+      "type": "string",
+      "enum": [
+        "capability",
+        "workflow",
+        "router",
+        "overlay"
+      ],
+      "description": "Archetype classifier (v3.1 preferred alias for `type`). When both are present they must match. Becomes canonical in v4."
+    },
+    "browse_category": {
+      "type": "string",
+      "description": "Flat human browse bucket (e.g., knowledge, engineering, quality). For hierarchical taxonomy use `category` instead."
+    },
+    "category": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9-]*(/[a-z0-9][a-z0-9-]*)*$",
+      "description": "Hierarchical browse path using slash-delimited segments (e.g., `ecommerce/integrations/shopify`). Complements `browse_category`; flat vs tree answer different questions. `category_path` is the v3.1 preferred alias and becomes canonical in v4."
+    },
+    "category_path": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9-]*(/[a-z0-9][a-z0-9-]*)*$",
+      "description": "Hierarchical browse path (v3.1 preferred alias for `category`). Slash-delimited segments. Becomes canonical in v4."
+    },
+    "scope": {
+      "type": "string",
+      "enum": [
+        "codebase",
+        "reference",
+        "portable"
+      ],
+      "description": "Where this skill applies. `codebase` — coupled to a specific repo's code/conventions; `reference` — pure knowledge (no repo coupling); `portable` — repo-agnostic patterns. Drives multi-project overlay decisions and informs the router's project-fit check."
+    },
+    "owner": {
+      "type": "string",
+      "description": "Maintainer or team accountable for keeping this skill correct. Free-form string; conventional values: `skill-graph-maintainer`, GitHub team handles, individual usernames. Used by drift-check workflows to route review requests."
+    },
+    "freshness": {
+      "type": "string",
+      "format": "date",
+      "description": "ISO date (YYYY-MM-DD) of the last meaningful content review. The author's claim that the skill was current as of this date. Complemented by `drift_check.truth_source_hashes` for grounded skills. `reviewed_at` is the v3.1 preferred alias and becomes canonical in v4."
+    },
+    "reviewed_at": {
+      "type": "string",
+      "format": "date",
+      "description": "ISO date (YYYY-MM-DD) of the last meaningful content review (v3.1 preferred alias for `freshness`). When both are present they must match. Becomes canonical in v4."
+    },
+    "drift_check": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "last_verified"
+      ],
+      "properties": {
+        "last_verified": {
+          "type": "string",
+          "format": "date",
+          "description": "ISO date of the last verification against truth sources. Authored claim. `verified_at` is the v3.1 preferred alias and becomes canonical in v4."
+        },
+        "verified_at": {
+          "type": "string",
+          "format": "date",
+          "description": "ISO date of the last verification against truth sources (v3.1 preferred alias for `last_verified`). When both are present they must match. Becomes canonical in v4."
+        },
+        "truth_source_hashes": {
+          "type": "object",
+          "description": "Map of normalized truth source key to 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. Evidence that complements the `last_verified` claim. Computed by `node scripts/skill-graph-drift.js --record --apply <skill-path>`.",
+          "additionalProperties": {
+            "type": "string",
+            "pattern": "^[a-f0-9]{64}$"
+          }
+        }
+      },
+      "description": "Drift-detection record for grounded skills. `last_verified` is the author's claim; `truth_source_hashes` is content-addressable evidence keyed by each normalized `grounding.truth_sources` entry. Whole-file sources hash normalized file content; line-range sources hash only the cited slice; anchor-only sources hash the resolved Markdown section or literal text. The combination lets `scripts/skill-graph-drift.js` detect when underlying truth has changed without an accompanying review."
+    },
+    "eval_artifacts": {
+      "type": "string",
+      "enum": [
+        "none",
+        "planned",
+        "present"
+      ],
+      "description": "Are eval artifacts present on disk for this skill? `none` (no evals planned), `planned` (eval intent declared but not yet shipped), `present` (eval JSON exists at `evals/<skill>.json` or similar). Lint enforces the `present` claim by requiring a real file. The `planned` state has a staleness guard — see lint check 6."
+    },
+    "eval_state": {
+      "type": "string",
+      "enum": [
+        "unverified",
+        "passing",
+        "monitored"
+      ],
+      "description": "What does the eval say about content quality? `unverified` (no eval has run), `passing` (last run passed), `monitored` (eval runs on a cadence and is currently passing). Independent of `routing_eval` (the routing-coverage axis). Use to express content-level quality grading orthogonal to routing coverage."
+    },
+    "routing_eval": {
+      "type": "string",
+      "enum": [
+        "absent",
+        "present"
+      ],
+      "description": "Is routing / trigger coverage explicitly evaluated? `absent` (router behaviour is not part of the eval set), `present` (the skill's `examples[]` and `anti_examples[]` pass `scripts/skill-graph-routing-eval.js`). When `present`, lint check 12 requires the harness to agree. Honesty over green checkmarks — flip to `present` only after the harness PASSes. The nested `eval.routing_coverage` is the v3.1 preferred alias."
+    },
+    "comprehension_state": {
+      "type": "string",
+      "enum": [
+        "absent",
+        "present"
+      ],
+      "description": "Does this skill carry a comprehension eval (typically `evals/comprehension.json`) and a `concept` block authored for the 7-dimension comprehension grader? `absent` (no comprehension grading), `present` (comprehension evals exist; the `concept` block is required by the allOf rule). Optional in v3 — omitted means `absent`. Independent of `routing_eval` (router-level) and `eval_state` (content-level). The nested `eval.comprehension_state` is the v3.1 preferred alias."
+    },
+    "concept": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "definition",
+        "mental_model",
+        "purpose",
+        "boundary",
+        "taxonomy",
+        "analogy",
+        "misconception"
+      ],
+      "properties": {
+        "definition": {
+          "type": "string",
+          "description": "What the concept IS. Primary category + what it does + who uses it. A domain outsider should understand. Author as deeply as the concept requires — there is no protocol length cap. Graded by the comprehension grader's `definition` dimension (weight 1.0)."
+        },
+        "mental_model": {
+          "type": "string",
+          "description": "Primitives and their relationships. Name primitives and the relationships between them. Markdown permitted inside the string. Author with the depth the concept needs — there is no protocol length cap. Graded by the comprehension grader's `mental_model` dimension (weight 1.5)."
+        },
+        "purpose": {
+          "type": "string",
+          "description": "What problem the concept solves and the alternative it replaced. Concrete pain point + prior alternative. No protocol length cap — explain as fully as the concept needs. Graded by the comprehension grader's `purpose` dimension (weight 1.0)."
+        },
+        "boundary": {
+          "type": "string",
+          "description": "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. No protocol length cap. Graded by the comprehension grader's `boundary` dimension (weight 1.5)."
+        },
+        "taxonomy": {
+          "type": "string",
+          "description": "Nearby concepts with their relationship type (subset / alternative / prerequisite / composition / specialization). Markdown list permitted inside the string. No protocol length cap. Graded by the comprehension grader's `taxonomy` dimension (weight 1.0)."
+        },
+        "analogy": {
+          "type": "string",
+          "description": "Analogy that preserves the core mechanism. Translate for a non-expert without breaking the structural relationship between primitives. No protocol length cap. Graded by the comprehension grader's `analogy` dimension (weight 0.5)."
+        },
+        "misconception": {
+          "type": "string",
+          "description": "The wrong mental model people bring and why it misleads. Authored hint to inoculate the agent against the common error trap. No protocol length cap. Not directly graded; complements `boundary`."
+        }
+      },
+      "description": "Seven-field universal-subject concept teaching block. Read by the comprehension grader (`scripts/skill/evaluate-skill.js --comprehension`) and rendered into the agent context when the skill is loaded. Required when `comprehension_state: present`. No protocol length cap — author each field as deeply as the concept requires. Distinct from `## Philosophy` in the body, which is about *why this skill file exists in this repo*; the `concept` block is about *what the subject is, universally*."
+    },
+    "eval_last_run": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Optional receipt for the most recent eval run. Complements `eval_state` so `passing` and `monitored` claims can point at evidence instead of remaining self-attested.",
+      "required": [
+        "at",
+        "status"
+      ],
+      "properties": {
+        "at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Timestamp for the eval run that supports the current eval_state claim."
+        },
+        "status": {
+          "type": "string",
+          "enum": [
+            "pass",
+            "fail",
+            "mixed"
+          ]
+        },
+        "runner": {
+          "type": "string",
+          "description": "Eval runner or command used, e.g. `scripts/skill-audit.js --graded`."
+        },
+        "model": {
+          "type": "string",
+          "description": "Optional grader/model identifier when an LLM grader was used."
+        },
+        "receipt": {
+          "type": "string",
+          "description": "Path or URL to the eval receipt, scorecard, grader history, or CI run."
+        },
+        "receipt_hash": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$",
+          "description": "Optional SHA-256 digest of the receipt artifact."
+        }
+      }
+    },
+    "eval": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Nested eval-health record (v3.1 preferred alias for the sibling triple `eval_artifacts` / `eval_state` / `routing_eval`). When both the top-level and nested forms are present they must match. Becomes canonical in v4.",
+      "properties": {
+        "artifacts": {
+          "type": "string",
+          "enum": [
+            "none",
+            "planned",
+            "present"
+          ],
+          "description": "Are eval artifacts present on disk for this skill? Mirrors top-level `eval_artifacts`."
+        },
+        "content_state": {
+          "type": "string",
+          "enum": [
+            "unverified",
+            "passing",
+            "monitored"
+          ],
+          "description": "What does the eval say about content quality? Mirrors top-level `eval_state`. Renamed to `content_state` here to disambiguate from `routing_coverage`."
+        },
+        "routing_coverage": {
+          "type": "string",
+          "enum": [
+            "absent",
+            "present"
+          ],
+          "description": "Is routing / trigger coverage explicitly evaluated? Mirrors top-level `routing_eval`. Renamed to `routing_coverage` here to remove the head-first compound ambiguity."
+        },
+        "comprehension_state": {
+          "type": "string",
+          "enum": [
+            "absent",
+            "present"
+          ],
+          "description": "Mirrors top-level `comprehension_state`. When `present`, the `concept` block is required by the allOf rule."
+        }
+      }
+    },
+    "stability": {
+      "type": "string",
+      "enum": [
+        "experimental",
+        "stable",
+        "frozen",
+        "deprecated"
+      ],
+      "description": "Lifecycle posture for consumers. `experimental` (subject to change), `stable` (production-ready), `frozen` (no further changes expected), `deprecated` (use `superseded_by` to name the replacement). Drives consumer pinning decisions."
+    },
+    "superseded_by": {
+      "type": "string",
+      "description": "Name of the skill that replaces this one. Required when `stability: deprecated` — enforced by the allOf rule so every deprecated skill names its successor and consumers can follow the chain automatically. Omit on non-deprecated skills."
+    },
+    "license": {
+      "type": "string",
+      "description": "SPDX license identifier (e.g., `MIT`, `Apache-2.0`, `CC-BY-4.0`). Resolved against the SPDX license list (ISO/IEC 5962:2021). Required for skills shipped externally; optional for codebase-internal skills."
+    },
+    "compatibility": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "runtimes": {
+          "type": "array",
+          "description": "Target agent runtimes with optional version constraints (e.g., `claude-code>=2.0`, `cursor>=0.40`). `agent_runtimes` is the v3.1 preferred alias and becomes canonical in v4.",
+          "items": {
+            "type": "string"
+          }
+        },
+        "agent_runtimes": {
+          "type": "array",
+          "description": "Target agent runtimes (v3.1 preferred alias for `runtimes`). Disambiguates from Node runtime, container runtime, etc. When both are present they must match. Becomes canonical in v4.",
+          "items": {
+            "type": "string"
+          }
+        },
+        "node": {
+          "type": "string",
+          "description": "Node.js version constraint (e.g., `>=18`). `node_version` is the v3.1 preferred alias and becomes canonical in v4."
+        },
+        "node_version": {
+          "type": "string",
+          "description": "Node.js version constraint (v3.1 preferred alias for `node`). Disambiguates from `node` reading as graph-node in a graph repo. When both are present they must match. Becomes canonical in v4."
+        },
+        "notes": {
+          "type": "string",
+          "description": "Free-text additional compatibility notes. Use sparingly; prefer structured fields. No protocol length cap."
+        }
+      },
+      "description": "Cross-runtime compatibility envelope. `runtimes` lists target agent runtimes with version constraints; `node` is the Node.js version requirement; `notes` is free-text overflow. Distinct from `extends` (overlay parent) and `relations.depends_on` (sibling skill dependency)."
+    },
+    "allowed-tools": {
+      "type": "string",
+      "description": "Optional space-separated whitelist of tools the skill is permitted to use (e.g., `Read Edit Bash`). Honoured by harnesses that gate tool calls per skill. Kebab-case spelling matches the common SKILL.md field name and Claude Code's `--allowed-tools` CLI flag. `allowed_tools` (snake_case) is the v3.1 preferred protocol alias; the export transform writes the kebab-case form for SKILL.md consumers."
+    },
+    "allowed_tools": {
+      "type": "string",
+      "description": "Space-separated whitelist of tools (v3.1 preferred snake_case alias for `allowed-tools`). When both are present they must match. The SKILL.md export transform rewrites this to the kebab-case form. Becomes canonical in v4."
+    },
+    "extends": {
+      "type": "string",
+      "description": "Overlay parent skill name. Only valid when `type: overlay`. The overlay specialises the parent and ceases to have meaning without it; its identity is INHERITED from the parent, not REPLACED. For non-existential cross-skill generalisation, use `relations.broader` instead."
+    },
+    "triggers": {
+      "type": "array",
+      "description": "Exact phrase or label triggers that activate this skill. For semantic phrases use `keywords`; for example user prompts use `examples`.",
+      "items": {
+        "type": "string"
+      }
+    },
+    "keywords": {
+      "type": "array",
+      "description": "Semantic keywords for discovery and fuzzy matching. Complements `triggers` (exact) and `examples` (full prompts).",
+      "items": {
+        "type": "string"
+      }
+    },
+    "examples": {
+      "type": "array",
+      "description": "Positive-class activation examples — realistic user prompts the skill SHOULD activate for. 2–5 entries recommended. Improves recall for embedding-based routers (SkillRouter-style few-shot retrieval) that find `keywords` alone insufficient at library scale. Groups under `activation.examples` in the manifest.",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "anti_examples": {
+      "type": "array",
+      "description": "Negative-class activation examples — realistic user prompts that look topically related but a DIFFERENT skill should handle. Used as hard-negative training signal. Pair with `relations.boundary` to name the skill that should activate instead. Groups under `activation.anti_examples` in the manifest.",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "paths": {
+      "type": "array",
+      "description": "Glob patterns that identify code surfaces this skill governs. Patterns prefixed with `!` are negations (gitignore-style). Negations only subtract from prior includes; a pattern list consisting only of negations matches nothing and is rejected by lint.",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "project_tags": {
+      "type": "array",
+      "description": "Literal project handles or semantic tags identifying which projects this skill is relevant to. Absent = ambient / cross-project. A workspace config at `.skill-graph/config.json` may map literal project handles to semantic tag sets so one skill tag matches many projects.",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z0-9][a-z0-9-]*$"
+      }
+    },
+    "routing_groups": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Tags that group skills for activation routing (e.g., `frontend`, `data-pipeline`). Routers use these for batch retrieval — when a query matches a routing group, all skills tagged with that group become candidates. Distinct from `browse_category` (single-value human bucket) and `category` (hierarchical taxonomy path)."
+    },
+    "relations": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Typed edges to sibling skills. Lint verifies every target exists. Predicate-to-W3C-vocabulary mapping is provided via schemas/skill.context.jsonld (JSON-LD @context). `boundary` is routing-layer asymmetric handoff; `disjoint_with` is the optional OWL class-disjointness predicate — they are distinct, not aliases.",
+      "properties": {
+        "adjacent": {
+          "type": "array",
+          "description": "DEPRECATED ALIAS of `related`. Symmetric co-read relation, maps to skos:related. Still valid in v3.x; lint emits a soft warning pointing at `related` as the preferred name. Removal target: v4.",
+          "items": {
+            "type": "string"
+          }
+        },
+        "related": {
+          "type": "array",
+          "description": "Symmetric associative relation (skos:related). Use for skills that should be co-read because they teach the same surface from different angles. Max 5 entries recommended to avoid hub-and-spoke clutter. Preferred over the deprecated `adjacent` alias.",
+          "items": {
+            "type": "string"
+          }
+        },
+        "boundary": {
+          "type": "array",
+          "description": "Anti-ownership / routing handoff edge — directional. Skills this skill explicitly does NOT own; the router uses this to redirect wrong-skill queries to the correct owner. Items may be bare skill names or `{skill, reason}` objects; reasons are strongly recommended. Maps to sg:disjointOwnership — a Skill-Graph-specific routing-layer predicate, intentionally weaker than OWL class-disjointness. For formal class-disjointness, use `disjoint_with`.",
+          "items": {
+            "oneOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "skill"
+                ],
+                "properties": {
+                  "skill": {
+                    "type": "string"
+                  },
+                  "reason": {
+                    "type": "string"
+                  }
+                }
+              }
+            ]
+          }
+        },
+        "disjoint_with": {
+          "type": "array",
+          "description": "Optional OWL class-disjointness assertion. Maps to owl:disjointWith — a formal ontological claim that the two skills name disjoint conceptual classes (no entity can simultaneously be an instance of both). Rare in practice. Does NOT replace `boundary` (the routing-layer asymmetric handoff). Same item shape as `boundary` — bare string OR `{skill, reason}`.",
+          "items": {
+            "oneOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "skill"
+                ],
+                "properties": {
+                  "skill": {
+                    "type": "string"
+                  },
+                  "reason": {
+                    "type": "string"
+                  }
+                }
+              }
+            ]
+          }
+        },
+        "broader": {
+          "type": "array",
+          "description": "Cross-skill generalisation (skos:broader). Use when this skill is a specialisation of another skill that is NOT its overlay parent (if it were, use `extends`). Example: `react-best-practices` has `broader: [frontend]`. Closes the cross-skill generalisation gap that `browse_category` cannot express.",
+          "items": {
+            "type": "string"
+          }
+        },
+        "narrower": {
+          "type": "array",
+          "description": "Cross-skill specialisation (skos:narrower). The inverse of `broader` — this skill is more general than the targets. Tooling can infer this from other skills' `broader` edges; authoring it explicitly is optional.",
+          "items": {
+            "type": "string"
+          }
+        },
+        "verify_with": {
+          "type": "array",
+          "description": "Skills to co-load for verification. Maps to prov:wasInformedBy — this skill's claims are informed by the verifier's claims. Keep to 1-3 high-signal verifiers.",
+          "items": {
+            "type": "string"
+          }
+        },
+        "depends_on": {
+          "type": "array",
+          "description": "Skills this skill requires conceptually or operationally. Items may be bare skill names or `{skill, min_version}` objects for version-constrained dependencies.",
+          "items": {
+            "oneOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "skill"
+                ],
+                "properties": {
+                  "skill": {
+                    "type": "string"
+                  },
+                  "min_version": {
+                    "type": "string",
+                    "description": "Semver range for the minimum required version of the target skill. Accepts bare semver (`1.2.0`, treated as exact), caret range (`^1.2.0`), tilde range (`~1.2.0`), comparator range (`>=1.2.0`, `>1.2.0`, `<2.0.0`, `<=1.5.0`), or AND-joined ranges (`>=1.2.0 <2.0.0`).",
+                    "pattern": "^(\\^|~|>=|<=|>|<|=)?[0-9]+\\.[0-9]+\\.[0-9]+(-[a-zA-Z0-9.-]+)?( +(\\^|~|>=|<=|>|<|=)?[0-9]+\\.[0-9]+\\.[0-9]+(-[a-zA-Z0-9.-]+)?)*$"
+                  }
+                }
+              }
+            ]
+          }
+        }
+      }
+    },
+    "grounding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "domain_object",
+        "grounding_mode",
+        "truth_sources",
+        "failure_modes",
+        "evidence_priority"
+      ],
+      "properties": {
+        "domain_object": {
+          "type": "string",
+          "description": "What the skill is about (e.g., `Shopify order sync`). `subject` is the v3.1 preferred alias and becomes canonical in v4."
+        },
+        "subject": {
+          "type": "string",
+          "description": "What the skill is about (v3.1 preferred alias for `domain_object`). When both are present they must match. Becomes canonical in v4."
+        },
+        "grounding_mode": {
+          "type": "string",
+          "enum": [
+            "repo_specific",
+            "universal",
+            "hybrid"
+          ],
+          "description": "Whether the skill's claims are repo-specific, universal, or a hybrid. `claim_scope` is the v3.1 preferred alias and becomes canonical in v4."
+        },
+        "claim_scope": {
+          "type": "string",
+          "enum": [
+            "repo_specific",
+            "universal",
+            "hybrid"
+          ],
+          "description": "Whether the skill's claims are repo-specific, universal, or a hybrid (v3.1 preferred alias for `grounding_mode`). When both are present they must match. Becomes canonical in v4."
+        },
+        "truth_sources": {
+          "type": "array",
+          "items": {
+            "oneOf": [
+              {
+                "type": "string",
+                "description": "Legacy whole-resource reference. Local paths are resolved relative to the repo root; URLs are allowed for external specs."
+              },
+              {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "path"
+                ],
+                "properties": {
+                  "path": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "Local file path or URL for the truth source."
+                  },
+                  "line_range": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": [
+                      "start"
+                    ],
+                    "properties": {
+                      "start": {
+                        "type": "integer",
+                        "minimum": 1
+                      },
+                      "end": {
+                        "type": "integer",
+                        "minimum": 1
+                      }
+                    },
+                    "description": "Optional inclusive line range to hash and review instead of the whole file."
+                  },
+                  "anchor": {
+                    "type": "string",
+                    "description": "Optional stable heading slug or literal text anchor used by lint to detect broken pointers."
+                  },
+                  "note": {
+                    "type": "string",
+                    "description": "Short human note explaining why this source grounds the skill."
+                  }
+                }
+              }
+            ]
+          },
+          "description": "Files, docs, or URLs that ground the skill's claims. Prefer object entries with path plus line_range or anchor for repo-backed skills; string entries remain valid for v3 compatibility."
+        },
+        "failure_modes": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "evidence_priority": {
+          "type": "string",
+          "enum": [
+            "repo_code_first",
+            "general_knowledge_first",
+            "equal"
+          ]
+        }
+      },
+      "description": "Records what the skill is grounded against — the truth sources, the grounding mode, and the failure modes when the truth drifts. Required when the skill makes claims about specific code or external systems. Optional for purely conceptual skills."
+    },
+    "portability": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "readiness",
+        "targets"
+      ],
+      "properties": {
+        "readiness": {
+          "type": "string",
+          "enum": [
+            "declared",
+            "scripted",
+            "verified"
+          ]
+        },
+        "targets": {
+          "type": "array",
+          "description": "Supported export destinations. `export_targets` is the v3.1 preferred alias and becomes canonical in v4.",
+          "items": {
+            "type": "string",
+            "enum": [
+              "skill-md"
+            ]
+          }
+        },
+        "export_targets": {
+          "type": "array",
+          "description": "Supported export destinations (v3.1 preferred alias for `targets`). Distinguishes from bare `targets` which is generic. When both are present they must match. Becomes canonical in v4.",
+          "items": {
+            "type": "string",
+            "enum": [
+              "skill-md"
+            ]
+          }
+        }
+      },
+      "description": "Portability execution signal. `readiness` declares whether portability is only declared (`declared`), covered by export tooling (`scripted`), or verified with a target-runtime receipt (`verified`). `targets` lists supported export destinations, currently `skill-md`."
+    },
+    "lifecycle": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Per-skill maintenance policy consumed by the drift sentinel.",
+      "properties": {
+        "stale_after_days": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Days after `drift_check.last_verified` at which the skill is flagged stale. Integration skills rot faster than pure concept skills; pick per skill."
+        },
+        "review_cadence": {
+          "type": "string",
+          "enum": [
+            "per-commit",
+            "weekly",
+            "quarterly",
+            "on-truth-source-change"
+          ],
+          "description": "How frequently the skill should be re-verified. Drives scheduled drift checks."
+        }
+      }
+    },
+    "runtime_telemetry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "feedback_source"
+      ],
+      "description": "Optional pointer to a real-world success/failure feed. Consumers may use telemetry to corroborate or override `eval_state`.",
+      "properties": {
+        "feedback_source": {
+          "type": "string",
+          "description": "Path or URL to a JSONL of run receipts. Each receipt is expected to carry `{ timestamp, skill, outcome }` at minimum."
+        },
+        "last_updated": {
+          "type": "string",
+          "format": "date"
+        },
+        "metrics": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "sample_size": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "success_rate": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1
+            }
+          }
+        }
+      }
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "type": {
+            "const": "overlay"
+          }
+        }
+      },
+      "then": {
+        "required": [
+          "extends"
+        ]
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "scope": {
+            "const": "codebase"
+          }
+        },
+        "required": [
+          "scope"
+        ]
+      },
+      "then": {
+        "required": [
+          "grounding"
+        ]
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "type": {
+            "not": {
+              "const": "overlay"
+            }
+          }
+        },
+        "required": [
+          "type"
+        ]
+      },
+      "then": {
+        "not": {
+          "required": [
+            "extends"
+          ]
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "stability": {
+            "const": "deprecated"
+          }
+        },
+        "required": [
+          "stability"
+        ]
+      },
+      "then": {
+        "required": [
+          "superseded_by"
+        ]
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "comprehension_state": {
+            "const": "present"
+          }
+        },
+        "required": [
+          "comprehension_state"
+        ]
+      },
+      "then": {
+        "required": [
+          "concept"
+        ]
+      }
+    }
+  ]
+}