@graphorin/skills 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @graphorin/skills
+
+## 0.1.0
+
+Initial release. See the workspace root `CHANGELOG.md` for the full
+release notes; the per-package changelog is generated by Changesets
+and tracks subsequent updates.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oleksiy Stepurenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,169 @@
+# @graphorin/skills
+
+> Skills surface for the Graphorin framework.
+
+`@graphorin/skills` ships the loader, registry, validator, and
+migration library that let a Graphorin agent consume skills written
+to the `SKILL.md` packaging format with three-tier progressive
+disclosure plus the Graphorin-specific extensions namespaced under
+the `graphorin-*` prefix.
+
+## Highlights
+
+- **Compatibility-first loader.** A skill written to the public
+  `SKILL.md` packaging format loads in Graphorin without
+  modification. Author-time fields under the `graphorin-*` prefix and
+  the spec-recommended `metadata.graphorin.*` bucket are honoured
+  through a deterministic field-resolution algorithm (Anthropic-base
+  > `metadata.graphorin.*` > `graphorin-*` legacy > caller fallback).
+- **Three-tier progressive disclosure.** Metadata (Tier 1) is parsed
+  at load time. The skill body (Tier 2) is read on first
+  `Skill.body()` call. Resources (Tier 3) are listed lazily and the
+  bytes are only read when `SkillResource.read()` is invoked.
+- **Conflict policy.** Direct collisions (Anthropic-base set + the
+  matching `graphorin-*` set) honour the operator-resolved
+  `conflictPolicy` (`'warn' | 'error' | 'silent'`); the default is
+  `'warn'`. The validator returns a typed `FrontmatterDiagnostic[]`
+  so callers can route the report to logs, audit, or CI.
+- **Spec-snapshot tracking.** A bundled
+  `anthropic-spec-snapshot.json` records the upstream fields the
+  framework recognises and the migration policy for every
+  `graphorin-*` extension. The `pnpm run check-anthropic-spec` CI
+  helper diffs the snapshot against the published specification so
+  maintainers can promote new fields with a clear changelog entry.
+- **Supply-chain aware.** Loading from `npm-package` and `git-repo`
+  sources delegates to the supply-chain helpers in
+  `@graphorin/security` so untrusted skills install with
+  `--ignore-scripts` enforced and a verifiable ed25519 signature is
+  required before the loader trusts the bytes. Local `folder`
+  installations remain trusted-by-default but inherit the same
+  validation pipeline.
+- **Slash-command activation.** `/skill:<name>` parses into a
+  structured activation request the agent runtime consumes alongside
+  the model-emitted auto-activation requests; skills that opt out via
+  `disable-model-invocation: true` are excluded from auto-activation
+  but remain reachable through the slash command.
+- **Migration library.** `migrateFrontmatter()` is idempotent and
+  dry-run by default. Re-running the migrator on an already-migrated
+  manifest returns `changed: false`.
+
+## Stable sub-paths
+
+```ts
+// Loader (folder / npm-package / git-repo / inline sources).
+import { loadSkills, loadSkillFromSource } from '@graphorin/skills/loader';
+
+// Registry (auto-activation metadata + slash-command resolver +
+// trust-level-aware tool-declaration listing).
+import { createSkillRegistry } from '@graphorin/skills/registry';
+
+// Frontmatter validator + field-resolution algorithm.
+import { validateFrontmatter, resolveSkillField } from '@graphorin/skills/frontmatter';
+
+// Idempotent migrate-frontmatter helper used by the CLI.
+import { migrateFrontmatter } from '@graphorin/skills/migration';
+
+// Activation utilities (`/skill:<name>` parser).
+import { parseSlashCommand, isSlashCommand } from '@graphorin/skills/activation';
+
+// Spec-snapshot helpers.
+import { getSpecSnapshot, getKnownField, compareAuthorSpecHint } from '@graphorin/skills/spec';
+
+// Typed errors.
+import { SkillFrontmatterConflictError, InputFilterRequiredError } from '@graphorin/skills/errors';
+```
+
+## Hello-world
+
+```ts
+import { loadSkillFromSource, createSkillRegistry } from '@graphorin/skills';
+
+const skill = await loadSkillFromSource(
+  { kind: 'folder', path: './skills/finance-helper' },
+  { conflictPolicy: 'warn', runtimeVersion: '0.5.0' },
+);
+
+const registry = createSkillRegistry();
+registry.register(skill);
+
+const metadataBlock = registry.getAutoActivationMetadata();
+// → metadata fed into the system prompt by the agent runtime (Phase 12).
+
+const activation = registry.resolveTrigger('/skill:finance-helper run-quarterly-report');
+if (activation !== null) {
+  const body = await activation.skill.body();
+  // → Tier-2 body resolved lazily on first call; cached afterwards.
+}
+```
+
+## Frontmatter cheat sheet
+
+```yaml
+---
+# === Public SKILL.md packaging format (no prefix) ===
+name: finance-helper
+description: |
+  Surface monthly P&L reports. Use when the user asks about cash
+  flow, runway, or quarterly business reports.
+license: MIT
+disable-model-invocation: false
+
+# === Graphorin extensions (namespaced) ===
+graphorin-runtime-compat: ^0.5.0
+graphorin-trust-level: trusted
+graphorin-sensitivity: internal
+graphorin-handoff-input-filter: lastUser
+graphorin-tools:
+  - name: pull_quarterly_report
+    description: Read the latest quarterly close.
+    tags: ['finance', 'reporting']
+graphorin-signature:
+  algorithm: ed25519-sha256
+  publisher: example.com
+  publishedAt: 2026-04-19T12:00:00Z
+  signature: <base64url>
+  publicKeyRef:
+    kind: well-known
+    url: https://example.com/.well-known/graphorin-skill-pubkey.pem
+---
+
+# Finance Helper
+
+The body of the SKILL.md is loaded lazily on activation.
+```
+
+## Trust levels
+
+| Source         | Default `graphorin-trust-level`         | `--ignore-scripts`         | Signature                   |
+|----------------|------------------------------------------|----------------------------|-----------------------------|
+| `folder`       | `trusted` (override `trusted-with-scripts`) | default ON; opt-in override | optional                    |
+| `npm-package`  | `untrusted` (override via `trustLevel`)  | mandatory (no override)     | mandatory                   |
+| `git-repo`     | `untrusted`                              | mandatory                   | mandatory                   |
+| `inline`       | `trusted` (test fixture)                 | n/a                         | n/a                         |
+
+The supply-chain layer enforces `--ignore-scripts` and signature
+verification through `@graphorin/security/supply-chain`. The skills
+loader does not duplicate that logic — it delegates and surfaces the
+resulting `ResolvedSkillTrustPolicy` alongside the loaded skill.
+
+## Dependencies
+
+- `yaml@^2.8.0` — required runtime dependency. Used for frontmatter
+  parsing and migrator output.
+- `@graphorin/core` — typed contracts (`ResolvedTool`, …) consumed by
+  the registry's tool-declaration surface.
+- `@graphorin/security` — supply-chain installer, ed25519 signature
+  verifier, trust-policy resolver. Skills loaded from `npm-package`
+  and `git-repo` sources go through this package.
+- `@graphorin/tools` — peer surface the agent runtime uses to
+  register skill-bundled tools after activation. The skills loader
+  does not import the runtime registry directly; it returns a typed
+  `RegisteredToolDeclaration[]` the runtime consumes.
+
+## License
+
+MIT. Copyright © 2026 Oleksiy Stepurenko.
+
+---
+
+**Project Graphorin** · v0.5.0 · MIT License · © 2026 Oleksiy Stepurenko · <https://github.com/o-stepper/graphorin>

package/anthropic-spec-snapshot.json

@@ -0,0 +1,114 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/o-stepper/graphorin/main/packages/skills/anthropic-spec-snapshot.json",
+  "snapshotDate": "2026-04-19",
+  "specSource": "https://agentskills.io/specification",
+  "specCommit": null,
+  "rationale": "Bundled snapshot of the publicly published `SKILL.md` file-format specification used to determine which frontmatter fields are recognised by the upstream loader. Updated through the `pnpm run check-anthropic-spec` CI cron whenever the published specification changes.",
+  "knownFields": {
+    "name": {
+      "since": "2025-01-01",
+      "required": true,
+      "type": "string",
+      "stability": "stable"
+    },
+    "description": {
+      "since": "2025-01-01",
+      "required": true,
+      "type": "string",
+      "stability": "stable"
+    },
+    "license": {
+      "since": "2025-06-01",
+      "required": false,
+      "type": "string",
+      "stability": "standardized"
+    },
+    "compatibility": {
+      "since": "2025-06-01",
+      "required": false,
+      "type": "string",
+      "stability": "standardized"
+    },
+    "metadata": {
+      "since": "2025-09-01",
+      "required": false,
+      "type": "object",
+      "stability": "standardized"
+    },
+    "allowed-tools": {
+      "since": "2025-12-01",
+      "required": false,
+      "type": "string-or-array",
+      "stability": "experimental"
+    },
+    "disable-model-invocation": {
+      "since": "2025-09-01",
+      "required": false,
+      "type": "boolean",
+      "stability": "stable"
+    }
+  },
+  "graphorinMapping": {
+    "graphorin-allowed-tools": {
+      "anthropicEquivalent": "allowed-tools",
+      "since": "agentskills-2025-12",
+      "policy": "deprecate-graphorin-prefix",
+      "deprecateAt": "graphorin@0.5",
+      "removeAt": "graphorin@1.0"
+    },
+    "graphorin-version": {
+      "anthropicEquivalent": "metadata.version",
+      "policy": "co-exist",
+      "rationale": "graphorin-version means runtime-compat semver range; metadata.version means skill version"
+    },
+    "graphorin-runtime-compat": {
+      "anthropicEquivalent": null,
+      "policy": "graphorin-only",
+      "rationale": "Successor naming for graphorin-version (clearer intent); both honoured during transition."
+    },
+    "graphorin-trust-level": {
+      "anthropicEquivalent": null,
+      "policy": "graphorin-only"
+    },
+    "graphorin-allowed-tools-overrides": {
+      "anthropicEquivalent": null,
+      "policy": "graphorin-only"
+    },
+    "graphorin-sandbox": {
+      "anthropicEquivalent": null,
+      "policy": "graphorin-only"
+    },
+    "graphorin-sensitivity": {
+      "anthropicEquivalent": null,
+      "policy": "graphorin-only"
+    },
+    "graphorin-sensitivity-defaults": {
+      "anthropicEquivalent": null,
+      "policy": "graphorin-only"
+    },
+    "graphorin-handoff-input-filter": {
+      "anthropicEquivalent": null,
+      "policy": "graphorin-only"
+    },
+    "graphorin-disable-model-invocation": {
+      "anthropicEquivalent": "disable-model-invocation",
+      "policy": "deprecate-graphorin-prefix",
+      "deprecateAt": "graphorin@0.5",
+      "removeAt": "graphorin@1.0"
+    },
+    "graphorin-signature": {
+      "anthropicEquivalent": null,
+      "policy": "graphorin-only"
+    },
+    "graphorin-tools": {
+      "anthropicEquivalent": null,
+      "policy": "graphorin-only"
+    },
+    "graphorin-anthropic-spec": {
+      "anthropicEquivalent": null,
+      "policy": "graphorin-only",
+      "rationale": "Author-declared snapshot date the skill was tested against."
+    }
+  }
+}

package/dist/activation/index.d.ts

@@ -0,0 +1,30 @@
+import { SlashCommandActivation } from "../types/index.js";
+
+//#region src/activation/index.d.ts
+
+/**
+ * Parse a single message body for a `/skill:<name>` invocation. The
+ * grammar accepts:
+ *
+ * ```
+ * /skill:<name>
+ * /skill:<name> <free-form-args>
+ * ```
+ *
+ * `<name>` must match `^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}$` (kebab-case
+ * conventional). Whitespace before the leading `/` is tolerated; any
+ * other prefix triggers a {@link SlashCommandParseError}.
+ *
+ * @stable
+ */
+declare function parseSlashCommand(raw: string): SlashCommandActivation;
+/**
+ * Convenience predicate. Returns `true` when {@link parseSlashCommand}
+ * would succeed against the supplied body.
+ *
+ * @stable
+ */
+declare function isSlashCommand(raw: string): boolean;
+//#endregion
+export { isSlashCommand, parseSlashCommand };
+//# sourceMappingURL=index.d.ts.map

package/dist/activation/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/activation/index.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;;;;;;iBAsCgB,iBAAA,eAAgC;;;;;;;iBA8BhC,cAAA"}

package/dist/activation/index.js

@@ -0,0 +1,71 @@
+import { SlashCommandParseError } from "../errors/index.js";
+
+//#region src/activation/index.ts
+/**
+* Activation surface for `@graphorin/skills`.
+*
+* Two activation paths are supported per DEC-206:
+*
+* 1. **Auto** — every step the agent runtime injects the metadata of
+*    every registered skill into the system prompt; the model elects
+*    a skill by invoking the synthetic `activate_skill(name)` tool.
+*    Skills with `disable-model-invocation: true` are excluded from
+*    the metadata advertisement so the model never sees them.
+* 2. **Slash command** — the user types `/skill:<name>` (optionally
+*    followed by free-form arguments) and the agent runtime activates
+*    the matched skill regardless of `disable-model-invocation`.
+*
+* The runtime owns the actual activation; this module only parses the
+* inputs into a structured payload.
+*
+* @packageDocumentation
+*/
+/**
+* Parse a single message body for a `/skill:<name>` invocation. The
+* grammar accepts:
+*
+* ```
+* /skill:<name>
+* /skill:<name> <free-form-args>
+* ```
+*
+* `<name>` must match `^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}$` (kebab-case
+* conventional). Whitespace before the leading `/` is tolerated; any
+* other prefix triggers a {@link SlashCommandParseError}.
+*
+* @stable
+*/
+function parseSlashCommand(raw) {
+	if (typeof raw !== "string" || raw.length === 0) throw new SlashCommandParseError(raw ?? "", "message body must be a non-empty string.");
+	const trimmed = raw.replace(/^\s+/u, "");
+	if (!trimmed.startsWith("/skill:")) throw new SlashCommandParseError(raw, "message must begin with '/skill:'.");
+	const remainder = trimmed.slice(7);
+	if (remainder.length === 0) throw new SlashCommandParseError(raw, "missing skill name after '/skill:'.");
+	const match = /^([A-Za-z0-9][A-Za-z0-9_.-]{0,127})(?:\s+([\s\S]*))?$/u.exec(remainder);
+	if (match === null) throw new SlashCommandParseError(raw, "skill name must match /^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}$/.");
+	const name = match[1] ?? "";
+	const args = (match[2] ?? "").trim();
+	return Object.freeze({
+		name,
+		args,
+		raw
+	});
+}
+/**
+* Convenience predicate. Returns `true` when {@link parseSlashCommand}
+* would succeed against the supplied body.
+*
+* @stable
+*/
+function isSlashCommand(raw) {
+	try {
+		parseSlashCommand(raw);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+//#endregion
+export { isSlashCommand, parseSlashCommand };
+//# sourceMappingURL=index.js.map

package/dist/activation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/activation/index.ts"],"sourcesContent":["/**\n * Activation surface for `@graphorin/skills`.\n *\n * Two activation paths are supported per DEC-206:\n *\n * 1. **Auto** — every step the agent runtime injects the metadata of\n *    every registered skill into the system prompt; the model elects\n *    a skill by invoking the synthetic `activate_skill(name)` tool.\n *    Skills with `disable-model-invocation: true` are excluded from\n *    the metadata advertisement so the model never sees them.\n * 2. **Slash command** — the user types `/skill:<name>` (optionally\n *    followed by free-form arguments) and the agent runtime activates\n *    the matched skill regardless of `disable-model-invocation`.\n *\n * The runtime owns the actual activation; this module only parses the\n * inputs into a structured payload.\n *\n * @packageDocumentation\n */\n\nimport { SlashCommandParseError } from '../errors/index.js';\nimport type { SlashCommandActivation } from '../types/index.js';\n\n/**\n * Parse a single message body for a `/skill:<name>` invocation. The\n * grammar accepts:\n *\n * ```\n * /skill:<name>\n * /skill:<name> <free-form-args>\n * ```\n *\n * `<name>` must match `^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}$` (kebab-case\n * conventional). Whitespace before the leading `/` is tolerated; any\n * other prefix triggers a {@link SlashCommandParseError}.\n *\n * @stable\n */\nexport function parseSlashCommand(raw: string): SlashCommandActivation {\n  if (typeof raw !== 'string' || raw.length === 0) {\n    throw new SlashCommandParseError(raw ?? '', 'message body must be a non-empty string.');\n  }\n  const trimmed = raw.replace(/^\\s+/u, '');\n  if (!trimmed.startsWith('/skill:')) {\n    throw new SlashCommandParseError(raw, \"message must begin with '/skill:'.\");\n  }\n  const remainder = trimmed.slice('/skill:'.length);\n  if (remainder.length === 0) {\n    throw new SlashCommandParseError(raw, \"missing skill name after '/skill:'.\");\n  }\n  const match = /^([A-Za-z0-9][A-Za-z0-9_.-]{0,127})(?:\\s+([\\s\\S]*))?$/u.exec(remainder);\n  if (match === null) {\n    throw new SlashCommandParseError(\n      raw,\n      'skill name must match /^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}$/.',\n    );\n  }\n  const name = match[1] ?? '';\n  const args = (match[2] ?? '').trim();\n  return Object.freeze({ name, args, raw });\n}\n\n/**\n * Convenience predicate. Returns `true` when {@link parseSlashCommand}\n * would succeed against the supplied body.\n *\n * @stable\n */\nexport function isSlashCommand(raw: string): boolean {\n  try {\n    parseSlashCommand(raw);\n    return true;\n  } catch {\n    return false;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsCA,SAAgB,kBAAkB,KAAqC;AACrE,KAAI,OAAO,QAAQ,YAAY,IAAI,WAAW,EAC5C,OAAM,IAAI,uBAAuB,OAAO,IAAI,2CAA2C;CAEzF,MAAM,UAAU,IAAI,QAAQ,SAAS,GAAG;AACxC,KAAI,CAAC,QAAQ,WAAW,UAAU,CAChC,OAAM,IAAI,uBAAuB,KAAK,qCAAqC;CAE7E,MAAM,YAAY,QAAQ,MAAM,EAAiB;AACjD,KAAI,UAAU,WAAW,EACvB,OAAM,IAAI,uBAAuB,KAAK,sCAAsC;CAE9E,MAAM,QAAQ,yDAAyD,KAAK,UAAU;AACtF,KAAI,UAAU,KACZ,OAAM,IAAI,uBACR,KACA,8DACD;CAEH,MAAM,OAAO,MAAM,MAAM;CACzB,MAAM,QAAQ,MAAM,MAAM,IAAI,MAAM;AACpC,QAAO,OAAO,OAAO;EAAE;EAAM;EAAM;EAAK,CAAC;;;;;;;;AAS3C,SAAgB,eAAe,KAAsB;AACnD,KAAI;AACF,oBAAkB,IAAI;AACtB,SAAO;SACD;AACN,SAAO"}

package/dist/errors/index.d.ts

@@ -0,0 +1,110 @@
+//#region src/errors/index.d.ts
+/**
+ * Typed error hierarchy for `@graphorin/skills`.
+ *
+ * Every error carries a stable lowercase `kind` discriminator so the
+ * agent runtime, the CLI, and the audit emitter can branch without
+ * resorting to `instanceof` chains, plus an optional `hint` field with
+ * an actionable remediation step (a CLI command or a documentation
+ * link).
+ *
+ * @packageDocumentation
+ */
+/** Base class for every error thrown by `@graphorin/skills`. */
+declare abstract class GraphorinSkillsError extends Error {
+  abstract readonly kind: string;
+  readonly hint?: string;
+  readonly cause?: unknown;
+  constructor(message: string, options?: {
+    hint?: string;
+    cause?: unknown;
+  });
+}
+/**
+ * The frontmatter validator detected an Anthropic-base / `graphorin-*`
+ * collision and the operator-resolved policy is `'error'`.
+ */
+declare class SkillFrontmatterConflictError extends GraphorinSkillsError {
+  readonly kind: "frontmatter:conflict";
+  readonly skillName: string;
+  readonly field: string;
+  readonly conflictingFields: ReadonlyArray<string>;
+  constructor(skillName: string, field: string, conflictingFields: ReadonlyArray<string>, options?: {
+    hint?: string;
+  });
+}
+/** A skill manifest could not be parsed (missing frontmatter / invalid YAML). */
+declare class SkillManifestParseError extends GraphorinSkillsError {
+  readonly kind: "manifest:parse";
+}
+/**
+ * The runtime-compat declaration on a skill does not satisfy the
+ * loader's installed runtime version.
+ */
+declare class SkillRuntimeCompatError extends GraphorinSkillsError {
+  readonly kind: "runtime-compat:mismatch";
+  readonly skillName: string;
+  readonly declared: string;
+  readonly installed: string;
+  constructor(skillName: string, declared: string, installed: string, options?: {
+    hint?: string;
+  });
+}
+/** A required Anthropic-base field is missing from the frontmatter. */
+declare class SkillRequiredFieldMissingError extends GraphorinSkillsError {
+  readonly kind: "frontmatter:missing-required";
+  readonly field: string;
+  constructor(field: string, options?: {
+    hint?: string;
+  });
+}
+/**
+ * `Agent.toTool()` / `handoff(...)` would be invoked inside an
+ * untrusted skill, but the skill did not declare
+ * `graphorin-handoff-input-filter`. Throwing the error at activation
+ * time prevents the runtime from materialising a sub-agent without an
+ * explicit filter.
+ */
+declare class InputFilterRequiredError extends GraphorinSkillsError {
+  readonly kind: "handoff:input-filter-required";
+  readonly skillName: string;
+  constructor(skillName: string, options?: {
+    hint?: string;
+    cause?: unknown;
+  });
+}
+/** A skill source could not be loaded from disk. */
+declare class SkillLoadError extends GraphorinSkillsError {
+  readonly kind: "load:failed";
+  readonly source: string;
+  constructor(source: string, message: string, options?: {
+    hint?: string;
+    cause?: unknown;
+  });
+}
+/** A skill name in a registry registration collided with another already-loaded skill. */
+declare class SkillNameCollisionError extends GraphorinSkillsError {
+  readonly kind: "registry:name-collision";
+  readonly skillName: string;
+  constructor(skillName: string, options?: {
+    hint?: string;
+    cause?: unknown;
+  });
+}
+/**
+ * The slash-command parser received a string that did not match the
+ * `/skill:<name>` grammar.
+ */
+declare class SlashCommandParseError extends GraphorinSkillsError {
+  readonly kind: "slash:parse";
+  readonly raw: string;
+  constructor(raw: string, message: string, options?: {
+    hint?: string;
+    cause?: unknown;
+  });
+}
+/** Convenience union — every `kind` discriminator the package may emit. */
+type GraphorinSkillsErrorKind = 'frontmatter:conflict' | 'manifest:parse' | 'runtime-compat:mismatch' | 'frontmatter:missing-required' | 'handoff:input-filter-required' | 'load:failed' | 'registry:name-collision' | 'slash:parse';
+//#endregion
+export { GraphorinSkillsError, GraphorinSkillsErrorKind, InputFilterRequiredError, SkillFrontmatterConflictError, SkillLoadError, SkillManifestParseError, SkillNameCollisionError, SkillRequiredFieldMissingError, SkillRuntimeCompatError, SlashCommandParseError };
+//# sourceMappingURL=index.d.ts.map

package/dist/errors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/errors/index.ts"],"sourcesContent":[],"mappings":";;AAaA;AAgBA;;;;;AAwBA;AAQA;AAiBA;AAgBA;AAkBA;AAUa,uBA7GS,oBAAA,SAA6B,KAAA,CA6Gc;EAkBpD,kBAAA,IAAA,EAAA,MAAuB;EAaxB,SAAA,IAAA,CAAA,EAAA,MAAA;;;;;;;;;;;cA5HC,6BAAA,SAAsC,oBAAA;;;;8BAIrB;mEAIP;;;;;cAgBV,uBAAA,SAAgC,oBAAA;;;;;;;cAQhC,uBAAA,SAAgC,oBAAA;;;;;;;;;;cAiBhC,8BAAA,SAAuC,oBAAA;;;;;;;;;;;;;;cAgBvC,wBAAA,SAAiC,oBAAA;;;;;;;;;cAkBjC,cAAA,SAAuB,oBAAA;;;;;;;;;cAUvB,uBAAA,SAAgC,oBAAA;;;;;;;;;;;;cAkBhC,sBAAA,SAA+B,oBAAA;;;;;;;;;KAahC,wBAAA"}

package/dist/errors/index.js

@@ -0,0 +1,126 @@
+//#region src/errors/index.ts
+/**
+* Typed error hierarchy for `@graphorin/skills`.
+*
+* Every error carries a stable lowercase `kind` discriminator so the
+* agent runtime, the CLI, and the audit emitter can branch without
+* resorting to `instanceof` chains, plus an optional `hint` field with
+* an actionable remediation step (a CLI command or a documentation
+* link).
+*
+* @packageDocumentation
+*/
+/** Base class for every error thrown by `@graphorin/skills`. */
+var GraphorinSkillsError = class extends Error {
+	hint;
+	cause;
+	constructor(message, options) {
+		super(message);
+		this.name = new.target.name;
+		if (options?.hint !== void 0) this.hint = options.hint;
+		if (options?.cause !== void 0) this.cause = options.cause;
+	}
+};
+/**
+* The frontmatter validator detected an Anthropic-base / `graphorin-*`
+* collision and the operator-resolved policy is `'error'`.
+*/
+var SkillFrontmatterConflictError = class extends GraphorinSkillsError {
+	kind = "frontmatter:conflict";
+	skillName;
+	field;
+	conflictingFields;
+	constructor(skillName, field, conflictingFields, options) {
+		super(`Skill '${skillName}' frontmatter conflict on '${field}' (also set: ${conflictingFields.filter((f) => f !== field).join(", ")}). Validator policy: 'error'.`, options);
+		this.skillName = skillName;
+		this.field = field;
+		this.conflictingFields = conflictingFields;
+	}
+};
+/** A skill manifest could not be parsed (missing frontmatter / invalid YAML). */
+var SkillManifestParseError = class extends GraphorinSkillsError {
+	kind = "manifest:parse";
+};
+/**
+* The runtime-compat declaration on a skill does not satisfy the
+* loader's installed runtime version.
+*/
+var SkillRuntimeCompatError = class extends GraphorinSkillsError {
+	kind = "runtime-compat:mismatch";
+	skillName;
+	declared;
+	installed;
+	constructor(skillName, declared, installed, options) {
+		super(`Skill '${skillName}' declares runtime-compat '${declared}' which does not match installed Graphorin '${installed}'.`, options);
+		this.skillName = skillName;
+		this.declared = declared;
+		this.installed = installed;
+	}
+};
+/** A required Anthropic-base field is missing from the frontmatter. */
+var SkillRequiredFieldMissingError = class extends GraphorinSkillsError {
+	kind = "frontmatter:missing-required";
+	field;
+	constructor(field, options) {
+		super(`Skill frontmatter is missing required field '${field}'.`, options);
+		this.field = field;
+	}
+};
+/**
+* `Agent.toTool()` / `handoff(...)` would be invoked inside an
+* untrusted skill, but the skill did not declare
+* `graphorin-handoff-input-filter`. Throwing the error at activation
+* time prevents the runtime from materialising a sub-agent without an
+* explicit filter.
+*/
+var InputFilterRequiredError = class extends GraphorinSkillsError {
+	kind = "handoff:input-filter-required";
+	skillName;
+	constructor(skillName, options) {
+		super(`Untrusted skill '${skillName}' uses Agent.toTool()/handoff() but did not declare 'graphorin-handoff-input-filter'.`, {
+			hint: options?.hint ?? "Add 'graphorin-handoff-input-filter: lastUser' (or another supported value) to the SKILL.md frontmatter.",
+			...options?.cause === void 0 ? {} : { cause: options.cause }
+		});
+		this.skillName = skillName;
+	}
+};
+/** A skill source could not be loaded from disk. */
+var SkillLoadError = class extends GraphorinSkillsError {
+	kind = "load:failed";
+	source;
+	constructor(source, message, options) {
+		super(`Skill load failed (source='${source}'): ${message}`, options);
+		this.source = source;
+	}
+};
+/** A skill name in a registry registration collided with another already-loaded skill. */
+var SkillNameCollisionError = class extends GraphorinSkillsError {
+	kind = "registry:name-collision";
+	skillName;
+	constructor(skillName, options) {
+		super(`Skill '${skillName}' is already registered.`, {
+			hint: options?.hint ?? "Either rename one of the colliding skills or call `registry.unregister(name)` before re-registering.",
+			...options?.cause === void 0 ? {} : { cause: options.cause }
+		});
+		this.skillName = skillName;
+	}
+};
+/**
+* The slash-command parser received a string that did not match the
+* `/skill:<name>` grammar.
+*/
+var SlashCommandParseError = class extends GraphorinSkillsError {
+	kind = "slash:parse";
+	raw;
+	constructor(raw, message, options) {
+		super(`Slash command '${raw}': ${message}`, {
+			hint: options?.hint ?? "Use `/skill:<name>` to activate a registered skill.",
+			...options?.cause === void 0 ? {} : { cause: options.cause }
+		});
+		this.raw = raw;
+	}
+};
+
+//#endregion
+export { GraphorinSkillsError, InputFilterRequiredError, SkillFrontmatterConflictError, SkillLoadError, SkillManifestParseError, SkillNameCollisionError, SkillRequiredFieldMissingError, SkillRuntimeCompatError, SlashCommandParseError };
+//# sourceMappingURL=index.js.map