@aeonbrain/skill-schema

The foundational primitive for the Aeon platform. Every other component compiles to this schema or consumes from it.

What's in this package

• AeonSkill Zod schema (src/schema.ts) — the canonical, vendor-neutral shape of a skill. Versioned via schemaVersion (currently "1.0").
• Canonical JSON serialization (src/canonical.ts) — sorted-key, no-whitespace serialization for byte-stable signing input.
• ed25519 signing + verification (src/signing.ts) — async-only API built on @noble/ed25519 v2.
• Compilers (src/compilers/) — Aeon → SKILL.md / OpenAPI 3.1 / OpenAI Custom GPT action.

Why a schema, not just SKILL.md

Anthropic's SKILL.md is the wire format for Claude. Microsoft Copilot Studio takes OpenAPI tool definitions. OpenAI Custom GPTs take OpenAPI 3.1 documents with x-openai-* extensions. We define one Aeon schema as a superset and emit the right format per runtime. Hyperscalers will not ship cross-runtime portability — lock-in is their incentive. We are the Switzerland of skills.

The schema

interface AeonSkill {
  schemaVersion: "1.0";
  slug: string;                 // tenant-unique kebab-case identifier
  name: string;
  description: string;
  domain: string;

  trigger: {
    pattern: "natural-language" | "explicit-call";
    examples: string[];
  };

  inputs: AeonInput[];
  outputs: AeonOutput[];
  steps: AeonStep[];

  governance: {
    requiresApproval: boolean;
    dataClasses: string[];
    regulatoryMappings: string[];
  };

  provenance: {
    sourceArtifactIds: string[];
    extractionRunId: string;
    authoredBy: string;
    authorizedAt: string;       // ISO 8601
  };

  signature?: {                 // attached at publish time, not at draft time
    algorithm: "ed25519";
    publicKeyId: string;
    value: string;              // base64-encoded
  };
}

Canonical example: refund handling

The example skill below is the round-trip fixture for tests (src/__tests__/fixtures.ts). It models the workflow extracted from a Slack thread about a $14,400 annual refund — the kind of tribal knowledge Aeon turns into an executable skill any AI runtime can consume.

import {
  AeonSkillSchema,
  compileToAnthropicSkillMd,
  compileToOpenApiTool,
  compileToOpenAiGptAction,
  generateKeyPair,
  signAndAttach,
  verifySkill,
} from "@aeonbrain/skill-schema";

const refundSkill = AeonSkillSchema.parse({
  schemaVersion: "1.0",
  slug: "process-customer-refund",
  name: "Process a Customer Refund Request",
  description: "Handles a refund request through escalation tiers and finance reconciliation.",
  domain: "customer-success",
  trigger: {
    pattern: "natural-language",
    examples: ["Customer X is asking for a refund", "We need to refund Acme Corp"],
  },
  inputs: [
    { name: "accountName", description: "Customer account", type: "string", required: true },
    { name: "refundAmount", description: "Requested USD amount", type: "number", required: true },
  ],
  outputs: [
    { name: "refundId", description: "Internal refund ID", type: "string" },
  ],
  steps: [
    { order: 0, description: "Confirm with sales rep this isn't a sandbagged renewal.", type: "lookup" },
    { order: 1, description: "If over $5,000 annual, get account-owner approval via email.", type: "user-input" },
  ],
  governance: {
    requiresApproval: true,
    dataClasses: ["financial", "customer-PII"],
    regulatoryMappings: [],
  },
  provenance: {
    sourceArtifactIds: ["slack-refund-thread"],
    extractionRunId: "run-2026-04-30-001",
    authoredBy: "user-curator-001",
    authorizedAt: "2026-04-30T14:00:00Z",
  },
});

// Sign at publish time
const { privateKey, publicKey } = await generateKeyPair();
const signed = await signAndAttach(refundSkill, privateKey, "tenant-key-1");

// Verify
await verifySkill(signed, publicKey); // true

// Compile to runtime targets
const skillMd = compileToAnthropicSkillMd(signed);     // → SKILL.md for Claude
const openapi = compileToOpenApiTool(signed);          // → OpenAPI for Copilot Studio
const gptAction = compileToOpenAiGptAction(signed);    // → OpenAPI + x-openai-* extensions

Signing details

• Algorithm: ed25519 (@noble/ed25519 v2 async APIs)
• Bytes signed: canonical JSON of the skill with the signature field stripped (see canonicalizeForSigning)
• Signature encoding: standard base64
• Determinism: signing the same skill with the same key produces the same signature (covered by tests — important for re-signing after immaterial edits)

The signing private key never leaves AWS KMS in production. This package accepts raw bytes so it stays portable; integration with KMS happens at the API layer (Phase 3+).

Running tests

npm install                                # at the repo root
npm run -w @aeonbrain/skill-schema test         # vitest
npm run -w @aeonbrain/skill-schema typecheck    # tsc --noEmit