@skill-map/spec 0.7.0 → 0.8.0

package/conformance/fixtures/minimal-claude/skills/hello.md

@@ -1,22 +0,0 @@
----
-name: hello-skill
-description: A minimal skill that greets the user by name.
-metadata:
-  version: 1.0.0
-  stability: stable
-  author: conformance
-  tags: [example, greeting]
----
-
-# Hello skill
-
-This skill does one thing: it greets the user.
-
-## Recipe
-
-1. Ask the user's name.
-2. Respond with "Hello, <name>".
-
-## Preconditions
-
-- None.

package/conformance/fixtures/orphan-after/skills/keep.md

@@ -1,13 +0,0 @@
----
-name: orphan-keep
-description: Fixture node that survives across before/after, so the after-state still has at least one node.
-metadata:
-  version: 1.0.0
-  stability: stable
-  author: conformance
----
-
-# Survivor
-
-Keeps the after-state graph non-empty so we can assert that the orphan
-issue is the only one emitted.

package/conformance/fixtures/orphan-before/skills/keep.md

@@ -1,13 +0,0 @@
----
-name: orphan-keep
-description: Fixture node that survives across before/after, so the after-state still has at least one node.
-metadata:
-  version: 1.0.0
-  stability: stable
-  author: conformance
----
-
-# Survivor
-
-Keeps the after-state graph non-empty so we can assert that the orphan
-issue is the only one emitted.

package/conformance/fixtures/orphan-before/skills/lonely.md

@@ -1,13 +0,0 @@
----
-name: orphan-lonely
-description: Fixture node that gets deleted in the after-state to trigger the orphan path.
-metadata:
-  version: 1.0.0
-  stability: stable
-  author: conformance
----
-
-# Orphan lonely body
-
-This file disappears in `orphan-after`. With no replacement matching
-its hashes, the rename heuristic emits an `orphan` issue.

package/conformance/fixtures/rename-high-after/skills/bar.md

@@ -1,14 +0,0 @@
----
-name: rename-high-foo
-description: Fixture node for the high-confidence rename conformance case.
-metadata:
-  version: 1.0.0
-  stability: stable
-  author: conformance
----
-
-# Rename high body
-
-Body content kept identical between the before and after fixtures so
-the body hash matches across the rename. Move it to `bar.md` to trigger
-a high-confidence auto-rename.

package/conformance/fixtures/rename-high-before/skills/foo.md

@@ -1,14 +0,0 @@
----
-name: rename-high-foo
-description: Fixture node for the high-confidence rename conformance case.
-metadata:
-  version: 1.0.0
-  stability: stable
-  author: conformance
----
-
-# Rename high body
-
-Body content kept identical between the before and after fixtures so
-the body hash matches across the rename. Move it to `bar.md` to trigger
-a high-confidence auto-rename.

package/schemas/extensions/adapter.schema.json

@@ -1,40 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://skill-map.dev/spec/v0/extensions/adapter.schema.json",
-  "title": "ExtensionAdapter",
-  "description": "Manifest shape for an `Adapter` extension. An adapter recognizes a platform (Claude Code, Codex, Gemini, Obsidian vault, generic MD) and classifies each candidate file into a node `kind`. Exactly zero or one adapter MUST match any given file; multiple matches → the kernel emits an issue `adapter-ambiguous` and the file is left unclassified. Adapters are deterministic-only — they sit at the filesystem boundary and run during boot; probabilistic classification would make boot slow, costly, and non-reproducible. The `mode` field MUST NOT appear in adapter manifests. If you need LLM-assisted classification, write a probabilistic Detector that emits classification hints as `Link[]`. Stability: stable as of spec v1.0.0 except where noted.",
-  "allOf": [
-    { "$ref": "base.schema.json" }
-  ],
-  "type": "object",
-  "required": ["id", "kind", "version", "emits", "defaultRefreshAction"],
-  "unevaluatedProperties": false,
-  "properties": {
-    "kind": { "const": "adapter" },
-    "emits": {
-      "type": "array",
-      "description": "Node kinds this adapter may classify files into.",
-      "minItems": 1,
-      "items": {
-        "type": "string",
-        "enum": ["skill", "agent", "command", "hook", "note"]
-      }
-    },
-    "roots": {
-      "type": "array",
-      "description": "Path globs (relative to scope root) that this adapter SHOULD be consulted for. Advisory — the kernel walks all roots and consults every adapter regardless, but this field lets `sm doctor` warn when no file matched a specific adapter (i.e. the adapter was loaded for a platform that isn't in this scope).",
-      "items": { "type": "string" }
-    },
-    "defaultRefreshAction": {
-      "type": "object",
-      "description": "Map from node `kind` to the action id the UI's probabilistic-refresh surface (`🧠 prob`) submits for that kind. MUST cover every kind listed in `emits`. Referenced action ids MUST resolve at load time; a dangling reference disables the adapter with status `invalid-manifest`.",
-      "propertyNames": {
-        "enum": ["skill", "agent", "command", "hook", "note"]
-      },
-      "additionalProperties": {
-        "type": "string",
-        "pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$"
-      }
-    }
-  }
-}

package/schemas/extensions/audit.schema.json

@@ -1,47 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://skill-map.dev/spec/v0/extensions/audit.schema.json",
-  "title": "ExtensionAudit",
-  "description": "Manifest shape for an `Audit` extension. An audit is a hardcoded workflow that composes rules and actions into a single report. The audit's execution mode is NOT declared in the manifest — it is **derived** from the modes of the primitives it composes: if every composed primitive is `deterministic`, the audit's effective mode is `deterministic` and runs synchronously inside `sm audit <id>`; if any composed primitive is `probabilistic`, the audit's effective mode is `probabilistic` and dispatches as a queued job (`sm job submit audit:<id>`). Declaring `mode` in the manifest is a load-time error. See `architecture.md` §Execution modes for the full derivation contract.",
-  "allOf": [
-    { "$ref": "base.schema.json" }
-  ],
-  "type": "object",
-  "required": ["id", "kind", "version", "composes", "reportSchemaRef"],
-  "unevaluatedProperties": false,
-  "properties": {
-    "kind": { "const": "audit" },
-    "composes": {
-      "type": "array",
-      "description": "Ordered list of rule and action references the audit executes in sequence. The kernel resolves each reference in the registry at load time; a dangling reference (id not found, kind mismatch, or primitive disabled) disables the audit with status `invalid-manifest`. Each composed primitive's `mode` participates in the audit's mode derivation.",
-      "minItems": 1,
-      "items": {
-        "type": "object",
-        "required": ["kind", "id"],
-        "unevaluatedProperties": false,
-        "properties": {
-          "kind": { "type": "string", "enum": ["rule", "action"] },
-          "id": { "type": "string" },
-          "failFast": {
-            "type": "boolean",
-            "default": false,
-            "description": "If true, the audit stops at the first error-severity issue this step emits. Default: collect everything and continue."
-          }
-        }
-      }
-    },
-    "reportSchemaRef": {
-      "type": "string",
-      "description": "Reference to the JSON Schema of the audit's report shape. Probabilistic audits MUST extend `report-base.schema.json` (carries `safety` / `confidence` per the report-base contract). Deterministic audits MAY extend it but are not required to."
-    },
-    "exitCodeMap": {
-      "type": "object",
-      "description": "How the audit report maps to CLI exit codes. Absent → standard behaviour: exit 0 on pass, 1 on any error-severity issue, 2 on operational error.",
-      "unevaluatedProperties": false,
-      "properties": {
-        "pass": { "type": "integer", "default": 0 },
-        "fail": { "type": "integer", "default": 1 }
-      }
-    }
-  }
-}

package/schemas/extensions/detector.schema.json

@@ -1,41 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://skill-map.dev/spec/v0/extensions/detector.schema.json",
-  "title": "ExtensionDetector",
-  "description": "Manifest shape for a `Detector` extension. A detector consumes a parsed node (frontmatter + body) and emits `Link[]` pointing to other nodes or to external URLs (the latter only if it is the designated URL-counter detector). Detectors run in isolation: they MUST NOT read other nodes, the graph, or the DB. Cross-node reasoning lives in Rules. Detectors are dual-mode: `deterministic` detectors run synchronously inside `sm scan`; `probabilistic` detectors invoke an LLM through the kernel's `RunnerPort` and execute only as queued jobs (never during scan). See `architecture.md` §Execution modes for the full contract.",
-  "allOf": [
-    { "$ref": "base.schema.json" }
-  ],
-  "type": "object",
-  "required": ["id", "kind", "version", "emitsLinkKinds", "defaultConfidence"],
-  "unevaluatedProperties": false,
-  "properties": {
-    "kind": { "const": "detector" },
-    "mode": {
-      "type": "string",
-      "enum": ["deterministic", "probabilistic"],
-      "default": "deterministic",
-      "description": "`deterministic` (default): pure code, runs synchronously during `sm scan`. Same input → same output, every run. `probabilistic`: invokes an LLM via `ctx.runner` and runs only as a queued job (`sm job submit detector:<id>`); never participates in `sm scan`. The kernel rejects probabilistic detectors that try to register scan-time hooks at load time. Omitting the field is equivalent to declaring `deterministic`."
-    },
-    "emitsLinkKinds": {
-      "type": "array",
-      "description": "Subset of `Link.kind` values this detector is allowed to emit. Emitting an unlisted kind at runtime → kernel rejects the link and logs `detector-kind-violation`.",
-      "minItems": 1,
-      "items": {
-        "type": "string",
-        "enum": ["invokes", "references", "mentions", "supersedes"]
-      }
-    },
-    "defaultConfidence": {
-      "type": "string",
-      "enum": ["high", "medium", "low"],
-      "description": "Confidence attached to emitted links by default. Detectors MAY override per-link at emission time."
-    },
-    "scope": {
-      "type": "string",
-      "enum": ["frontmatter", "body", "both"],
-      "default": "both",
-      "description": "Which part of the node this detector consumes. The kernel passes only the declared scope to the detector — a `frontmatter` detector that tries to read `body` receives an empty string."
-    }
-  }
-}

package/schemas/extensions/renderer.schema.json

@@ -1,29 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://skill-map.dev/spec/v0/extensions/renderer.schema.json",
-  "title": "ExtensionRenderer",
-  "description": "Manifest shape for a `Renderer` extension. A renderer serializes the graph (or a filtered subgraph) into a string in a declared format. Renderers are invoked by `sm graph --format <format>` and `sm export`. Renderers are deterministic-only — they sit at the graph-to-string boundary and their output MUST be byte-deterministic for the same input graph (the snapshot-test suite relies on this). The `mode` field MUST NOT appear in renderer manifests. Probabilistic narrators of the graph are a valid product but they live in jobs and emit Findings, not in renderers.",
-  "allOf": [
-    { "$ref": "base.schema.json" }
-  ],
-  "type": "object",
-  "required": ["id", "kind", "version", "format"],
-  "unevaluatedProperties": false,
-  "properties": {
-    "kind": { "const": "renderer" },
-    "format": {
-      "type": "string",
-      "description": "Format identifier consumed by `--format`. Built-in set: `ascii`, `mermaid`, `dot`, `json`. Third-party renderers MAY register new format ids; collisions are a load-time error."
-    },
-    "contentType": {
-      "type": "string",
-      "description": "MIME-like hint used by the Server when streaming rendered output over HTTP (e.g. `text/plain`, `image/svg+xml`, `application/json`). Advisory.",
-      "default": "text/plain"
-    },
-    "supportsFilter": {
-      "type": "boolean",
-      "default": true,
-      "description": "If true, the renderer accepts the `--filter` expression used by `sm export`. If false, `sm export --format <this>` rejects `--filter` with exit 2."
-    }
-  }
-}

package/schemas/frontmatter/agent.schema.json

@@ -1,17 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://skill-map.dev/spec/v0/frontmatter/agent.schema.json",
-  "title": "FrontmatterAgent",
-  "description": "Frontmatter shape for nodes classified as `agent`. Extends `base.schema.json`. Kind-specific field: `model`. The `tools` and `allowedTools` fields live on `base` and apply here unchanged (see `base.schema.json`). Color, when needed, lives in `metadata.color` (inherited from base).",
-  "allOf": [
-    { "$ref": "base.schema.json" }
-  ],
-  "type": "object",
-  "additionalProperties": true,
-  "properties": {
-    "model": {
-      "type": "string",
-      "description": "Model identifier for this agent (e.g. `sonnet`, `opus`, `haiku`, or a full `claude-*` id). Free-form string; adapters MAY validate against a platform-specific enum."
-    }
-  }
-}

package/schemas/frontmatter/command.schema.json

@@ -1,39 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://skill-map.dev/spec/v0/frontmatter/command.schema.json",
-  "title": "FrontmatterCommand",
-  "description": "Frontmatter shape for nodes classified as `command`. Extends `base.schema.json`. Kind-specific fields: `args`, `shortcut`.",
-  "allOf": [
-    { "$ref": "base.schema.json" }
-  ],
-  "type": "object",
-  "additionalProperties": true,
-  "properties": {
-    "args": {
-      "type": "array",
-      "description": "Declared positional / named arguments for this command.",
-      "items": { "$ref": "#/$defs/CommandArg" }
-    },
-    "shortcut": {
-      "type": "string",
-      "description": "Keyboard shortcut hint. Platform-specific notation (e.g. `cmd+shift+k`, `ctrl+alt+m`). Purely advisory."
-    }
-  },
-  "$defs": {
-    "CommandArg": {
-      "type": "object",
-      "required": ["name"],
-      "additionalProperties": true,
-      "properties": {
-        "name": { "type": "string", "minLength": 1 },
-        "type": {
-          "type": "string",
-          "description": "Free-form type hint (e.g. `string`, `integer`, `path`, `boolean`, `enum:a|b|c`)."
-        },
-        "required": { "type": "boolean", "default": false },
-        "description": { "type": "string" },
-        "default": { "description": "Any JSON value." }
-      }
-    }
-  }
-}

package/schemas/frontmatter/hook.schema.json

@@ -1,29 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://skill-map.dev/spec/v0/frontmatter/hook.schema.json",
-  "title": "FrontmatterHook",
-  "description": "Frontmatter shape for nodes classified as `hook`. Extends `base.schema.json`. Kind-specific fields: `event`, `condition`, `blocking`, `idempotent`.",
-  "allOf": [
-    { "$ref": "base.schema.json" }
-  ],
-  "type": "object",
-  "additionalProperties": true,
-  "properties": {
-    "event": {
-      "type": "string",
-      "description": "Event name this hook reacts to (e.g. `PreToolUse`, `PostToolUse`, `SubagentStop`, `SessionStart`). Platform-specific enum; adapters MAY validate."
-    },
-    "condition": {
-      "type": "string",
-      "description": "Free-form predicate expression evaluated by the host. Syntax is platform-specific; the spec does not constrain it."
-    },
-    "blocking": {
-      "type": "boolean",
-      "description": "When true, the host MUST wait for the hook to finish before proceeding. When false, the hook runs fire-and-forget."
-    },
-    "idempotent": {
-      "type": "boolean",
-      "description": "Author-declared: executing twice with the same inputs produces the same result. Consumed by runners for retry and dedup."
-    }
-  }
-}

package/schemas/frontmatter/note.schema.json

@@ -1,11 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://skill-map.dev/spec/v0/frontmatter/note.schema.json",
-  "title": "FrontmatterNote",
-  "description": "Frontmatter shape for nodes classified as `note`. Extends `base.schema.json` with no additional fields. Exists so that every kind has a matching schema for uniform routing.",
-  "allOf": [
-    { "$ref": "base.schema.json" }
-  ],
-  "type": "object",
-  "additionalProperties": true
-}

package/schemas/frontmatter/skill.schema.json

@@ -1,37 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://skill-map.dev/spec/v0/frontmatter/skill.schema.json",
-  "title": "FrontmatterSkill",
-  "description": "Frontmatter shape for nodes classified as `skill`. Extends `base.schema.json`. Kind-specific fields: `inputs`, `outputs`. Stability: experimental — the parameter shape may tighten once summarizer needs emerge.",
-  "allOf": [
-    { "$ref": "base.schema.json" }
-  ],
-  "type": "object",
-  "additionalProperties": true,
-  "properties": {
-    "inputs": {
-      "type": "array",
-      "description": "Declared inputs for this skill. Optional structured. Stability: experimental.",
-      "items": { "$ref": "#/$defs/Parameter" }
-    },
-    "outputs": {
-      "type": "array",
-      "description": "Declared outputs. Optional structured. Stability: experimental.",
-      "items": { "$ref": "#/$defs/Parameter" }
-    }
-  },
-  "$defs": {
-    "Parameter": {
-      "type": "object",
-      "required": ["name"],
-      "additionalProperties": true,
-      "properties": {
-        "name": { "type": "string", "minLength": 1 },
-        "type": { "type": "string", "description": "Free-form type hint (e.g. `string`, `integer`, `path`, `glob`)." },
-        "description": { "type": "string" },
-        "required": { "type": "boolean", "default": false },
-        "default": { "description": "Any JSON value, or a templated string." }
-      }
-    }
-  }
-}