@graphorin/skills 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @graphorin/skills
 
+## 0.7.0
+
+### Minor Changes
+
+- [#154](https://github.com/o-stepper/graphorin/pull/154) [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04) Thanks [@o-stepper](https://github.com/o-stepper)! - W-072: every export map's `import` condition becomes `default`, and the Node floor rises to `>=22.12.0`.
+
+  CJS consumers previously hit a bewildering `ERR_PACKAGE_PATH_NOT_EXPORTED` instead of a clear ESM-only signal. With the `default` condition, plain `require('@graphorin/core')` works via Node's stable `require(esm)` - which shipped in 22.12, hence the engines bump across every workspace manifest (packages, examples, benchmarks, docs; enforced by the widened mvp-readiness sweep). No dual-instance hazard: there is no CJS build, `require()` returns the same ESM module instance. ESM consumers are unaffected (`default` serves both paths; `types` stays first). The pack gate now runs attw under the full `node16` profile (was `esm-only`) and adds a runtime `require(esm)` smoke against the packed tarballs. Installs on Node 22.0-22.11 with `engine-strict` will refuse - upgrade Node (see the migration guide).
+
+### Patch Changes
+
+- [#162](https://github.com/o-stepper/graphorin/pull/162) [`73b19ca`](https://github.com/o-stepper/graphorin/commit/73b19caeda388bda628a48138cb7d70b1db839a3) Thanks [@o-stepper](https://github.com/o-stepper)! - Remove phantom workspace dependencies that no source file imports: agent no longer depends on provider and observability, mcp/workflow/server no longer depend on observability, sessions no longer depends on security (and its memory edge moves to devDependencies where the single test import lives), skills no longer depends on tools. Dead tsdown `external` entries for the removed edges are gone too, so a future import can no longer build as external without a declared dependency. Consumer install graphs shrink accordingly; a new repo-wide `check-phantom-deps` CI gate keeps the manifest graph honest from here on.
+
+- [#164](https://github.com/o-stepper/graphorin/pull/164) [`764239b`](https://github.com/o-stepper/graphorin/commit/764239b97e0e0202442e91272583f13adeb12d00) Thanks [@o-stepper](https://github.com/o-stepper)! - Tarballs now ship `src/` so the published `dist/**/*.d.ts.map` files actually work (W-136): the maps referenced `../src/*.ts` that the `files` whitelist excluded, so go-to-definition fell back into `.d.ts` and the shipped maps were dead weight. The pack gate gains a `map-integrity` leg: every source referenced by a shipped map must resolve inside the tarball (or be embedded via `sourcesContent`), with an anti-vacuous guard - a package whose tsdown config emits declaration maps must contain a non-zero number of `.d.ts.map` files, so a cache-restored dist that silently dropped maps fails the gate instead of passing vacuously. `mvp-readiness` now requires `src` in every publishable `files` array.
+
+- [#164](https://github.com/o-stepper/graphorin/pull/164) [`764239b`](https://github.com/o-stepper/graphorin/commit/764239b97e0e0202442e91272583f13adeb12d00) Thanks [@o-stepper](https://github.com/o-stepper)! - Every published package now declares its tree-shaking contract via `sideEffects` (W-137): 18 packages audited to a pure module scope get `false`, the CLI declares its bin entry (`["./dist/bin/*"]`), and `@graphorin/security` gets an explicit `true` - its secrets subsystem registers built-in resolvers and the SecretValue caller-context provider at import time, so marking it pure would let bundlers drop those registrations. `mvp-readiness` now fails any publishable manifest without a declared `sideEffects`, closing the drift for future packages.
+
+- Updated dependencies [[`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`832f22e`](https://github.com/o-stepper/graphorin/commit/832f22e570b8c3175c1adeb4c150070cbd131534), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`832f22e`](https://github.com/o-stepper/graphorin/commit/832f22e570b8c3175c1adeb4c150070cbd131534), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`32bbd03`](https://github.com/o-stepper/graphorin/commit/32bbd03b588136a355e4b5ad6ac5e19b36b4d8ab), [`32bbd03`](https://github.com/o-stepper/graphorin/commit/32bbd03b588136a355e4b5ad6ac5e19b36b4d8ab), [`32bbd03`](https://github.com/o-stepper/graphorin/commit/32bbd03b588136a355e4b5ad6ac5e19b36b4d8ab), [`4ee256e`](https://github.com/o-stepper/graphorin/commit/4ee256e30fe9190cef6c48dc6785464757707156), [`4ee256e`](https://github.com/o-stepper/graphorin/commit/4ee256e30fe9190cef6c48dc6785464757707156), [`4ee256e`](https://github.com/o-stepper/graphorin/commit/4ee256e30fe9190cef6c48dc6785464757707156), [`4ee256e`](https://github.com/o-stepper/graphorin/commit/4ee256e30fe9190cef6c48dc6785464757707156), [`32bbd03`](https://github.com/o-stepper/graphorin/commit/32bbd03b588136a355e4b5ad6ac5e19b36b4d8ab), [`32bbd03`](https://github.com/o-stepper/graphorin/commit/32bbd03b588136a355e4b5ad6ac5e19b36b4d8ab), [`764239b`](https://github.com/o-stepper/graphorin/commit/764239b97e0e0202442e91272583f13adeb12d00), [`764239b`](https://github.com/o-stepper/graphorin/commit/764239b97e0e0202442e91272583f13adeb12d00), [`764239b`](https://github.com/o-stepper/graphorin/commit/764239b97e0e0202442e91272583f13adeb12d00), [`764239b`](https://github.com/o-stepper/graphorin/commit/764239b97e0e0202442e91272583f13adeb12d00), [`764239b`](https://github.com/o-stepper/graphorin/commit/764239b97e0e0202442e91272583f13adeb12d00), [`764239b`](https://github.com/o-stepper/graphorin/commit/764239b97e0e0202442e91272583f13adeb12d00), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04)]:
+  - @graphorin/core@0.7.0
+  - @graphorin/security@0.7.0
+
+## 0.6.1
+
+### Patch Changes
+
+- [#142](https://github.com/o-stepper/graphorin/pull/142) [`436d6ca`](https://github.com/o-stepper/graphorin/commit/436d6ca5ebbd16df094e915682d3915c279a8430) Thanks [@o-stepper](https://github.com/o-stepper)! - Version constants and version-bearing strings now derive from each package's manifest at build time (`VERSION = pkg.version`; writer ids, client/server info, OTLP framework attributes, build-info metrics interpolate it). No behavioral change at the current version: the rendered strings are byte-identical. A release bump no longer edits source; the new `check-version-consistency` gate fails any reintroduced hardcoded framework version.
+
+- Updated dependencies [[`436d6ca`](https://github.com/o-stepper/graphorin/commit/436d6ca5ebbd16df094e915682d3915c279a8430)]:
+  - @graphorin/core@0.6.1
+  - @graphorin/security@0.6.1
+  - @graphorin/tools@0.6.1
+
 ## 0.6.0
 
 ### Patch Changes

package/README.md

@@ -82,7 +82,7 @@ import { loadSkillFromSource, createSkillRegistry } from '@graphorin/skills';
 
 const skill = await loadSkillFromSource(
   { kind: 'folder', path: './skills/finance-helper' },
-  { conflictPolicy: 'warn', runtimeVersion: '0.6.0' },
+  { conflictPolicy: 'warn', runtimeVersion: '0.7.0' },
 );
 
 const registry = createSkillRegistry();
@@ -111,7 +111,7 @@ license: MIT
 disable-model-invocation: false
 
 # === Graphorin extensions (namespaced) ===
-graphorin-runtime-compat: ^0.6.0
+graphorin-runtime-compat: ^0.7.0
 graphorin-trust-level: trusted
 graphorin-sensitivity: internal
 graphorin-handoff-input-filter: lastUser
@@ -168,4 +168,4 @@ MIT. Copyright © 2026 Oleksiy Stepurenko.
 
 ---
 
-**Project Graphorin** · v0.6.0 · MIT License · © 2026 Oleksiy Stepurenko · <https://github.com/o-stepper/graphorin>
+**Project Graphorin** · v0.7.0 · MIT License · © 2026 Oleksiy Stepurenko · <https://github.com/o-stepper/graphorin>

package/dist/index.d.ts

@@ -45,8 +45,7 @@ import { FieldStability, GraphorinFieldPolicy, GraphorinMappingEntry, KnownField
  *
  * @packageDocumentation
  */
-/** Canonical version constant. Mirrors the `package.json` version. */
-declare const VERSION = "0.6.0";
+declare const VERSION: string;
 //#endregion
 export { ActivatedSkill, ActivationRequest, FieldResolution, FieldStability, FrontmatterDiagnostic, FrontmatterValidatorPolicy, GraphorinFieldPolicy, GraphorinMappingEntry, GraphorinSkillsError, GraphorinSkillsErrorKind, HandoffInputFilterDeclaration, HandoffInputFilterStep, InlineSkill, InlineSkillTool, InputFilterRequiredError, KnownFieldEntry, LoadSkillOptions, LoadSkillsOptions, MigrateFrontmatterOptions, MigrationResult, MigrationRewrite, ParsedActivationTrigger, RegisteredToolDeclaration, ResolvedSkillTrustPolicy, Skill, SkillFrontmatterConflictError, SkillLoadError, SkillManifestParseError, SkillMetadata, SkillNameCollisionError, SkillRegistry, SkillRegistryOptions, SkillRequiredFieldMissingError, SkillResource, SkillRuntimeCompatError, SkillSignatureVerificationResult, SkillSource, SkillToolDeclaration, SkillToolStamper, SkillTrustLevel, SkillTrustLevelValue, SkillsTrustLevel, SlashCommandActivation, SlashCommandParseError, SpecSnapshot, SplitSkillMd, StampedSkillTool, SupplyChainSkillSource, UnknownFieldPolicy, VERSION, ValidateFrontmatterOptions, ValidatedFrontmatter, _setSpecSnapshotForTesting, compareAuthorSpecHint, createSkillRegistry, getGraphorinMapping, getKnownField, getSpecSnapshot, isRuntimeCompatSatisfied, isSlashCommand, loadSkillFromSource, loadSkills, migrateFrontmatter, parseActivationTrigger, parseAllowedToolsValue, parseFrontmatterYaml, parseHandoffInputFilter, parseSlashCommand, parseToolsField, requireHandoffInputFilter, resolveSkillField, sortKeysAnthropicFirst, splitSkillMd, stampSkillTool, stampSkillToolFromMetadata, validateFrontmatter };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAqCA;;;;;;;;;;;;;;;;;;;;;;;;;cAAa,OAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAuCA;;;;;;;;;;;;;;;;;;;;;;;;cAAa"}

package/dist/index.js

@@ -1,3 +1,4 @@
+import { version } from "./package.js";
 import { GraphorinSkillsError, InputFilterRequiredError, SkillFrontmatterConflictError, SkillLoadError, SkillManifestParseError, SkillNameCollisionError, SkillRequiredFieldMissingError, SkillRuntimeCompatError, SlashCommandParseError } from "./errors/index.js";
 import { isSlashCommand, parseSlashCommand } from "./activation/index.js";
 import { _setSpecSnapshotForTesting, compareAuthorSpecHint, getGraphorinMapping, getKnownField, getSpecSnapshot } from "./spec/index.js";
@@ -43,8 +44,8 @@ import { createSkillRegistry, parseActivationTrigger } from "./registry/index.js
 *
 * @packageDocumentation
 */
-/** Canonical version constant. Mirrors the `package.json` version. */
-const VERSION = "0.6.0";
+/** Canonical version constant, derived from `package.json` at build time. */
+const VERSION = version;
 
 //#endregion
 export { GraphorinSkillsError, InputFilterRequiredError, SkillFrontmatterConflictError, SkillLoadError, SkillManifestParseError, SkillNameCollisionError, SkillRequiredFieldMissingError, SkillRuntimeCompatError, SlashCommandParseError, VERSION, _setSpecSnapshotForTesting, compareAuthorSpecHint, createSkillRegistry, getGraphorinMapping, getKnownField, getSpecSnapshot, isRuntimeCompatSatisfied, isSlashCommand, loadSkillFromSource, loadSkills, migrateFrontmatter, parseActivationTrigger, parseAllowedToolsValue, parseFrontmatterYaml, parseHandoffInputFilter, parseSlashCommand, parseToolsField, requireHandoffInputFilter, resolveSkillField, sortKeysAnthropicFirst, splitSkillMd, stampSkillTool, stampSkillToolFromMetadata, validateFrontmatter };

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * `@graphorin/skills` - skills surface for the Graphorin framework.\n *\n * The package owns:\n *\n * - `SKILL.md` loader with three-tier progressive disclosure\n *   (metadata always available; body and resources lazy-loaded).\n * - Frontmatter validator implementing the field-resolution\n *   algorithm and conflict policy from ADR-043.\n * - Bundled snapshot of the publicly published `SKILL.md` packaging-\n *   format specification + the framework-specific extension\n *   catalogue.\n * - Slash-command parser (`/skill:<name>`) + auto-activation\n *   metadata generator.\n * - `SkillRegistry` with name-collision detection, activation\n *   resolution, and a typed tool-declaration surface the agent\n *   runtime bridges into the `@graphorin/tools` registry.\n * - Idempotent `migrateFrontmatter` library that rewrites legacy\n *   `graphorin-*` fields onto their upstream equivalents per the\n *   bundled mapping table.\n *\n * Stable sub-paths:\n *\n * ```ts\n * import { loadSkills, loadSkillFromSource } from '@graphorin/skills/loader';\n * import { createSkillRegistry } from '@graphorin/skills/registry';\n * import { validateFrontmatter, resolveSkillField } from '@graphorin/skills/frontmatter';\n * import { migrateFrontmatter } from '@graphorin/skills/migration';\n * import { parseSlashCommand } from '@graphorin/skills/activation';\n * import { getSpecSnapshot, getKnownField } from '@graphorin/skills/spec';\n * import { SkillFrontmatterConflictError } from '@graphorin/skills/errors';\n * ```\n *\n * @packageDocumentation\n */\n\n/** Canonical version constant. Mirrors the `package.json` version. */\nexport const VERSION = '0.6.0';\n\nexport * from './activation/index.js';\nexport * from './errors/index.js';\nexport * from './frontmatter/index.js';\nexport * from './loader/index.js';\nexport * from './migration/index.js';\nexport * from './registry/index.js';\nexport * from './spec/index.js';\nexport * from './types/index.js';\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCA,MAAa,UAAU"}
+{"version":3,"file":"index.js","names":["VERSION: string","pkg.version"],"sources":["../src/index.ts"],"sourcesContent":["/**\n * `@graphorin/skills` - skills surface for the Graphorin framework.\n *\n * The package owns:\n *\n * - `SKILL.md` loader with three-tier progressive disclosure\n *   (metadata always available; body and resources lazy-loaded).\n * - Frontmatter validator implementing the field-resolution\n *   algorithm and conflict policy from ADR-043.\n * - Bundled snapshot of the publicly published `SKILL.md` packaging-\n *   format specification + the framework-specific extension\n *   catalogue.\n * - Slash-command parser (`/skill:<name>`) + auto-activation\n *   metadata generator.\n * - `SkillRegistry` with name-collision detection, activation\n *   resolution, and a typed tool-declaration surface the agent\n *   runtime bridges into the `@graphorin/tools` registry.\n * - Idempotent `migrateFrontmatter` library that rewrites legacy\n *   `graphorin-*` fields onto their upstream equivalents per the\n *   bundled mapping table.\n *\n * Stable sub-paths:\n *\n * ```ts\n * import { loadSkills, loadSkillFromSource } from '@graphorin/skills/loader';\n * import { createSkillRegistry } from '@graphorin/skills/registry';\n * import { validateFrontmatter, resolveSkillField } from '@graphorin/skills/frontmatter';\n * import { migrateFrontmatter } from '@graphorin/skills/migration';\n * import { parseSlashCommand } from '@graphorin/skills/activation';\n * import { getSpecSnapshot, getKnownField } from '@graphorin/skills/spec';\n * import { SkillFrontmatterConflictError } from '@graphorin/skills/errors';\n * ```\n *\n * @packageDocumentation\n */\n\n/** Canonical version constant, derived from `package.json` at build time. */\nimport pkg from '../package.json' with { type: 'json' };\n\nexport const VERSION: string = pkg.version;\n\nexport * from './activation/index.js';\nexport * from './errors/index.js';\nexport * from './frontmatter/index.js';\nexport * from './loader/index.js';\nexport * from './migration/index.js';\nexport * from './registry/index.js';\nexport * from './spec/index.js';\nexport * from './types/index.js';\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCA,MAAaA,UAAkBC"}

package/dist/package.js

@@ -0,0 +1,6 @@
+//#region package.json
+var version = "0.7.0";
+
+//#endregion
+export { version };
+//# sourceMappingURL=package.js.map

package/dist/package.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package.js","names":[],"sources":["../package.json"],"sourcesContent":["{\n  \"name\": \"@graphorin/skills\",\n  \"version\": \"0.7.0\",\n  \"description\": \"Skills surface for the Graphorin framework: loader for the SKILL.md packaging format with three-tier progressive disclosure (metadata / body / resources), frontmatter validator implementing the field-resolution algorithm and conflict policy from ADR-043, registry with auto-activation + slash-command activation, supply-chain hardening (signature verification + `--ignore-scripts` enforcement via @graphorin/security), sandbox-tier propagation for untrusted skills, handoff input-filter declaration recognition, and idempotent migrate-frontmatter library.\",\n  \"license\": \"MIT\",\n  \"author\": \"Oleksiy Stepurenko\",\n  \"homepage\": \"https://github.com/o-stepper/graphorin/tree/main/packages/skills\",\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"git+https://github.com/o-stepper/graphorin.git\",\n    \"directory\": \"packages/skills\"\n  },\n  \"bugs\": {\n    \"url\": \"https://github.com/o-stepper/graphorin/issues\"\n  },\n  \"keywords\": [\n    \"graphorin\",\n    \"ai\",\n    \"agents\",\n    \"framework\",\n    \"skills\",\n    \"skill-loader\",\n    \"skill-registry\",\n    \"frontmatter\",\n    \"yaml\",\n    \"progressive-disclosure\",\n    \"supply-chain\",\n    \"sandbox\",\n    \"ed25519\",\n    \"signature-verification\",\n    \"migration\"\n  ],\n  \"type\": \"module\",\n  \"sideEffects\": false,\n  \"engines\": {\n    \"node\": \">=22.12.0\"\n  },\n  \"main\": \"./dist/index.js\",\n  \"module\": \"./dist/index.js\",\n  \"types\": \"./dist/index.d.ts\",\n  \"exports\": {\n    \".\": {\n      \"types\": \"./dist/index.d.ts\",\n      \"default\": \"./dist/index.js\"\n    },\n    \"./loader\": {\n      \"types\": \"./dist/loader/index.d.ts\",\n      \"default\": \"./dist/loader/index.js\"\n    },\n    \"./registry\": {\n      \"types\": \"./dist/registry/index.d.ts\",\n      \"default\": \"./dist/registry/index.js\"\n    },\n    \"./frontmatter\": {\n      \"types\": \"./dist/frontmatter/index.d.ts\",\n      \"default\": \"./dist/frontmatter/index.js\"\n    },\n    \"./migration\": {\n      \"types\": \"./dist/migration/index.d.ts\",\n      \"default\": \"./dist/migration/index.js\"\n    },\n    \"./spec\": {\n      \"types\": \"./dist/spec/index.d.ts\",\n      \"default\": \"./dist/spec/index.js\"\n    },\n    \"./activation\": {\n      \"types\": \"./dist/activation/index.d.ts\",\n      \"default\": \"./dist/activation/index.js\"\n    },\n    \"./errors\": {\n      \"types\": \"./dist/errors/index.d.ts\",\n      \"default\": \"./dist/errors/index.js\"\n    },\n    \"./anthropic-spec-snapshot.json\": \"./anthropic-spec-snapshot.json\",\n    \"./package.json\": \"./package.json\"\n  },\n  \"files\": [\n    \"dist\",\n    \"src\",\n    \"anthropic-spec-snapshot.json\",\n    \"README.md\",\n    \"CHANGELOG.md\",\n    \"LICENSE\"\n  ],\n  \"scripts\": {\n    \"build\": \"tsdown\",\n    \"typecheck\": \"tsc --noEmit && tsc -p tsconfig.tests.json\",\n    \"test\": \"vitest run\",\n    \"lint\": \"biome check .\",\n    \"clean\": \"rimraf dist .turbo *.tsbuildinfo\"\n  },\n  \"dependencies\": {\n    \"@graphorin/core\": \"workspace:*\",\n    \"@graphorin/security\": \"workspace:*\",\n    \"yaml\": \"^2.8.0\"\n  },\n  \"publishConfig\": {\n    \"access\": \"public\",\n    \"provenance\": true\n  },\n  \"devDependencies\": {\n    \"fast-check\": \"^3.23.0\",\n    \"zod\": \"^3.25.0\"\n  }\n}\n"],"mappings":";cAEa"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphorin/skills",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Skills surface for the Graphorin framework: loader for the SKILL.md packaging format with three-tier progressive disclosure (metadata / body / resources), frontmatter validator implementing the field-resolution algorithm and conflict policy from ADR-043, registry with auto-activation + slash-command activation, supply-chain hardening (signature verification + `--ignore-scripts` enforcement via @graphorin/security), sandbox-tier propagation for untrusted skills, handoff input-filter declaration recognition, and idempotent migrate-frontmatter library.",
   "license": "MIT",
   "author": "Oleksiy Stepurenko",
@@ -31,8 +31,9 @@
     "migration"
   ],
   "type": "module",
+  "sideEffects": false,
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=22.12.0"
   },
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -40,41 +41,42 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "default": "./dist/index.js"
     },
     "./loader": {
       "types": "./dist/loader/index.d.ts",
-      "import": "./dist/loader/index.js"
+      "default": "./dist/loader/index.js"
     },
     "./registry": {
       "types": "./dist/registry/index.d.ts",
-      "import": "./dist/registry/index.js"
+      "default": "./dist/registry/index.js"
     },
     "./frontmatter": {
       "types": "./dist/frontmatter/index.d.ts",
-      "import": "./dist/frontmatter/index.js"
+      "default": "./dist/frontmatter/index.js"
     },
     "./migration": {
       "types": "./dist/migration/index.d.ts",
-      "import": "./dist/migration/index.js"
+      "default": "./dist/migration/index.js"
     },
     "./spec": {
       "types": "./dist/spec/index.d.ts",
-      "import": "./dist/spec/index.js"
+      "default": "./dist/spec/index.js"
     },
     "./activation": {
       "types": "./dist/activation/index.d.ts",
-      "import": "./dist/activation/index.js"
+      "default": "./dist/activation/index.js"
     },
     "./errors": {
       "types": "./dist/errors/index.d.ts",
-      "import": "./dist/errors/index.js"
+      "default": "./dist/errors/index.js"
     },
     "./anthropic-spec-snapshot.json": "./anthropic-spec-snapshot.json",
     "./package.json": "./package.json"
   },
   "files": [
     "dist",
+    "src",
     "anthropic-spec-snapshot.json",
     "README.md",
     "CHANGELOG.md",
@@ -82,9 +84,8 @@
   ],
   "dependencies": {
     "yaml": "^2.8.0",
-    "@graphorin/core": "0.6.0",
-    "@graphorin/security": "0.6.0",
-    "@graphorin/tools": "0.6.0"
+    "@graphorin/core": "0.7.0",
+    "@graphorin/security": "0.7.0"
   },
   "publishConfig": {
     "access": "public",

package/src/activation/index.ts

@@ -0,0 +1,76 @@
+/**
+ * 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
+ */
+
+import { SlashCommandParseError } from '../errors/index.js';
+import type { SlashCommandActivation } from '../types/index.js';
+
+/**
+ * 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
+ */
+export function parseSlashCommand(raw: string): SlashCommandActivation {
+  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('/skill:'.length);
+  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
+ */
+export function isSlashCommand(raw: string): boolean {
+  try {
+    parseSlashCommand(raw);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/errors/index.ts

@@ -0,0 +1,162 @@
+/**
+ * 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`. */
+export abstract class GraphorinSkillsError extends Error {
+  abstract readonly kind: string;
+  readonly hint?: string;
+  override readonly cause?: unknown;
+  constructor(message: string, options?: { hint?: string; cause?: unknown }) {
+    super(message);
+    this.name = new.target.name;
+    if (options?.hint !== undefined) this.hint = options.hint;
+    if (options?.cause !== undefined) this.cause = options.cause;
+  }
+}
+
+/**
+ * The frontmatter validator detected an Anthropic-base / `graphorin-*`
+ * collision and the operator-resolved policy is `'error'`.
+ */
+export class SkillFrontmatterConflictError extends GraphorinSkillsError {
+  readonly kind = 'frontmatter:conflict' as const;
+  readonly skillName: string;
+  readonly field: string;
+  readonly conflictingFields: ReadonlyArray<string>;
+  constructor(
+    skillName: string,
+    field: string,
+    conflictingFields: ReadonlyArray<string>,
+    options?: { hint?: string },
+  ) {
+    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). */
+export class SkillManifestParseError extends GraphorinSkillsError {
+  readonly kind = 'manifest:parse' as const;
+}
+
+/**
+ * The runtime-compat declaration on a skill does not satisfy the
+ * loader's installed runtime version.
+ */
+export class SkillRuntimeCompatError extends GraphorinSkillsError {
+  readonly kind = 'runtime-compat:mismatch' as const;
+  readonly skillName: string;
+  readonly declared: string;
+  readonly installed: string;
+  constructor(skillName: string, declared: string, installed: string, options?: { hint?: string }) {
+    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. */
+export class SkillRequiredFieldMissingError extends GraphorinSkillsError {
+  readonly kind = 'frontmatter:missing-required' as const;
+  readonly field: string;
+  constructor(field: string, options?: { hint?: string }) {
+    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.
+ */
+export class InputFilterRequiredError extends GraphorinSkillsError {
+  readonly kind = 'handoff:input-filter-required' as const;
+  readonly skillName: string;
+  constructor(skillName: string, options?: { hint?: string; cause?: unknown }) {
+    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 === undefined ? {} : { cause: options.cause }),
+      },
+    );
+    this.skillName = skillName;
+  }
+}
+
+/** A skill source could not be loaded from disk. */
+export class SkillLoadError extends GraphorinSkillsError {
+  readonly kind = 'load:failed' as const;
+  readonly source: string;
+  constructor(source: string, message: string, options?: { hint?: string; cause?: unknown }) {
+    super(`Skill load failed (source='${source}'): ${message}`, options);
+    this.source = source;
+  }
+}
+
+/** A skill name in a registry registration collided with another already-loaded skill. */
+export class SkillNameCollisionError extends GraphorinSkillsError {
+  readonly kind = 'registry:name-collision' as const;
+  readonly skillName: string;
+  constructor(skillName: string, options?: { hint?: string; cause?: unknown }) {
+    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 === undefined ? {} : { cause: options.cause }),
+    });
+    this.skillName = skillName;
+  }
+}
+
+/**
+ * The slash-command parser received a string that did not match the
+ * `/skill:<name>` grammar.
+ */
+export class SlashCommandParseError extends GraphorinSkillsError {
+  readonly kind = 'slash:parse' as const;
+  readonly raw: string;
+  constructor(raw: string, message: string, options?: { hint?: string; cause?: unknown }) {
+    super(`Slash command '${raw}': ${message}`, {
+      hint: options?.hint ?? 'Use `/skill:<name>` to activate a registered skill.',
+      ...(options?.cause === undefined ? {} : { cause: options.cause }),
+    });
+    this.raw = raw;
+  }
+}
+
+/** Convenience union - every `kind` discriminator the package may emit. */
+export type GraphorinSkillsErrorKind =
+  | 'frontmatter:conflict'
+  | 'manifest:parse'
+  | 'runtime-compat:mismatch'
+  | 'frontmatter:missing-required'
+  | 'handoff:input-filter-required'
+  | 'load:failed'
+  | 'registry:name-collision'
+  | 'slash:parse';