@agentproto/skill 0.2.4 → 0.3.0

package/dist/{chunk-GZK4KIZA.mjs → chunk-AKJV2BIA.mjs}

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { createDoctype } from '@agentproto/define-doctype';
+import { createDoctype } from '@agentproto/doctype';
 
 /**
  * @agentproto/skill v0.1.0-alpha
@@ -33,7 +33,9 @@ var executionSchema = z.object({
   dependencies: z.record(z.string(), z.string()).optional()
 }).strict().describe("Executable bindings. Required when variant=executable.");
 var aip3ExtensionsSchema = z.object({
-  schema: z.literal("skills/v1").describe("Schema dispatch tag. Required for AIP-3 conformance."),
+  schema: z.enum(["skill/v1", "skills/v1"]).describe(
+    "Schema dispatch tag. Required for AIP-3 conformance. `skills/v1` is accepted as a legacy alias (AIP-70)."
+  ),
   variant: z.enum(["instruction", "executable", "composite"]).default("instruction").describe(
     "Skill variant. `instruction` is prose-only (default); `executable` bundles runnable code via `execution`; `composite` references other skills via `uses`."
   ),
@@ -109,5 +111,5 @@ var defineSkill = createDoctype({
 });
 
 export { aip3ExtensionsSchema, defineSkill, skillFrontmatterSchema };
-//# sourceMappingURL=chunk-GZK4KIZA.mjs.map
-//# sourceMappingURL=chunk-GZK4KIZA.mjs.map
+//# sourceMappingURL=chunk-AKJV2BIA.mjs.map
+//# sourceMappingURL=chunk-AKJV2BIA.mjs.map

package/dist/chunk-AKJV2BIA.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/schema.ts","../src/define-skill.ts"],"names":[],"mappings":"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","file":"chunk-AKJV2BIA.mjs","sourcesContent":["/**\n * AIP-3 SKILL.md frontmatter zod schema.\n *\n * Mirrors `resources/aip-3/draft/SKILL.schema.json` field-for-field.\n * AIP-3 is a profile of agentskills.io — top-level fields are the\n * canonical agentskills.io frontmatter; AIP-3 extensions live under\n * `metadata.aip3.*` so a skill authored against AIP-3 remains a valid\n * agentskills.io skill in any conformant runtime.\n *\n * Both authoring paths (`define-skill.ts` for TS-authored skills and\n * `manifest/index.ts` for SKILL.md parsing) validate against this\n * schema, so every field-level constraint runs in both paths from a\n * single source of truth.\n *\n * Cross-field rules (variant=executable ⇒ execution required;\n * variant=composite ⇒ uses non-empty) live in `define-skill.ts`'s\n * `validate(def)` body — they're harder to encode in a flat zod\n * schema and want a single error path.\n */\n\nimport { z } from \"zod\"\n\n/** agentskills.io `name` rule: 1–64, kebab, no leading/trailing/consecutive `-`. */\nconst NAME_PATTERN = /^[a-z0-9](?:[a-z0-9]|-(?!-))*[a-z0-9]$|^[a-z0-9]$/\n\nconst SEMVER_PATTERN = /^\\d+\\.\\d+\\.\\d+(?:[-+][a-zA-Z0-9.-]+)?$/\nconst TAG_PATTERN = /^[a-z][a-z0-9-]*$/\n\nconst executionSchema = z\n  .object({\n    language: z\n      .enum([\"typescript\", \"javascript\", \"python\", \"shell\"])\n      .describe(\"Implementation language. Runtimes MAY refuse languages they don't support.\"),\n    code: z\n      .union([\n        z\n          .object({\n            file: z\n              .string()\n              .min(1)\n              .describe(\n                \"Relative path to the entry file. SHOULD live under `scripts/`. Path traversal segments escaping the skill dir MUST be rejected.\",\n              ),\n          })\n          .strict(),\n        z\n          .object({\n            inline: z\n              .string()\n              .describe(\"Inline source. Runtimes MUST sandbox before executing.\"),\n          })\n          .strict(),\n      ])\n      .describe(\"Exactly one of { file } or { inline }. File paths are relative to SKILL.md.\"),\n    entrypoint: z.string().min(1).optional(),\n    runtime: z\n      .object({\n        provider: z.string().optional(),\n        timeout: z.number().int().positive().optional(),\n        memory: z.string().optional(),\n      })\n      .strict()\n      .optional(),\n    artifacts: z\n      .object({\n        patterns: z.array(z.string()).min(1),\n      })\n      .strict()\n      .optional(),\n    dependencies: z.record(z.string(), z.string()).optional(),\n  })\n  .strict()\n  .describe(\"Executable bindings. Required when variant=executable.\")\n\nexport const aip3ExtensionsSchema = z\n  .object({\n    schema: z\n      .enum([\"skill/v1\", \"skills/v1\"])\n      .describe(\n        \"Schema dispatch tag. Required for AIP-3 conformance. `skills/v1` is accepted as a legacy alias (AIP-70).\",\n      ),\n    variant: z\n      .enum([\"instruction\", \"executable\", \"composite\"])\n      .default(\"instruction\")\n      .describe(\n        \"Skill variant. `instruction` is prose-only (default); `executable` bundles runnable code via `execution`; `composite` references other skills via `uses`.\",\n      ),\n    version: z\n      .string()\n      .regex(SEMVER_PATTERN)\n      .optional()\n      .describe(\"Semver. Bump on breaking changes to the skill's behavior or required tools.\"),\n    tags: z\n      .array(z.string().regex(TAG_PATTERN))\n      .max(12)\n      .default([])\n      .describe(\"Catalog tags. Lowercase kebab-case; no leading symbols. 3–6 tags is typical.\"),\n    category: z\n      .string()\n      .min(1)\n      .max(64)\n      .optional()\n      .describe(\n        \"Coarse grouping (e.g. 'productivity', 'creative', 'development'). Free-form; runtimes SHOULD NOT enumerate.\",\n      ),\n    requires: z\n      .array(z.number().int().positive())\n      .default([])\n      .describe(\n        \"Other AIPs this skill depends on (e.g. `[9]` for the operator runtime). Runtimes MAY warn when a declared dependency is unsupported.\",\n      ),\n    author: z\n      .string()\n      .max(200)\n      .optional()\n      .describe(\n        \"Optional. Conventional shape: 'Name <email>' or stable handle. Mirrors agentskills.io's `metadata.author` convention; if both are present, `metadata.aip3.author` wins for AIP-3 runtimes.\",\n      ),\n    title: z\n      .string()\n      .min(1)\n      .max(120)\n      .optional()\n      .describe(\n        \"Optional human-readable display title. Headless runtimes that can't render the body H1 MAY use this. The body H1 is preferred.\",\n      ),\n    uses: z\n      .array(z.string().regex(NAME_PATTERN))\n      .default([])\n      .describe(\n        \"Skill names this skill composes with. Required and non-empty when variant=composite.\",\n      ),\n    execution: executionSchema.optional(),\n  })\n  .loose()\n\nexport const skillFrontmatterSchema = z\n  .object({\n    name: z\n      .string()\n      .min(1)\n      .max(64)\n      .regex(NAME_PATTERN)\n      .describe(\n        \"Machine identifier. 1–64 chars, lowercase alphanumeric and hyphens only, no leading/trailing/consecutive hyphens. MUST equal the parent directory name. Inherited verbatim from agentskills.io.\",\n      ),\n    description: z\n      .string()\n      .min(1)\n      .max(1024)\n      .describe(\n        \"One-paragraph purpose. SHOULD describe both what the skill does and when to use it. Inherited from agentskills.io (1024-char cap).\",\n      ),\n    license: z\n      .string()\n      .max(200)\n      .optional()\n      .describe(\n        \"Optional. License identifier (SPDX or pointer to a bundled license file). Inherited from agentskills.io.\",\n      ),\n    compatibility: z\n      .string()\n      .min(1)\n      .max(500)\n      .optional()\n      .describe(\n        \"Optional. Free-form environment requirements: intended product, system packages, network access, etc. Most skills omit this.\",\n      ),\n    \"allowed-tools\": z\n      .string()\n      .optional()\n      .describe(\n        \"Optional. Space-separated list of pre-approved tool patterns (e.g. 'Bash(git:*) Read'). Experimental upstream — runtimes MAY ignore. The field is a request, not a grant.\",\n      ),\n    metadata: z\n      .object({ aip3: aip3ExtensionsSchema.optional() })\n      .loose()\n      .default({})\n      .describe(\n        \"Free-form key-value mapping. Hosts and standards stash extension fields under namespaced keys (e.g. `metadata.aip3.*`, `metadata.acme.*`). Inherited from agentskills.io.\",\n      ),\n  })\n  .loose()\n  .describe(\n    \"Validates the YAML frontmatter portion of an AIP-3 SKILL.md manifest. AIP-3 is a profile of agentskills.io.\",\n  )\n\nexport type SkillFrontmatter = z.infer<typeof skillFrontmatterSchema>\nexport type Aip3Extensions = z.infer<typeof aip3ExtensionsSchema>\n","import { createDoctype } from \"@agentproto/doctype\"\nimport { skillFrontmatterSchema } from \"./schema.js\"\nimport type { SkillDefinition, SkillHandle } from \"./types.js\"\n\n/**\n * AIP-3 reference implementation of `defineSkill`.\n *\n * Built on `createDoctype` so the cross-AIP invariants (id pattern,\n * description length, top-level freeze, \"defineSkill (AIP-3): …\"\n * error prefix) run uniformly with every other AIP defineX.\n *\n * Field-level validation runs the schema-derived zod from\n * `./schema.ts` against the input. Same source of truth as the .md\n * path uses (`parseSkillManifest`), so a malformed TS-authored\n * definition fails with the same diagnostic as a malformed manifest.\n *\n * Cross-field rules — variant=executable requires `metadata.aip3.execution`;\n * variant=composite requires non-empty `metadata.aip3.uses` — run after\n * the zod check so callers see one consistent error path.\n *\n * Identity / description extractors detected from the JSON Schema:\n *   readIdentity: def.name\n *   readDescription: def.description.\n */\nexport const defineSkill = createDoctype<SkillDefinition, SkillHandle>({\n  aip: 3,\n  name: \"skill\",\n  readIdentity: (def) => def.name,\n  validate(def) {\n    const result = skillFrontmatterSchema.safeParse(def)\n    if (!result.success) {\n      throw new Error(\n        `defineSkill (AIP-3): ${result.error.issues\n          .map((i) => `${i.path.join(\".\")}: ${i.message}`)\n          .join(\"; \")}`,\n      )\n    }\n\n    const aip3 = result.data.metadata?.aip3\n    if (!aip3) return\n\n    const variant = aip3.variant ?? \"instruction\"\n    if (variant === \"executable\" && !aip3.execution) {\n      throw new Error(\n        \"defineSkill (AIP-3): metadata.aip3.execution is required when metadata.aip3.variant=executable\",\n      )\n    }\n    if (variant === \"composite\" && (!aip3.uses || aip3.uses.length === 0)) {\n      throw new Error(\n        \"defineSkill (AIP-3): metadata.aip3.uses must be non-empty when metadata.aip3.variant=composite\",\n      )\n    }\n  },\n  build(def) {\n    return { ...def } as SkillHandle\n  },\n})\n"]}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { S as SkillDefinition } from './schema-yW7X0mwK.js';
-export { A as Aip3Extensions, a as SkillExecution, b as SkillExecutionLanguage, c as SkillFrontmatter, d as SkillHandle, e as SkillVariant, f as aip3ExtensionsSchema, s as skillFrontmatterSchema } from './schema-yW7X0mwK.js';
+import { S as SkillDefinition } from './schema-ChpeZIr2.js';
+export { A as Aip3Extensions, a as SkillExecution, b as SkillExecutionLanguage, c as SkillFrontmatter, d as SkillHandle, e as SkillVariant, f as aip3ExtensionsSchema, s as skillFrontmatterSchema } from './schema-ChpeZIr2.js';
 import 'zod';
 
 /**
@@ -35,7 +35,7 @@ declare const defineSkill: (def: SkillDefinition) => Readonly<SkillDefinition>;
  *   - TS:  `defineSkill({...})` → `SkillHandle`
  *   - MD:  `parseSkillManifest(src) → skillFromManifest({...})` → `SkillHandle`
  */
-declare const SPEC_NAME: "agentskill/v1";
+declare const SPEC_NAME: "skill/v1";
 declare const SPEC_VERSION: "2.0.0-alpha";
 
 export { SPEC_NAME, SPEC_VERSION, SkillDefinition, defineSkill };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-export { aip3ExtensionsSchema, defineSkill, skillFrontmatterSchema } from './chunk-GZK4KIZA.mjs';
+export { aip3ExtensionsSchema, defineSkill, skillFrontmatterSchema } from './chunk-AKJV2BIA.mjs';
 
 /**
  * @agentproto/skill v0.1.0-alpha
@@ -6,7 +6,7 @@ export { aip3ExtensionsSchema, defineSkill, skillFrontmatterSchema } from './chu
  */
 
 // src/index.ts
-var SPEC_NAME = "agentskill/v1";
+var SPEC_NAME = "skill/v1";
 var SPEC_VERSION = "2.0.0-alpha";
 
 export { SPEC_NAME, SPEC_VERSION };

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;AAYO,IAAM,SAAA,GAAY;AAClB,IAAM,YAAA,GAAe","file":"index.mjs","sourcesContent":["/**\n * @agentproto/skill — AIP-3 SKILL.md `defineSkill` reference impl.\n *\n * A markdown + frontmatter format for distributing reusable agent skills as portable, version-controlled files.\n *\n * Spec: https://agentproto.sh/docs/aip-3\n *\n * Authoring paths:\n *   - TS:  `defineSkill({...})` → `SkillHandle`\n *   - MD:  `parseSkillManifest(src) → skillFromManifest({...})` → `SkillHandle`\n */\n\nexport const SPEC_NAME = \"agentskill/v1\" as const\nexport const SPEC_VERSION = \"2.0.0-alpha\" as const\n\nexport { defineSkill } from \"./define-skill.js\"\nexport { skillFrontmatterSchema, aip3ExtensionsSchema } from \"./schema.js\"\nexport type { SkillFrontmatter, Aip3Extensions } from \"./schema.js\"\nexport type {\n  SkillDefinition,\n  SkillHandle,\n  SkillVariant,\n  SkillExecution,\n  SkillExecutionLanguage,\n} from \"./types.js\"\n"]}
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;AAYO,IAAM,SAAA,GAAY;AAClB,IAAM,YAAA,GAAe","file":"index.mjs","sourcesContent":["/**\n * @agentproto/skill — AIP-3 SKILL.md `defineSkill` reference impl.\n *\n * A markdown + frontmatter format for distributing reusable agent skills as portable, version-controlled files.\n *\n * Spec: https://agentproto.sh/docs/aip-3\n *\n * Authoring paths:\n *   - TS:  `defineSkill({...})` → `SkillHandle`\n *   - MD:  `parseSkillManifest(src) → skillFromManifest({...})` → `SkillHandle`\n */\n\nexport const SPEC_NAME = \"skill/v1\" as const\nexport const SPEC_VERSION = \"2.0.0-alpha\" as const\n\nexport { defineSkill } from \"./define-skill.js\"\nexport { skillFrontmatterSchema, aip3ExtensionsSchema } from \"./schema.js\"\nexport type { SkillFrontmatter, Aip3Extensions } from \"./schema.js\"\nexport type {\n  SkillDefinition,\n  SkillHandle,\n  SkillVariant,\n  SkillExecution,\n  SkillExecutionLanguage,\n} from \"./types.js\"\n"]}

package/dist/manifest/index.d.ts

@@ -1,5 +1,5 @@
-import { c as SkillFrontmatter, d as SkillHandle } from '../schema-yW7X0mwK.js';
-export { s as skillFrontmatterSchema } from '../schema-yW7X0mwK.js';
+import { c as SkillFrontmatter, d as SkillHandle } from '../schema-ChpeZIr2.js';
+export { s as skillFrontmatterSchema } from '../schema-ChpeZIr2.js';
 import 'zod';
 
 /**

package/dist/manifest/index.mjs

@@ -1,5 +1,5 @@
-import { skillFrontmatterSchema, defineSkill } from '../chunk-GZK4KIZA.mjs';
-export { skillFrontmatterSchema } from '../chunk-GZK4KIZA.mjs';
+import { skillFrontmatterSchema, defineSkill } from '../chunk-AKJV2BIA.mjs';
+export { skillFrontmatterSchema } from '../chunk-AKJV2BIA.mjs';
 import matter from 'gray-matter';
 
 /**

package/dist/{schema-yW7X0mwK.d.ts → schema-ChpeZIr2.d.ts}

@@ -39,7 +39,7 @@ interface SkillExecution {
 /** AIP-3 extensions to the agentskills.io baseline. Lives under `metadata.aip3`. */
 interface Aip3Extensions$1 {
     /** Schema dispatch tag. Required for AIP-3 conformance. */
-    schema: "skills/v1";
+    schema: "skill/v1" | "skills/v1";
     /** Skill variant. Defaults to "instruction" when omitted. */
     variant?: SkillVariant;
     /** Semver. */
@@ -110,7 +110,10 @@ type SkillHandle = Readonly<SkillDefinition>;
  */
 
 declare const aip3ExtensionsSchema: z.ZodObject<{
-    schema: z.ZodLiteral<"skills/v1">;
+    schema: z.ZodEnum<{
+        "skill/v1": "skill/v1";
+        "skills/v1": "skills/v1";
+    }>;
     variant: z.ZodDefault<z.ZodEnum<{
         instruction: "instruction";
         executable: "executable";
@@ -155,7 +158,10 @@ declare const skillFrontmatterSchema: z.ZodObject<{
     "allowed-tools": z.ZodOptional<z.ZodString>;
     metadata: z.ZodDefault<z.ZodObject<{
         aip3: z.ZodOptional<z.ZodObject<{
-            schema: z.ZodLiteral<"skills/v1">;
+            schema: z.ZodEnum<{
+                "skill/v1": "skill/v1";
+                "skills/v1": "skills/v1";
+            }>;
             variant: z.ZodDefault<z.ZodEnum<{
                 instruction: "instruction";
                 executable: "executable";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentproto/skill",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "description": "@agentproto/skill — AIP-3 SKILL.md reference implementation. A markdown + frontmatter format for distributing reusable agent skills as portable, version-controlled files.",
   "keywords": [
     "agentproto",
@@ -47,11 +47,11 @@
   },
   "dependencies": {
     "gray-matter": "^4.0.3",
-    "zod": "^4.6.5",
-    "@agentproto/define-doctype": "0.1.3"
+    "zod": "^4.6.7",
+    "@agentproto/doctype": "0.2.0"
   },
   "devDependencies": {
-    "@types/node": "^25.9.5",
+    "@types/node": "^25.9.9",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "vitest": "^3.2.7",

package/dist/chunk-GZK4KIZA.mjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/schema.ts","../src/define-skill.ts"],"names":[],"mappings":"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","file":"chunk-GZK4KIZA.mjs","sourcesContent":["/**\n * AIP-3 SKILL.md frontmatter zod schema.\n *\n * Mirrors `resources/aip-3/draft/SKILL.schema.json` field-for-field.\n * AIP-3 is a profile of agentskills.io — top-level fields are the\n * canonical agentskills.io frontmatter; AIP-3 extensions live under\n * `metadata.aip3.*` so a skill authored against AIP-3 remains a valid\n * agentskills.io skill in any conformant runtime.\n *\n * Both authoring paths (`define-skill.ts` for TS-authored skills and\n * `manifest/index.ts` for SKILL.md parsing) validate against this\n * schema, so every field-level constraint runs in both paths from a\n * single source of truth.\n *\n * Cross-field rules (variant=executable ⇒ execution required;\n * variant=composite ⇒ uses non-empty) live in `define-skill.ts`'s\n * `validate(def)` body — they're harder to encode in a flat zod\n * schema and want a single error path.\n */\n\nimport { z } from \"zod\"\n\n/** agentskills.io `name` rule: 1–64, kebab, no leading/trailing/consecutive `-`. */\nconst NAME_PATTERN = /^[a-z0-9](?:[a-z0-9]|-(?!-))*[a-z0-9]$|^[a-z0-9]$/\n\nconst SEMVER_PATTERN = /^\\d+\\.\\d+\\.\\d+(?:[-+][a-zA-Z0-9.-]+)?$/\nconst TAG_PATTERN = /^[a-z][a-z0-9-]*$/\n\nconst executionSchema = z\n  .object({\n    language: z\n      .enum([\"typescript\", \"javascript\", \"python\", \"shell\"])\n      .describe(\"Implementation language. Runtimes MAY refuse languages they don't support.\"),\n    code: z\n      .union([\n        z\n          .object({\n            file: z\n              .string()\n              .min(1)\n              .describe(\n                \"Relative path to the entry file. SHOULD live under `scripts/`. Path traversal segments escaping the skill dir MUST be rejected.\",\n              ),\n          })\n          .strict(),\n        z\n          .object({\n            inline: z\n              .string()\n              .describe(\"Inline source. Runtimes MUST sandbox before executing.\"),\n          })\n          .strict(),\n      ])\n      .describe(\"Exactly one of { file } or { inline }. File paths are relative to SKILL.md.\"),\n    entrypoint: z.string().min(1).optional(),\n    runtime: z\n      .object({\n        provider: z.string().optional(),\n        timeout: z.number().int().positive().optional(),\n        memory: z.string().optional(),\n      })\n      .strict()\n      .optional(),\n    artifacts: z\n      .object({\n        patterns: z.array(z.string()).min(1),\n      })\n      .strict()\n      .optional(),\n    dependencies: z.record(z.string(), z.string()).optional(),\n  })\n  .strict()\n  .describe(\"Executable bindings. Required when variant=executable.\")\n\nexport const aip3ExtensionsSchema = z\n  .object({\n    schema: z\n      .literal(\"skills/v1\")\n      .describe(\"Schema dispatch tag. Required for AIP-3 conformance.\"),\n    variant: z\n      .enum([\"instruction\", \"executable\", \"composite\"])\n      .default(\"instruction\")\n      .describe(\n        \"Skill variant. `instruction` is prose-only (default); `executable` bundles runnable code via `execution`; `composite` references other skills via `uses`.\",\n      ),\n    version: z\n      .string()\n      .regex(SEMVER_PATTERN)\n      .optional()\n      .describe(\"Semver. Bump on breaking changes to the skill's behavior or required tools.\"),\n    tags: z\n      .array(z.string().regex(TAG_PATTERN))\n      .max(12)\n      .default([])\n      .describe(\"Catalog tags. Lowercase kebab-case; no leading symbols. 3–6 tags is typical.\"),\n    category: z\n      .string()\n      .min(1)\n      .max(64)\n      .optional()\n      .describe(\n        \"Coarse grouping (e.g. 'productivity', 'creative', 'development'). Free-form; runtimes SHOULD NOT enumerate.\",\n      ),\n    requires: z\n      .array(z.number().int().positive())\n      .default([])\n      .describe(\n        \"Other AIPs this skill depends on (e.g. `[9]` for the operator runtime). Runtimes MAY warn when a declared dependency is unsupported.\",\n      ),\n    author: z\n      .string()\n      .max(200)\n      .optional()\n      .describe(\n        \"Optional. Conventional shape: 'Name <email>' or stable handle. Mirrors agentskills.io's `metadata.author` convention; if both are present, `metadata.aip3.author` wins for AIP-3 runtimes.\",\n      ),\n    title: z\n      .string()\n      .min(1)\n      .max(120)\n      .optional()\n      .describe(\n        \"Optional human-readable display title. Headless runtimes that can't render the body H1 MAY use this. The body H1 is preferred.\",\n      ),\n    uses: z\n      .array(z.string().regex(NAME_PATTERN))\n      .default([])\n      .describe(\n        \"Skill names this skill composes with. Required and non-empty when variant=composite.\",\n      ),\n    execution: executionSchema.optional(),\n  })\n  .loose()\n\nexport const skillFrontmatterSchema = z\n  .object({\n    name: z\n      .string()\n      .min(1)\n      .max(64)\n      .regex(NAME_PATTERN)\n      .describe(\n        \"Machine identifier. 1–64 chars, lowercase alphanumeric and hyphens only, no leading/trailing/consecutive hyphens. MUST equal the parent directory name. Inherited verbatim from agentskills.io.\",\n      ),\n    description: z\n      .string()\n      .min(1)\n      .max(1024)\n      .describe(\n        \"One-paragraph purpose. SHOULD describe both what the skill does and when to use it. Inherited from agentskills.io (1024-char cap).\",\n      ),\n    license: z\n      .string()\n      .max(200)\n      .optional()\n      .describe(\n        \"Optional. License identifier (SPDX or pointer to a bundled license file). Inherited from agentskills.io.\",\n      ),\n    compatibility: z\n      .string()\n      .min(1)\n      .max(500)\n      .optional()\n      .describe(\n        \"Optional. Free-form environment requirements: intended product, system packages, network access, etc. Most skills omit this.\",\n      ),\n    \"allowed-tools\": z\n      .string()\n      .optional()\n      .describe(\n        \"Optional. Space-separated list of pre-approved tool patterns (e.g. 'Bash(git:*) Read'). Experimental upstream — runtimes MAY ignore. The field is a request, not a grant.\",\n      ),\n    metadata: z\n      .object({ aip3: aip3ExtensionsSchema.optional() })\n      .loose()\n      .default({})\n      .describe(\n        \"Free-form key-value mapping. Hosts and standards stash extension fields under namespaced keys (e.g. `metadata.aip3.*`, `metadata.acme.*`). Inherited from agentskills.io.\",\n      ),\n  })\n  .loose()\n  .describe(\n    \"Validates the YAML frontmatter portion of an AIP-3 SKILL.md manifest. AIP-3 is a profile of agentskills.io.\",\n  )\n\nexport type SkillFrontmatter = z.infer<typeof skillFrontmatterSchema>\nexport type Aip3Extensions = z.infer<typeof aip3ExtensionsSchema>\n","import { createDoctype } from \"@agentproto/define-doctype\"\nimport { skillFrontmatterSchema } from \"./schema.js\"\nimport type { SkillDefinition, SkillHandle } from \"./types.js\"\n\n/**\n * AIP-3 reference implementation of `defineSkill`.\n *\n * Built on `createDoctype` so the cross-AIP invariants (id pattern,\n * description length, top-level freeze, \"defineSkill (AIP-3): …\"\n * error prefix) run uniformly with every other AIP defineX.\n *\n * Field-level validation runs the schema-derived zod from\n * `./schema.ts` against the input. Same source of truth as the .md\n * path uses (`parseSkillManifest`), so a malformed TS-authored\n * definition fails with the same diagnostic as a malformed manifest.\n *\n * Cross-field rules — variant=executable requires `metadata.aip3.execution`;\n * variant=composite requires non-empty `metadata.aip3.uses` — run after\n * the zod check so callers see one consistent error path.\n *\n * Identity / description extractors detected from the JSON Schema:\n *   readIdentity: def.name\n *   readDescription: def.description.\n */\nexport const defineSkill = createDoctype<SkillDefinition, SkillHandle>({\n  aip: 3,\n  name: \"skill\",\n  readIdentity: (def) => def.name,\n  validate(def) {\n    const result = skillFrontmatterSchema.safeParse(def)\n    if (!result.success) {\n      throw new Error(\n        `defineSkill (AIP-3): ${result.error.issues\n          .map((i) => `${i.path.join(\".\")}: ${i.message}`)\n          .join(\"; \")}`,\n      )\n    }\n\n    const aip3 = result.data.metadata?.aip3\n    if (!aip3) return\n\n    const variant = aip3.variant ?? \"instruction\"\n    if (variant === \"executable\" && !aip3.execution) {\n      throw new Error(\n        \"defineSkill (AIP-3): metadata.aip3.execution is required when metadata.aip3.variant=executable\",\n      )\n    }\n    if (variant === \"composite\" && (!aip3.uses || aip3.uses.length === 0)) {\n      throw new Error(\n        \"defineSkill (AIP-3): metadata.aip3.uses must be non-empty when metadata.aip3.variant=composite\",\n      )\n    }\n  },\n  build(def) {\n    return { ...def } as SkillHandle\n  },\n})\n"]}