skill-map spec

Vendor-neutral specification for mapping, inspecting, and managing collections of interrelated markdown files — skills, agents, commands, hooks, and notes.

Top-level schemas

• execution-record.schema.json ExecutionRecord

  A single row in the execution history (`state_executions`). One record per action or audit invocation — regardless of whether the runner was CLI, Skill, or in-process.

• issue.schema.json Issue

  Deterministic finding emitted by a rule when evaluating the graph. Not to be confused with `Finding`, which is probabilistic (LLM-produced).

• job.schema.json Job

  Row in `state_jobs`. Non-terminal state until it reaches `completed` or `failed`, at which point an `ExecutionRecord` is also written.

• link.schema.json Link

  Directed relation between two nodes, produced by one or more detectors during a scan.

• node.schema.json Node

  A single markdown file in the graph (skill, agent, command, hook, note). Identified by its relative path from the scope root.

• plugins-registry.schema.json PluginsRegistry

  Two shapes in one file: (1) the per-plugin manifest that authors ship as `plugin.json` (see `$defs/PluginManifest`); (2) the aggregate registry the implementation produces on disk (e.g. `~/.skill-map/plugins.json`), which lists all discovered plugins with their compat status. Both shapes are normative. camelCase keys throughout.

• project-config.schema.json ProjectConfig

  Shape of `.skill-map.json` at the project root. All fields optional; defaults apply when absent. camelCase keys throughout — consistent with the rest of the spec.

• report-base.schema.json ReportBase

  Base shape for any probabilistic report produced by an LLM-backed action (summarizers, `sm what`, `sm cluster-triggers`, etc.). All per-kind summary schemas under `summaries/` extend this. Kernel validates the `confidence` and `safety` fields regardless of action-specific extensions.

• scan-result.schema.json ScanResult

  Canonical output of `sm scan --json` (and the data shape sent over WebSocket scan events). Self-describing and versioned; consumers MUST check `schemaVersion` before parsing.

Frontmatter schemas

• frontmatter/agent.schema.json FrontmatterAgent

  Frontmatter shape for nodes classified as `agent`. Extends `base.schema.json`. Kind-specific fields: `model`, `tools`. Color, when needed, lives in `metadata.color` (inherited from base).

• frontmatter/base.schema.json FrontmatterBase

  Base shape of the YAML frontmatter block on every node, across all kinds. Kind-specific schemas (`skill`, `agent`, `command`, `hook`, `note`) extend this via `allOf`. camelCase keys throughout. `additionalProperties` is intentionally permissive; the deterministic `unknown-field` rule emits warnings for keys outside the catalog so that the JSON Schema remains shape-only and policy lives in rules.

• frontmatter/command.schema.json FrontmatterCommand

  Frontmatter shape for nodes classified as `command`. Extends `base.schema.json`. Kind-specific fields: `args`, `shortcut`.

• frontmatter/hook.schema.json FrontmatterHook

  Frontmatter shape for nodes classified as `hook`. Extends `base.schema.json`. Kind-specific fields: `event`, `condition`, `blocking`, `idempotent`.

• frontmatter/note.schema.json FrontmatterNote

  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.

• frontmatter/skill.schema.json FrontmatterSkill

  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.

Summary schemas

• summaries/agent.schema.json SummaryAgent

  Report produced by `agent-summarizer` for a single `agent` node. Extends `report-base.schema.json`. Stability: experimental.

• summaries/command.schema.json SummaryCommand

  Report produced by `command-summarizer` for a single `command` node. Extends `report-base.schema.json`. Stability: experimental.

• summaries/hook.schema.json SummaryHook

  Report produced by `hook-summarizer` for a single `hook` node. Extends `report-base.schema.json`. Stability: experimental.

• summaries/note.schema.json SummaryNote

  Report produced by `note-summarizer` for a single `note` node. Extends `report-base.schema.json`. Stability: experimental.

• summaries/skill.schema.json SummarySkill

  Report produced by `skill-summarizer` for a single `skill` node. Extends `report-base.schema.json`. Stability: experimental — field set may tighten as real summarizer output stabilizes.

Prose contracts

Rendered on GitHub. The spec on this site is the schemas; the prose below is what they enforce.

• README.md README

  Overview of the spec and what it defines.

• versioning.md Versioning

  Evolution policy, stability tags, deprecation window.

• CHANGELOG.md Changelog

  Normative history of spec changes.

• architecture.md Architecture

  Hexagonal ports & adapters, 6 extension kinds.

• cli-contract.md CLI contract

  Verbs, flags, exit codes, JSON introspection.

• dispatch-lifecycle.md Dispatch lifecycle

  Job state machine, atomic claim, TTL, reap.

• job-events.md Job events

  Canonical event stream emitted during execution.

• prompt-preamble.md Prompt preamble

  Verbatim injection-mitigation text prepended to every job.

• db-schema.md DB schema

  Zoned table catalog, naming conventions, migrations.

• plugin-kv-api.md Plugin KV API

  ctx.store contract for mode A + mode B dedicated rules.

• interfaces/security-scanner.md Security scanner interface

  Convention for third-party security scanners.