# `@contentful/skill-kit` — SDK Specification _v0.1 draft. Builds on the Skill CLI PRD. Specs the TypeScript library skill authors import to define stateful, CLI-driven skills._ --- ## What this is A SDK for building agent skills where the workflow is driven by a small bundled CLI rather than by prose alone. If you've only seen the prose-based skill format (a `SKILL.md` file full of instructions the agent reads), this is a different shape. Read this section before the rest. ### The problem it solves Today's skills are a single blob of prose. This works for one-shot tasks ("rewrite this README in a friendlier tone") but degrades fast for multi-stage workflows. Long prose is hard to review, inconsistent across models, impossible to branch cleanly, and gives no way to enforce strict input/output formats. A 3,000-line prose skill is unpleasant to reason about and slow to improve. ### The shape of the solution A skill is a folder containing a small CLI program plus supporting prose and reference files. The agent invokes the CLI, the CLI hands back a prompt for the current step, the agent does the thinking, the agent returns its answer to the CLI, and the CLI decides what the next step is. The loop continues until the CLI says the workflow is done. ``` ┌─────────────┐ "here is step N's prompt" ┌─────────────┐ │ │ ─────────────────────────────► │ │ │ Agent │ │ Skill CLI │ │ (Claude, │ step N's answer, structured │ (workflow │ │ Codex, │ ─────────────────────────────► │ engine) │ │ etc.) │ │ │ │ │ "here is step N+1's prompt" │ │ │ │ ◄───────────────────────────── │ │ └─────────────┘ └─────────────┘ ``` ### Responsibilities, explicitly **The CLI is the engine.** It owns the workflow's state machine. It decides which step runs next based on the answer to the previous step. It validates the agent's response against a schema. It holds shared state across steps. It does progressive disclosure — the agent only sees the prose for the step it's currently on, never the whole skill. **The prose is still prose.** Authors write each step's instructions in plain markdown. The SDK doesn't replace prose with code; it just controls when each piece of prose is shown and what shape the agent's answer has to take. Nodes contain freely-written instructions; transitions between nodes are typed and explicit. **The agent does what agents are good at.** Reading, reasoning, writing, calling host tools, synthesizing. The agent doesn't need to understand the skill's overall structure — it just reads the current prompt, does the work, and returns an answer. The CLI handles everything else. ### Why this is better than pure prose - **Reviewable.** Each step is small and has an explicit contract. Skills become diffable the way code is diffable. - **Deterministic where it matters.** Formatting-heavy outputs (tables, reports) are rendered by code and pasted by the model verbatim, not negotiated per turn. - **Branchable without drift.** The CLI decides next steps from typed outputs, not by hoping the model picks the right path out of a long prose flowchart. - **Host-portable.** Different agent hosts expose different native tools. The SDK emits XML tags for primitives and maps them to host tools via the preamble, so one skill works everywhere with the best UX the host can offer. - **Improves over time.** Prompt-engineering work done in the SDK benefits every skill that uses SDK primitives. Authors don't rewrite prose to pick up improvements. ### What authors write ```typescript // skill.ts import { skill, type } from '@contentful/skill-kit'; export default skill({ name: 'repo-doctor', entry: 'diagnose', params: type({ repoPath: 'string = "."' }), }) .step('diagnose', { prompt: 'Inspect the repository and report failed health checks.', response: type({ checks: CheckResult.array() }), next: ({ response }) => (response.checks.some((c) => c.status === 'fail') ? 'remediate' : 'report'), }) .step('remediate', { /* ... */ }) .step('report', { /* ... */ }) .build(); ``` `skill()` returns a builder. `.step()` chains add steps — params types flow into callbacks via contextual inference. `.build()` produces the final skill definition. `skill-kit build` then bundles it into a distributable skill directory — a bundled executable or JS file, a generated `SKILL.md` (per the [agentskills.io spec](https://agentskills.io/specification)), and a shell wrapper in `scripts/`. ### What authors don't write - A state machine implementation — the SDK provides it. - Host-specific tool invocations — the SDK's primitives emit XML tags mapped to tools via the preamble. - Parsing, validation, retry logic — handled at the boundary by response schemas. - Formatting templates repeated across prompts — `view()`, renderers, and fragments cover that. ### Where to read next The sections below go in order: primitives (§1), prompts and fragments (§2), transitions (§3), views and rendering (§4), references (§5), modularization (§6), params and state including terminal-output for programmatic consumers (§7), side effects and observers (§8), testing (§9), the CLI invocation protocol (§10), build and distribution (§11), repo layout for skill authors (§12), opinionated decisions (§13), cross-host behavior (§14), and what's out of scope for v0.1 (§15). If you just want to see the whole shape at once, read §1 and §4, then skim §11–§14. --- ## Design goals 1. **Declarative feel.** A simple skill is ~30 lines. Authors describe a workflow, not write one. 2. **Prose stays prose.** The SDK structures _when_ prose is shown and _what contract_ it satisfies. It never replaces prose with code. 3. **Typed boundaries, untyped interiors.** Step I/O is schema-enforced. What the model does inside a step is freeform. 4. **Node-native, flexible distribution.** `npx tsx skill.ts` works in dev. `skill-kit build` bundles skills for distribution — either as lightweight Node.js bundles (`--mode node`, via esbuild) or standalone executables (`--mode bun`, via `bun build --compile`). 5. **Composable.** Steps, schemas, fragments, and render helpers are importable across skills. 6. **One obvious way.** Opinionated where the cost of choice exceeds the benefit. --- ## 1. Core primitives ### `skill(config)` → `SkillBuilder` Returns a builder. One per entry file. Params ArkType schemas declared here flow into all step callbacks. ```typescript import { skill, type } from '@contentful/skill-kit'; export default skill({ name: 'repo-doctor', version: '1.0.0', system: 'You are a thorough code health inspector. Be precise and actionable.', entry: 'diagnose', params: type({ repoPath: 'string = "."' }), package: { name: '@contentful/skill-repo-doctor', license: 'MIT', }, }) .step('diagnose', { /* ... */ }) .step('remediate', { /* ... */ }) .step('report', { /* ... */ }) .build(); ``` ### `.step(name, config)` on the builder Adds a step inline. The prompt callbacks receive typed `params` and `store` from the builder — no manual annotations. ```typescript .step("diagnose", { prompt: ({ params }) => `Check ${params.repoPath}`, // repoPath: string ✓ response: type({ /* ... */ }), next: "report", }) ``` The `response` schema is optional. When omitted, no `` block is emitted in the prompt and response validation is skipped. See [Response-less steps](#response-less-steps) below. ### `step(config)` — standalone function For shared/reusable steps defined outside a skill. These default to untyped params/store. Use `.extend()` on the builder to apply typed overrides. ```typescript import { step, type } from "@contentful/skill-kit"; export const openQuestion = step({ response: type({ answer: 'string' }), next: "__parent__", }); // In a skill: .extend("ask-name", openQuestion, { prompt: ({ store }) => `${store.steps.greet.name}, tell me more.`, // typed via builder next: "done", }) ``` ### `module(config)` → `ModuleBuilder` Composable step groups with their own store scope. Module steps can't access the parent skill's params (enforces portability). ```typescript import { module, type } from '@contentful/skill-kit'; export const authModule = module({ name: 'auth', entry: 'auth-login', }) .step('auth-login', { /* ... next: "__parent__" */ }) .build(); ``` Register into a skill with `.register()` — store types merge via intersection: ```typescript skill({ ... }) .register(authModule, { next: "dashboard" }) // store types from module steps are available .step("dashboard", { prompt: ({ store }) => `${store.steps['auth-login'].userId} logged in`, // typed ✓ ... }) ``` ### `type` ArkType's `type` function re-exported so authors don't manage a separate dependency and all schemas come from one source. --- ## 2. Prompts ### Static ```typescript step({ prompt: ` Inspect the repository. Return whether CI is configured and which provider is detected. `, response: type({ configured: 'boolean', provider: 'string | null' }), next: 'report', }); ``` ### Dynamic A function of the workflow state, returning `string | PromptPiece | PromptPiece[]`. Plain strings are instructions. `system` segments set persona/frame. `act` segments inject primitive directives (see [Composable prompt vocabulary](#composable-prompt-vocabulary) below). The `prompt` field also accepts a single `PromptPiece` or `PromptPiece[]` directly (not wrapped in a function), which is useful for steps that consist entirely of primitive directives. ```typescript step({ prompt: ({ params, store }) => { const diagnose = store.steps.diagnose; return ` Failed checks for ${params.repoPath}: ${JSON.stringify(diagnose.failedChecks, null, 2)} Propose concrete remediation for each. `; }, response: RemediationsSchema, next: 'report', }); ``` Fields available in the prompt function: | Field | Description | | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `store` | State accessor. Step results under `store.steps.*` — guaranteed steps are non-optional (`store.steps.greet.name`), branch targets are optional (`store.steps['ask-stack']?.answer`). Sub-stores at `store.*`. See §7. | | `params` | Skill params — the external data passed at invocation (config defaults + runtime overrides) | | `refs` | Lazy loader for reference files (§5) | | `attempts` | How many times this step has been visited (for retries) | | `host` | The handshake — `host`, `toolsAvailable`, `isSubagent` | | `act` | Primitive directive builders (see §2.1) | | `system` | System segment tag/function for persona/frame (see §2.1) | > **Why `params` instead of `context`?** "Context" is overloaded — callback context, execution context, prompt context, etc. "params" clearly identifies the external data passed to the skill at invocation time, distinct from the internal workflow state. ### Fragments (partials) For prose that repeats across steps or skills. ```typescript // fragments/tone.ts import { fragment } from '@contentful/skill-kit'; export const enterpriseTone = fragment( 'enterprise-tone', ` Use a professional, concise tone. Avoid jargon unless the user introduced it. Prefer concrete recommendations over hedging. `, ); export const jsonOutputRules = fragment( 'json-output', ` Return only valid JSON matching the schema. No preamble, no markdown fences, no commentary outside the object. `, ); ``` Used via a tagged template literal that handles indentation and interpolation: ```typescript import { prompt } from '@contentful/skill-kit'; import { enterpriseTone, jsonOutputRules } from '../fragments/tone'; step({ prompt: ({ store }) => { const gather = store.steps.gather; return prompt` ${enterpriseTone} Analyze the dependency tree at ${gather.repoPath}. Flag packages with known CVEs. ${jsonOutputRules} `; }, }); ``` Fragments are named (first arg) so tooling can track usage, detect duplication, and lint for drift. `prompt` is the only bit of sugar. It exists because plain template literals in indented TS produce ugly whitespace; everything else is standard functions. ### Composable prompt vocabulary Prompt functions can return `string | PromptPiece | PromptPiece[]`. A `PromptPiece` is either a plain string (instructions), a `system` segment (persona/frame), or an `act` segment (primitive directive). When a prompt returns an array, the SDK assembles pieces in **author order** — segments appear in the output exactly as written. The `act` and `system` helpers are injected via `PromptContext`, not imported. Authors destructure them from the prompt function argument: ```typescript .step('build', { prompt: ({ store, act, system }) => [ system`You are a game dev mentor. Be methodical.`, act.checklist({ create: store.steps.plan.tasks.map(t => ({ title: t, status: 'pending' })) }), prompt`Build the game. Update the checklist as you go.`, ], response: type({ filesCreated: 'string[]' }), next: 'done', }) ``` **`system`** — creates a system segment for persona or framing. Used as a template tag (`system\`...\``) or called as a function (`system('...')`). **`act`** — provides methods for each primitive: - `act.askUser(config)` — structured or open question directive - `act.confirm(config)` — binary approval directive - `act.plan(config)` — plan presentation directive - `act.checklist(config)` — tracked task list directive - `act.subagent(config)` — sub-agent spawn directive Each `act` method returns an `act` segment with the primitive's host-aware prose. The returned `PromptPiece` is opaque to authors — the SDK renders it during prompt assembly. **Assembly** — `resolvePromptValue` calls the prompt function, `normalizePieces` coerces the return to an array of `PromptPiece`, and `assemblePieces` renders each piece as XML: plain strings become `` tags, system segments become `` tags, act segments are rendered via `renderPrimitive()` into their respective XML tags (e.g., ``, ``), and view segments are wrapped in `` tags (with an optional `name` attribute). All pieces are concatenated in author order. The `PromptFn` return type is `PromptReturn` (= `string | PromptPiece | PromptPiece[]`). #### Simple single-primitive steps Since `prompt` now accepts `PromptPiece` directly (including `ActSegment`), a step that consists entirely of one primitive needs no wrapper function: ```typescript .step('choose', { prompt: act.askUser({ type: 'structured', question: '...', options: [...] }), response: type({ choice: 'string' }), next: 'next-step', }) ``` Any `ActSegment` or `PromptPiece` can be passed directly to `prompt` — no wrapper needed for single-primitive steps. #### Prompt-less steps When `prompt` is omitted from a step config, the engine auto-advances without an LLM round-trip. The step runs its `next` callback immediately — no prompt is emitted, no model response is expected, and the CLI proceeds directly to the transition. This is useful for **pure routing gates** — steps that exist solely to branch the workflow based on store or params, without requiring model reasoning: ```typescript .step('route', { // No prompt, no response — pure routing gate next: ({ params, store }) => store.steps.diagnose.issues.length > 0 ? 'remediate' : 'report', }) ``` Combine with response-less (no `response` schema) for the lightest-weight step: no prompt emitted, no schema emitted, no validation, no LLM call. The engine evaluates `next` and moves on. #### Response-less steps When `response` is omitted from a step config, no `` block is emitted in the prompt and validation is skipped. The model's response is not parsed or validated — it passes through as-is. This is useful for free-form steps where the model produces prose (e.g., a final report or user-facing message) and the workflow doesn't need structured data from the response: ```typescript .step('present-report', { prompt: ({ store }) => `Present the findings to the user in a clear, readable format.`, // No response schema — model response is unstructured next: terminal, }) ``` When combined with a prompt-less step (omitting both `prompt` and `response`), the result is a pure routing gate that requires no LLM interaction at all. --- ## 3. Transitions ```typescript import { terminal } from '@contentful/skill-kit'; // Static step({ next: 'report' }); // Conditional (response-based) step({ next: ({ response }) => (response.checks.some((c) => c.status === 'fail') ? 'remediate' : 'report'), }); // Conditional (actionResult-based) step({ action: { run: apiAction }, next: ({ actionResult }) => (actionResult.status === 200 ? 'success' : 'retry'), }); // Terminal (constant shorthand) step({ next: terminal }); // Terminal (object literal — equivalent) step({ next: { terminal: true } }); // Bounded loop step({ next: ({ response, attempts }) => (response.confidence < 0.7 && attempts < 3 ? 'self' : 'report'), maxVisits: 3, onMaxVisits: 'report', // required fallback }); // Declarative branching (NextBranch[]) step({ next: [ { to: 'ask-stack', when: ({ response }) => response.role === 'dev' }, { to: 'ask-tools', when: ({ response }) => response.role === 'designer' }, { to: 'ask-specialty' }, // fallback — no condition ], }); ``` The `terminal` constant is exported from `@contentful/skill-kit` and is equivalent to `{ terminal: true }`. Use whichever form reads better. Cycles detected by the graph analyzer apply an implicit visit limit (10) at runtime. Declaring `maxVisits` + `onMaxVisits` provides explicit control: `onMaxVisits` redirects when the limit is hit, while `maxVisits` without `onMaxVisits` throws (fail-closed). Linear workflows with function-based `next` don't need cycle guards — the conservative graph analysis handles safety automatically. ### The `next` callback When `next` is a function, it receives the following fields: | Field | Description | | -------------- | --------------------------------------------------------------------------- | | `response` | The validated response of this step (typed by the step's `response` schema) | | `actionResult` | The action's result, if an action was configured (typed by action's schema) | | `attempts` | How many times this step has been visited (for bounded-loop patterns) | | `params` | Skill params — the external data passed at invocation | | `store` | State accessor — step results via `store.steps.*`, sub-stores via `store.*` | ### Declarative branching (`NextBranch[]`) When `next` is an array of `NextBranch` objects, the engine evaluates each branch's `when` predicate in order and takes the first match. The last entry may omit `when` to serve as a fallback. Each `when` predicate receives the same fields as the `next` function: `{ response, actionResult, params, store, attempts }`. This is the preferred form for multi-way branching — it's readable, declarative, and the builder uses it to track which downstream steps are branch targets (optional in the store) vs guaranteed. --- ## 4. Rendering (deterministic output) The pattern that sold the PRD: structured model output → code-rendered artifact → model pastes verbatim. The `view()` helper wraps content in a `ViewSegment` that renders as a `` XML tag. It is a prompt composition helper — use it inside prompt callbacks to inject pre-rendered content inline. ```typescript import { step, view, render, prompt, terminal } from '@contentful/skill-kit'; step({ prompt: ({ store }) => { const diagnose = store.steps.diagnose; const table = render.table(diagnose.checks, { columns: ['name', 'status', 'detail'], statusIcons: { pass: '✅', fail: '❌', warn: '⚠️' }, }); return [ view('report', table), prompt` Output the report above to the user exactly as shown, with no preamble or trailing commentary. `, ]; }, response: type({ delivered: 'boolean' }), next: terminal, }); ``` The `view()` function has two signatures: - `view(content)` — wraps content in an unnamed `` tag - `view(label, content)` — wraps content in a named `` tag Named views help the model reference specific rendered blocks when a prompt contains multiple views. ### Built-in renderers A small, opinionated set. Authors can write their own any time. - `render.table(rows, opts)` — markdown tables with consistent styling - `render.checklist(items)` — `- [x]` / `- [ ]` lists - `render.diff(before, after)` — unified diffs - `render.code(source, lang)` — fenced blocks - `render.kv(pairs)` — aligned key/value blocks - `render.section(title, body)` — headers + body Custom renderers are just `(args) => string`. No registration; anything returning a string works. --- ## 5. References (external files) Skills often ship supporting docs. The existing `references/` convention stays. The SDK exposes them as lazy loaders so they don't bloat every prompt. ``` skills/repo-doctor/ ├── skill.ts ├── references/ │ ├── ci-providers.md │ ├── security-checklist.md │ └── severity-rubric.md └── assets/ └── schema.json ``` ```typescript step({ prompt: ({ refs, store }) => { const gather = store.steps.gather; return prompt` Classify each finding's severity using this rubric: ${refs.load('severity-rubric.md')} Findings: ${JSON.stringify(gather.findings)} `; }, }); ``` `refs.load()` reads from `references/` relative to the skill file and inlines the content. Resolved at prompt-build time, not skill-load time — conditional steps don't pay for references they never use. ### Asset references `refs.asset(path)` returns an absolute path for files the CLI or a prompt callback needs on disk (schemas, templates, images). ### Reference lints - All files under `references/` must be referenced by at least one step. Orphans fail `skill check`. - Circular fragment includes fail to load. - Reference files over 8KB emit a warning suggesting split or on-demand loading. --- ## 6. Modularization Three patterns, in increasing weight. ### A. Shared schemas and fragments Plain TS imports. No ceremony. ```typescript // shared/schemas.ts export const CheckResult = type({ /* ... */ }); // In a skill: import { CheckResult } from '../../shared/schemas'; ``` ### B. Reusable step definitions `step()` creates standalone, portable steps. Use `__parent__` for the transition and `.extend()` on the builder to wire them in with typed overrides. ```typescript // shared/steps/gather-repo-facts.ts export const gatherRepoFacts = step({ prompt: "Inspect the repo and list languages, build tools, CI config.", response: RepoFactsSchema, next: "__parent__", // transition decided by importing skill }); // In a skill — .extend() applies typed params/store to overrides: skill({ params: ParamsSchema, ... }) .extend("gather", gatherRepoFacts, { prompt: ({ params }) => `Inspect ${params.repoPath}`, // typed ✓ next: "analyze", }) ``` ### C. Modules (composable step groups) For groups of steps that belong together and have their own store scope. Modules can't access the parent skill's params — this enforces portability. ```typescript import { module, type } from '@contentful/skill-kit'; export const authModule = module({ name: 'auth', entry: 'auth-login', }) .step('auth-login', { prompt: 'Ask for credentials.', response: type({ userId: 'string' }), next: '__parent__', }) .build(); ``` Register into a skill with `.register()`. The module's `__parent__` exit is wired to the `next` target, and store types merge via intersection: ```typescript skill({ ... }) .step("start", { ..., next: "auth-login" }) .register(authModule, { next: "dashboard" }) .step("dashboard", { // store has auth-login results available prompt: ({ store }) => `Welcome ${store.steps['auth-login'].userId}`, ... }) .build(); ``` **Opinion:** Modules are for groups of steps that are reused across skills with their own state. Most composition needs are met by shared steps + `.extend()`. ### D. Composite skills (sub-skills and topics) When related skills share references, params, or user-facing scope, they can be combined into a single composite skill. A composite is a regular `skill()` that has sub-skills and/or topics registered on it. ```typescript import { skill, type, act } from '@contentful/skill-kit'; import doctorSkill from './subskills/doctor.js'; import setupSkill from './subskills/setup.js'; export default skill({ name: 'contentful-help', entry: 'classify', params: type({ query: 'string' }), }) .step('classify', { prompt: ({ params }) => `Classify intent: "${params.query}"`, response: type({ intent: 'string', confidence: 'number' }), next: ({ response }) => { if (response.confidence < 0.7) return 'clarify'; return `subskill:${response.intent}`; }, }) .step('clarify', { /* ask user, then route */ }) .topic('rate-limits', { label: 'API rate limits', content: ({ refs }) => refs.load('rate-limits.md'), }) .subskill('doctor', doctorSkill, { params: (_output, store) => ({ spaceId: store.steps['get-space']?.spaceId ?? '' }), }) .subskill('setup', setupSkill) .build(); ``` **Sub-skills** are standalone `SkillDefinition`s imported and registered via `.subskill(name, def, opts?)`. They have independent state machines, stores, and params. They can be developed and tested independently with `runSkill()`. **Topics** are reference entries registered via `.topic(name, config)` — same as on `reference()`. They can be resolved as dispatch targets or looked up directly via CLI. #### Routing Any step's `next` can return special prefixed targets to exit the dispatcher: - `'subskill:doctor'` — transitions into the `doctor` sub-skill. The engine returns a `RedirectResult` (the target doesn't exist in the local step map). The composite entry point intercepts the redirect, calls the sub-skill's `paramsMap` to produce params, and starts the sub-skill's engine. - `'topic:rate-limits'` — resolves the topic and returns its content as a `DoneResult`. - Regular step names route within the dispatcher as normal. The dispatcher is a full state machine — it can have as many steps as needed before routing (classify, triage, gather context, ask clarifications). #### Params mapping Each `.subskill()` registration accepts an optional `params` function: ```typescript .subskill('doctor', doctorSkill, { params: (_output, store) => ({ spaceId: store.steps['get-space']?.spaceId ?? '' }), }) ``` The function receives the response of the step that triggered the redirect and the dispatcher's store accessor. It returns the params object for the sub-skill's engine. #### Step name namespacing Sub-skill step names are prefixed with `subskillName/` at the protocol layer: - Dispatcher steps: `classify`, `clarify` (no prefix) - Sub-skill steps: `doctor/diagnose`, `setup/configure` Engines never see prefixes — the composite entry handles prefixing/unprefixing. #### CLI protocol All commands go through `scripts/run`: ```bash scripts/run --params '{...}' # dispatcher start scripts/run advance --step classify --output '{...}' # dispatcher advance scripts/run advance --step doctor/diagnose --output .. # sub-skill advance scripts/run doctor --params '{...}' # direct sub-skill start scripts/run topics # list reference topics scripts/run topic rate-limits # load a topic ``` #### Constraints - **No nesting**: `.subskill()` throws at runtime if the sub-skill definition already has subskills. - **No `/` in dispatcher step names**: the slash is reserved for namespacing. - **Sub-skills share references**: one `references/` directory, one `ReferenceLoader`. **Difference from modules:** Modules flatten into the parent's step namespace and merge store types. Sub-skills are independent — isolated store, own entry points, testable standalone, invokable as CLI subcommands. --- ## 7. Params and state ### Skill params Declared on the skill, validated on invocation, typed everywhere. Params are the external data passed to the skill at invocation time — the skill's "arguments." ```typescript skill({ params: type({ repoPath: 'string = "."', strictness: "'lenient' | 'normal' | 'strict' = 'normal'", }), // ... }); ``` > **Why "params" and not "context"?** "Context" is overloaded — callback context, execution context, prompt context, workflow context. "params" clearly identifies the external data passed to the skill at invocation, making it easy to distinguish from internal workflow state like the store. ### The store The store has two namespaces: `store.steps.*` for step-keyed results, and top-level `store.*` for named sub-stores declared via the `stores` config. The type system tracks which entries are guaranteed (on all paths) vs optional (branch targets or unwritten sub-store paths) — computed automatically from your declarations. ```typescript // Step results live under store.steps store.steps.greet.name; // guaranteed step — non-optional store.steps['ask-stack']?.answer; // branch target — optional store.steps.all('ask-hobby'); // loop visits store.steps.ran('ask-stack'); // boolean check store.steps.history; // raw records // Sub-stores live at the top level store.environment?.apiA?.host; // sub-store — optional until narrowed ``` Skills can declare named sub-stores for domain-structured state that doesn't belong to any single step. Sub-stores are typed by their schema and accessed at the top level of `store` (everything outside `steps`): ```typescript skill({ stores: { environment: type({ apiA: { host: 'string', key: 'string' } }), }, }); ``` Steps write to sub-stores via the `save` callback (see below). Sub-store writes are deep-merged — each step can contribute a slice without overwriting the rest. The store is available in prompt callbacks, `next` callbacks, `save` callbacks, and `action.mapInput` callbacks. It provides typed access to step results and sub-store state based on what the builder has accumulated — no manual annotations needed. There is no `updateState`, no `setState`, no reducers, no manual wiring. Step results flow into the store automatically. ### The `save` callback The `save` callback routes data to the store. It returns an object where the `step` key sets the step-keyed result (stored under `store.steps.`) and other top-level keys write to named sub-stores (deep-merged). By default — when `save` is omitted — the step-keyed result is the `response` (or `actionResult` if the step has an action). ```typescript .step('write-report', { response: type({ title: 'string', body: 'string' }), action: { run: saveReport }, save: ({ response, actionResult }) => ({ step: { title: response.title, path: actionResult.path, bytes: actionResult.bytes, }, }), next: 'confirm-publish', }) ``` Later steps access the transformed result via `store.steps['write-report']?.path`, not the raw response or action result. The priority for step results: explicit `save().step` > action output > response. Sub-store writes use the same callback — top-level keys matching declared store names are deep-merged into the corresponding sub-store: ```typescript save: ({ actionResult }) => ({ environment: { apiA: { host: actionResult.host } }, }); ``` A single `save` callback can write to both the step store and sub-stores simultaneously. The `save` callback receives `{ response, actionResult, store, params }` — the step's validated response, the action's result (if any), the current store accessor, and the skill params. ### Store type narrowing The builder tracks which steps are guaranteed (on all paths to the current step) vs optional (branch targets). This flows into the `StoreView` type: - **Guaranteed steps** appear as required properties: `store.steps.greet.name` (no `?.` needed) - **Branch targets** appear as optional properties: `store.steps['ask-stack']?.answer` (must use `?.`) - **Methods** are always available: `store.steps.all(stepName)`, `store.steps.ran(stepName)`, `store.steps.history` The guarantee tracking extracts branch targets from both `NextBranch[]` arrays (via the `to` fields) and function `next` (via the inferred literal return type — e.g., `() => response.ok ? 'a' : 'b'` infers as `() => "a" | "b"`, yielding targets `'a' | 'b'`). When a step's `next` produces multiple forward targets, those targets become optional. When there's only one forward target (others are backward edges to already-defined steps), it remains guaranteed. Sub-store narrowing follows a similar principle. When a guaranteed predecessor writes to a sub-store via `save`, those paths become non-optional downstream — the type system knows the data is present. Branch target writes remain optional, since the writing step may not have run. ### Type system scaling The builder's type narrowing is computed at compile time via generic accumulators. Each `.step()` call adds an intersection layer to `TSteps` and updates `BranchState`/`GuaranteeState`. The practical limits: | Dimension | Tested up to | Notes | | ------------------------------------ | ------------------------------------------------------- | ------------------------------------------------------------------------ | | Linear chain (sequential steps) | 300 steps in ~24s, 500 in ~108s | The only bottleneck. Each step adds an intersection layer to `TSteps`. | | Branch width | 100-way branch in <6s | Union extraction and reconvergence checking scale linearly. | | Independent branches | 20+ branch points in <4s | `BranchState.groups` record accumulates cheaply. | | Reconvergence cycles | 30 branch-reconverge pairs in <4s | Template literal edge tracking handles large edge sets. | | Sub-store nesting depth | 10 levels in <4s | `DeepPartial`/`DeepReadonly` traverse schema shape, not the accumulator. | | Combined (branches + stores + saves) | 15 steps, 3 branches, 2 reconvergences, 2 stores in <5s | Representative real-world skill. | The only practical limit is the linear step chain depth, because TypeScript must resolve the accumulated intersection type `{} & { s01: T1 } & { s02: T2 } & ...` at each step. Real-world skills rarely exceed 20 steps, so the ~300-step wall is a non-issue. Branches, reconvergence, and sub-stores add negligible overhead. A stress test generator is available at `scripts/stress-test-gen.ts` for reproducing these measurements. ### No globals, no mutation Steps receive inputs, return outputs. The store is append-only. Load-bearing for determinism and replay. ### Terminal output (for programmatic consumers) A skill can declare a schema for its final result, independent of what any individual step produces. This is the skill's "return value" when invoked programmatically. ```typescript skill({ name: 'repo-doctor', entry: 'diagnose', finalOutput: type({ passed: 'boolean', checks: CheckResult.array(), reportPath: 'string', }), // ... }); ``` The last step before termination must produce a response matching the `finalOutput` schema — either directly, or via its action's result. The CLI surfaces this to the invoker when the workflow reaches a terminal state. **Why this matters for interop.** Skills aren't always invoked from a chat surface. A programmatic consumer — for example, a larger agent built with the Claude Agent SDK — might invoke a skill and want its result as structured data. The Agent SDK's `query()` has an `outputFormat: { type: 'json_schema', schema }` option that serves the same purpose at the agent level; our skills expose the equivalent at the skill level, using ArkType schemas that compile to JSON Schema. A consumer calling our skill programmatically via `runSkill()` (see §9) gets the validated final output typed by the `finalOutput` schema. A consumer invoking the skill from within an Agent SDK session gets the same data serialized into the agent's transcript. If `finalOutput` is omitted, the skill's terminal output defaults to the last step's response — useful for quick prototypes, but programmatic consumers will want the explicit schema for stable integration. --- ## 8. Side effects and observers The SDK has two primitives for things that happen around a step: **actions** (which _do_ things) and **observers** (which _watch_ things). They're in the same section because both attach to a step's lifecycle, but they're deliberately different in intent and power. ### Actions Steps are pure: inputs in, outputs out, transition declared. When a skill needs to _do_ something — write a file, call an API, spawn a subprocess — it declares an **action**. An action is **node-side plumbing**, not a tool. The distinction matters. - A **tool**, in the agent-host sense (Read, Edit, Bash, AskUserQuestion), is something the model decides to call. The model reasons, picks a tool, provides arguments, the host executes, the result goes back into the model's context. - An **action** is something **the CLI runs deterministically** after a step's response is validated. The model never chooses it. The workflow declares when it runs and with what inputs. The model's only role is producing the step response that parametrizes the action. Actions are how skills do things; tools are how agents do things. They don't share a surface. ```typescript import { writeFile } from 'node:fs/promises'; import { action, type } from '@contentful/skill-kit'; const writeReport = action({ name: 'write-report', input: type({ path: 'string', content: 'string' }), output: type({ bytesWritten: 'number' }), run: async ({ input, signal }) => { await writeFile(input.path, input.content); return { bytesWritten: input.content.length }; }, }); step({ prompt: 'Decide where to write the report and what it should contain.', response: type({ path: 'string', content: 'string' }), action: { run: writeReport }, // runs CLI-side after validation, before transition next: 'confirm', }); ``` **Decoupling action input from step response** — when the model's reasoning response doesn't match what the action needs, use `action.mapInput` to transform: ```typescript step({ response: type({ reasoning: 'string', fileName: 'string', body: 'string' }), action: { run: writeReport, mapInput: ({ response, store, params }) => ({ path: `${store.steps['setup']?.outDir ?? '.'}/${response.fileName}`, content: response.body, }), }, save: ({ response, actionResult }) => ({ step: { fileName: response.fileName, bytesWritten: actionResult.bytesWritten, }, }), next: ({ actionResult }) => (actionResult.bytesWritten > 0 ? 'confirm' : 'retry'), }); ``` **Inline actions** — when the action is specific to one step and doesn't need to be reused, pass a function directly instead of an object with `run`: ```typescript step({ response: type({ url: 'string' }), action: async ({ response, store, params, signal }) => { const data = await fetch(response.url); return { status: data.status }; }, save: ({ actionResult }) => ({ step: { status: actionResult.status } }), next: 'report', }); ``` Inline actions receive the full step context — `{ response, store, params, signal }` — with no schemas, no name, and no input mapping needed. The return type is inferred and flows into `actionResult` in `save`, `next`, and the store. Like reusable actions, inline actions are not re-executed during replay: the persisted `actionResult` is passed directly to `save`. The discriminant is `typeof action === 'function'` (inline) vs an object with a `run` property (reusable). **`action.mapInput`** receives `{ response, store, params }` — the step's validated response, the store accessor, and the skill params. Use it to transform the model's response into the shape the action expects. Only applicable to the reusable action form. **The `save` callback** runs after the action completes (or after response validation if no action exists), receiving `{ response, actionResult, store, params }`. Its return value routes data to the store: the `step` key is stored under `store.steps.`, and other keys write to named sub-stores via deep merge. When `save` is omitted, the step-keyed result defaults to the action result (if an action exists) or the response. The lifecycle of a step with an action depends on the form: - **Inline action:** prompt → model → validate(response) → action(ctx) → save → next - **Reusable action:** prompt → model → validate(response) → action.mapInput → action.run → save → next Actions accept an `AbortSignal` so long-running operations can be cancelled cleanly when the skill is interrupted. **Why not let the model call tools instead?** Because when the effect is deterministic and workflow-mandated, running it CLI-side gives replayability, auditability, and no reliance on the model executing reliably. The model still has access to all of the host's tools for exploration during a step — that hasn't changed. Actions are for things the workflow says must happen, not things the model might choose to do. Actions are declared alongside their step and have typed input/output schemas, making them auditable and diffable. ### Observers Observers are read-only callbacks the SDK fires at specific lifecycle points. They're for cross-cutting concerns — logging, telemetry, audit trails, wiring skills into external observability. They receive a frozen snapshot of the relevant state and return nothing. They cannot change what the workflow does. ```typescript skill({ // ... observers: { onStepStart: ({ step, params }) => { logger.info({ step: step.name, skill: 'repo-doctor' }, 'step started'); }, onStepComplete: ({ step, response, durationMs }) => { metrics.histogram('skill.step.duration', durationMs, { step: step.name }); }, onStepValidationFailed: ({ step, raw, error, attempt }) => { logger.warn({ step: step.name, attempt, error }, 'validation failed'); }, onTransition: ({ from, to, reason }) => { audit.record({ from, to, reason, timestamp: Date.now() }); }, onSkillComplete: ({ path, finalOutput, durationMs }) => { metrics.increment('skill.completed', { skill: 'repo-doctor' }); }, }, }); ``` Available observer events, deliberately kept to five: | Event | Fires when | | ------------------------ | -------------------------------------------------------------------- | | `onStepStart` | Before the step's prompt is emitted to the model | | `onStepComplete` | After the step's response is validated (and action, if any, has run) | | `onStepValidationFailed` | When the model's response doesn't match the schema (before retry) | | `onTransition` | When the CLI routes from one step to another, including terminal | | `onSkillComplete` | When the skill reaches a terminal state, successfully or otherwise | **Observers do not mutate state.** If you need to transform data between steps, declare a step or an action — the transformation belongs in the workflow, not hidden in an observer. This is load-bearing: observers that mutate create non-local data flow that breaks replay and makes skills hard to reason about. **Observers are not interceptors.** Some systems (notably the Claude Agent SDK's `PreToolUse`/`PostToolUse` hooks) allow callbacks to block or alter tool calls. We intentionally don't expose that. Those concerns belong to the agent host, which we don't run. An observer can log that a step failed; it cannot prevent a step from running or change what prose the model sees. **Observers can be async**, but they should be fire-and-forget from the CLI's perspective. A slow observer doesn't block the workflow; the SDK queues them. If an observer throws, the error is logged but the skill continues — observers cannot bring down a skill run. The word choice is deliberate: "observers," not "hooks." Hooks imply leverage; observers imply telescopes. If you need to intervene in the workflow, that's what steps and actions are for. --- ## 9. Testing ```typescript // skill.test.ts import { test, runSkill, mockModel } from '@contentful/skill-kit/test'; import doctor from './skill'; test('routes to remediate when checks fail', async () => { const result = await runSkill(doctor, { params: { repoPath: './fixtures/broken-repo' }, model: mockModel({ diagnose: { checks: [{ name: 'ci', status: 'fail', detail: '...' }] }, remediate: { remediations: [{ check: 'ci', action: 'add .github/workflows/ci.yml' }] }, }), }); expect(result.path).toEqual(['diagnose', 'remediate', 'report']); expect(result.response).toMatchSnapshot(); }); ``` `mockModel` takes either a map of step → canned response or a function. --- ## 10. Runtime / CLI invocation protocol The compiled skill binary is invoked by agents via Bash — one call per step. Each call is stateless; the agent passes the full conversation history on every invocation. JSON output goes to stdout, diagnostics and errors to stderr. ### Subcommands **`start`** (default) — Begin the workflow. Returns the first step's prompt and schema. The `start` subcommand is implicit — omitting it defaults to `start`, so agents see `run *` as the base permission pattern. ```bash ./scripts/run --params '{"repoPath":"."}' --host claude-code ``` ```json { "kind": "prompt", "step": "diagnose", "prompt": "Inspect the repository and report failed health checks.", "schema": {...} } ``` **`advance`** — Submit a step's response and get the next prompt (or done signal). ```bash ./scripts/run advance \ --step diagnose \ --output '{"checks":[{"name":"ci","status":"fail","detail":"no CI config found"}]}' \ --history '[{"step":"diagnose","output":{"checks":[...]}}]' \ --host claude-code ``` ```json { "kind": "prompt", "step": "remediate", "prompt": "Fix these issues...", "schema": {...} } ``` **Terminal response:** ```json { "kind": "done", "done": true, "finalOutput": {...} } ``` **Validation error:** ```json { "kind": "error", "error": "validation", "step": "diagnose", "message": "Expected object, received string", "retry": true } ``` All CLI result types carry a `kind` field that serves as a discriminant for the `CliResult` union: `'prompt'`, `'done'`, `'error'`, or `'redirect'`. The SDK exports type guard helpers (`isPrompt`, `isDone`, `isError`, `isRedirect`) for narrowing. ### Flags | Flag | Required | Description | | --------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `--params` | On `start` | JSON string. Validated against the skill's params schema. | | `--step` | On `advance` | Name of the step whose response is being submitted. Not needed with `--session` in file mode. | | `--output` | On `advance` | JSON string. The agent's response for the step. Not needed with `--session` in file mode. | | `--history` | On `advance` | JSON array of `{"step": string, "output": unknown}` objects. Full conversation history. Not needed with `--session`. | | `--host` | Optional | Host identifier for tool resolution. Defaults to `generic`. Known values: `claude-code`, `codex`, `opencode`, `gemini-cli`, `cline`, `roo-code`, `kilo-code`, `cursor`, `amp`. | | `--tools` | Optional | Comma-separated list of available tools (merged with host registry; authoritative with `--subagent`). E.g., `--tools AskUserQuestion,EnterPlanMode,TaskCreate,Agent`. | | `--subagent` | Optional | Boolean flag. Indicates a subagent with a genuine tool subset — `--tools` becomes authoritative (no registry merge). | | `--session` | Optional | `new` to create a session (start), or session ID (advance). See [Session protocol](#session-protocol-file-based). | | `--session-dir` | Optional | Directory for session files. Default: OS temp directory. | | `--output-mode` | Optional | `file` (default) or `flag`. How the agent passes step output. Only on start with `--session new`. | | `--help` | — | Print usage to stderr, exit 0. | ### Statelessness Each invocation reconstructs the workflow engine from the skill definition + history. The binary replays history to rebuild the store (visit counts, step results, etc.) without re-executing actions or observers. This is cheap — history is data, not re-execution. This design means no persistent process, no stdin piping, and no reliance on the agent managing a subprocess lifecycle. The agent makes sequential Bash calls and parses JSON output — a pattern every agent host supports today. ### Composite CLI protocol Skills with registered sub-skills and/or topics accept additional commands. All go through `scripts/run` (hosts grant `scripts/run *` via "Always allow"). **Direct sub-skill access** — bypass the dispatcher and start a sub-skill directly: ```bash ./scripts/run doctor --params '{"spaceId":"abc"}' --host claude-code ./scripts/run doctor advance --step diagnose --output '{...}' --history '[...]' ``` **Reference topics** — list or load topics: ```bash ./scripts/run topics # list all topics with labels ./scripts/run topic rate-limits # load topic content to stdout ``` **Namespaced step names** — sub-skill steps are prefixed at the protocol layer. The host sees `doctor/diagnose` in the `step` field and passes it back on `advance`. The composite entry strips the prefix before routing to the sub-skill engine. **RedirectResult** — when the dispatcher's `next` resolves to `subskill:` or `topic:`, the engine returns a `RedirectResult` (the target doesn't exist in the local step map). The composite entry intercepts this and either starts the sub-skill or loads the topic. The host never sees `RedirectResult` — it receives the sub-skill's first `PromptResult` or a `DoneResult` with topic content. ### Script design conventions The binary follows the [agentskills.io script design conventions](https://agentskills.io/specification): - Non-interactive (no TTY prompts) - `--help` for discoverability - JSON to stdout, diagnostics to stderr - `--long-name` flags only - Non-zero exit on failure with descriptive error messages ### Session protocol (file-based) The stateless protocol works but produces noisy UX — every invocation dumps verbose JSON to stdout (visible in the agent's Bash tool output), and the `--history` flag grows with every step. The session protocol is an opt-in alternative that moves protocol data to a temp file. **Creating a session:** ```bash ./scripts/run --params '{"repoPath":"."}' --host claude-code --session new ``` Returns a `SessionPointer` to stdout: ```json { "sessionId": "abc123", "file": "/tmp/skill-kit-abc123.jsonl", "line": 2 } ``` The session file is JSONL. Line 1 is the header; line 2 is the first prompt. **Session JSONL format:** | Line type | `type` field | Description | | --------- | ------------ | ----------------------------------------------------------------------------------- | | Header | `header` | Session metadata: `sessionId`, `skill`, `host`, `params`, `createdAt`, `outputMode` | | Prompt | `prompt` | Step prompt with `step`, `prompt`, `schema`, optional `preamble` and `completed` | | Output | `output` | Agent's step response: `step`, `output` | | Done | `done` | Terminal: `done: true`, `finalOutput`, `completed` | | Error | `error` | Validation error: `error`, `step`, `message`, `retry` | Example session file: ```jsonl {"type":"header","sessionId":"abc123","skill":"doctor","host":"claude-code","params":{},"createdAt":"2026-04-22T10:00:00Z","outputMode":"file"} {"type":"prompt","step":"diagnose","prompt":"Inspect the repo...","schema":{...},"preamble":"..."} {"type":"output","step":"diagnose","output":{"checks":[...]}} {"type":"prompt","step":"remediate","prompt":"Fix these...","schema":{...},"completed":{"step":"diagnose","output":{...}}} {"type":"output","step":"remediate","output":{"fixed":true}} {"type":"done","finalOutput":{"fixed":true},"completed":{"step":"remediate","output":{...}}} ``` **Output modes** — how the agent passes its step output back: - **`file` (default):** The agent appends a `{"type":"output","step":"","output":{...}}` line to the JSONL file, then calls `advance --session ` with no `--step` or `--output` flags. The CLI reads the last output line from the file. - **`flag`:** The agent passes `--step --output '{...}'` on the advance call. The CLI writes the output line to the file itself. Set via `--output-mode flag` at session creation. **Advancing with a session:** ```bash # file mode (default) — agent already appended output line ./scripts/run advance --session abc123 # → stdout: 4 (line number of the next prompt/done) # flag mode — agent passes output as CLI args ./scripts/run advance --step diagnose --output '{...}' --session abc123 # → stdout: 4 ``` The line number tells the agent which line to read from the session file. **History reconstruction:** The CLI reads `completed` fields from `prompt` and `done` lines to rebuild the history array. This matches the existing `--history` format exactly. No `--history` flag is needed with `--session`. **Session flags:** | Flag | Description | | -------------------------- | ------------------------------------------------------------------- | | `--session new` | Create a new session (on `start`). Returns `SessionPointer`. | | `--session ` | Use existing session (on `advance`). Returns line number. | | `--session-dir ` | Override temp directory. Default: `os.tmpdir()`. | | `--output-mode file\|flag` | Set output mode (on `start` with `--session new`). Default: `file`. | **Composite skills and sessions:** One session spans the entire composite workflow. Subskill step names are prefixed in the session file (e.g., `doctor/diagnose`), same as in the stateless protocol. Direct subskill access (`./scripts/run doctor --session new`) creates a separate session for that subskill. **The `SessionPointer` type:** ```typescript interface SessionPointer { sessionId: string; file: string; line: number; } ``` --- ## 11. Build and distribution ### `skill-kit build` Produces a distributable, [agentskills.io](https://agentskills.io/specification)-compliant skill directory from a skill source file. ```bash skill-kit build src/skills/repo-doctor/skill.ts -o skills/repo-doctor ``` This: 1. Validates the skill definition (cycle guards, schema consistency) 2. Bundles the skill code (mode-dependent — see below) 3. Generates `scripts/run` shell wrapper (public interface) 4. Generates `SKILL.md` with invocation instructions 5. Generates `package.json` — name, version, and any fields from the `package` config. Merges with existing `package.json` in the output directory if present. When `resolveVersion: true` is set, reads the version from the nearest ancestor `package.json` instead of using the hardcoded `version` field. 6. Copies `references/` from the source directory ### Build modes The `--mode` flag selects the bundling strategy: | Mode | Flag | Output | Size | Requires | | ----------------- | ------------- | -------------------------------------- | -------------------- | ----------------------- | | **bun** (default) | `--mode bun` | Platform-specific compiled executables | ~50-100MB per target | `bun` installed | | **node** | `--mode node` | Single `.mjs` bundle | ~100-500KB | Node.js ≥ 24 at runtime | Node mode is the right choice for skills that live inside a Node.js codebase where Node is already available. Bun mode produces standalone executables that work without any runtime dependency. ### Protocol mode The `--protocol` flag controls which invocation instructions the generated SKILL.md contains: | Protocol | Flag | SKILL.md instructions | | --------------------- | ---------------------- | ---------------------------------------------------------------------------------- | | **session** (default) | `--protocol session` | File-based session protocol (see [Session protocol](#session-protocol-file-based)) | | **stateless** | `--protocol stateless` | Traditional `--history`-passing protocol | Session mode is the default and recommended choice — it produces cleaner agent UX and shorter Bash output. Use `--protocol stateless` only for hosts that cannot write to the filesystem (e.g., sandboxed environments where the agent has no Write/echo capability). The flag only affects the generated SKILL.md. The binary itself always supports both protocols — an agent can use `--session` or `--history` regardless of what the SKILL.md says. ### Output structure **Bun mode** (default): ``` skills/repo-doctor/ SKILL.md # Generated — agent reads this package.json # Generated — name, version scripts/ run # Shell wrapper — detects OS/arch, delegates to binary bin/ repo-doctor-darwin-arm64 # macOS Apple Silicon repo-doctor-linux-x64 # Linux x86_64 references/ # Copied from source severity-rubric.md ``` Default targets: `darwin-arm64` and `linux-x64`. Override with `--targets`. Use `--single` for fast dev builds (current platform only). **Node mode** (`--mode node`): ``` skills/repo-doctor/ SKILL.md # Generated — agent reads this package.json # Generated — name, version scripts/ run # Shell wrapper — checks Node ≥ 24, runs bundle bin/ repo-doctor.mjs # Single ESM bundle (all deps inlined) references/ # Copied from source severity-rubric.md ``` One bundle works on all platforms where Node.js ≥ 24 is available. No `--targets` or `--single` flags needed. ### The `scripts/run` wrapper Following [skill-dev conventions](https://github.com/TimBeyer/agent-skills/blob/main/skills/skill-dev/SKILL.md), the public interface is a shell wrapper in `scripts/` that delegates to `bin/`. The wrapper varies by build mode: **Bun mode** — detects OS and architecture, dispatches to the correct platform binary: ```bash #!/usr/bin/env bash set -euo pipefail SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" SKILL_DIR="$(cd "$SCRIPT_DIR/.." && pwd)" OS="$(uname -s | tr '[:upper:]' '[:lower:]')" ARCH="$(uname -m)" case "$ARCH" in x86_64) ARCH="x64" ;; aarch64|arm64) ARCH="arm64" ;; esac BIN="$SKILL_DIR/bin/repo-doctor-${OS}-${ARCH}" if [[ ! -x "$BIN" ]]; then echo "error: no binary for ${OS}-${ARCH}. Available:" >&2 ls "$SKILL_DIR/bin/" >&2; exit 1 fi exec "$BIN" "$@" ``` **Node mode** — checks Node.js version, sets `SKILL_DIR` env var for reference resolution, runs the bundle: ```bash #!/usr/bin/env bash set -euo pipefail SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" SKILL_DIR="$(cd "$SCRIPT_DIR/.." && pwd)" NODE_VERSION="$(node -e 'process.stdout.write(process.versions.node.split(".")[0])')" if [ "$NODE_VERSION" -lt 24 ] 2>/dev/null; then echo "error: Node.js >= 24 required" >&2; exit 1 fi export SKILL_DIR exec node "$SKILL_DIR/bin/repo-doctor.mjs" "$@" ``` `SKILL.md` references only `scripts/run` — never `bin/` directly. The wrapper decouples the skill's contract from its internal layout. ### Generated SKILL.md The build generates a SKILL.md with: - **Frontmatter:** `name`, `description`, optional `metadata.version`, and optional extension fields set via the `skill()` config — including `argument-hint`, `allowed-tools`, `paths`, `context`, `license`, `compatibility`, `agent`, `model`, `effort`, `disable-model-invocation`, `user-invocable`. The build always emits `allowed-tools` with at least `Bash(scripts/run *)`, `Read` (required for CLI mode), and the skill's MCP tool names (`mcp____start`, `mcp____advance`, plus `mcp____topic` and `mcp____topics` when topics exist); author-declared tools are merged with these defaults. - **Invocation instructions:** step-by-step pattern for the agent (start → advance loop → parse JSON → follow schema) - **Step descriptions:** each step's purpose (extracted from the skill definition) - **Reference pointers:** links to files in `references/` (loaded on demand) Authors customize via `skill.description` and optional `skill.skillMd` template override. For composite skills, the generated SKILL.md also includes: - A **Sub-skills** section listing available sub-skills with descriptions and direct-access commands - A **Reference topics** section listing topics with `scripts/run topics` and `scripts/run topic ` commands - Context-aware guidance: when a dispatcher exists, the SKILL.md tells the agent to start normally and let the workflow route; direct sub-skill access is presented as a fallback for explicit user requests ### The compile/bundle step The build generates a temporary entry point: ```typescript import skill from './skill'; import { main } from '@contentful/skill-kit/cli'; main(skill); ``` **Bun mode:** `bun build --compile` bundles everything — the SDK, ArkType, the skill code — into a single self-contained executable per target platform. **Node mode:** esbuild bundles the same dependency tree into a single `.mjs` file. All dependencies (SDK, ArkType) are inlined; only Node.js built-ins are external. The result is a portable ESM module that runs under `node`. **Composite skills** build identically — same `skill-kit build` command, same output structure. The build pipeline detects `def.subskills` and generates a wrapper calling `compositeMain` instead of `main`. No special flags or separate build step needed. --- ## 12. Repo layout for skill authors Source and built skills live in separate directories. `src/skills/` is where authors write TypeScript. `skills/` is the distribution output — every subdirectory is a valid, self-contained skill per the agentskills.io spec. ``` my-repo/ package.json # @contentful/skill-kit as devDep, build scripts src/ skills/ repo-doctor/ skill.ts # Skill definition (SDK code) skill.test.ts # Tests using runSkill() + mockModel() references/ # Reference docs (copied to output on build) severity-rubric.md deploy-helper/ skill.ts skill.test.ts skills/ # Build output — each subdir is a valid skill repo-doctor/ # Built by: skill-kit build src/skills/repo-doctor/skill.ts -o skills/repo-doctor SKILL.md package.json scripts/ run bin/ repo-doctor.mjs # --mode node (single bundle) # — OR for --mode bun: — # repo-doctor-darwin-arm64 # repo-doctor-linux-x64 references/ severity-rubric.md some-prose-skill/ # Traditional prose skills coexist SKILL.md package.json CLAUDE.md README.md ``` **Why the separation matters:** - `skills/` is the installation boundary. The `skills` CLI copies skill directories in isolation. Everything outside — source, tests, CI configs — stays out of the installed artifact. - `src/skills/` contains author code, tests, and source references. It's not distributed. - `SKILL.md` lives at the skill root as required by the agentskills.io spec. The directory name matches the `name` field. - Traditional prose skills and skill-kit skills coexist in `skills/` — both are valid skill directories. **Build wiring** in root `package.json`: ```json { "scripts": { "build": "skill-kit build src/skills/repo-doctor/skill.ts -o skills/repo-doctor", "build:all": "skill-kit build src/skills/*/skill.ts", "test": "node --test --import tsx/esm 'src/skills/**/*.test.ts'" } } ``` **Git distribution:** With `--mode node`, the `.mjs` bundles in `skills/*/bin/` are small enough to commit to git. With `--mode bun`, the compiled executables are large (50-100MB each) — add `skills/*/bin/` to `.gitignore` and build in CI instead. --- ## 13. What the SDK is opinionated about Non-negotiable, for good reasons: - **Schemas are ArkType.** One validator, one source of truth, native TS types. No pluggable schema systems. - **Prose is markdown.** Not JSX, not MDX, not templating DSLs. Portable, diffable, model-friendly. - **State is append-only.** No mutation of prior step results. The store is append-only. Enables replay. - **Cycles require explicit bounds.** No unguarded loops. - **Capabilities are declared, not discovered.** No runtime probing. - **Actions are declared, not inferred.** Any CLI-side side effect must exist as a named action. - **Steps are named string keys.** The state machine is inspectable as data, not reconstructed from closures. Author choices: - How many steps, how prose is decomposed, what schemas look like. - Whether to use fragments, references, sub-skills. - Tone, formatting, domain language. - Custom render helpers beyond the built-ins. --- ## 14. Cross-host capability model ### The architectural constraint (read this first) The skill CLI is a compiled binary invoked by the agent via Bash. The agent reads the generated `SKILL.md`, which instructs it to call `scripts/run start` and then `scripts/run advance` in a loop. The CLI returns JSON to stdout — including a `prompt` field containing prose the agent reads and acts on. The CLI cannot call tools. The CLI cannot invoke MCP methods. The CLI cannot cause the host to render UI. Only the model can do those things, and only in response to its own reasoning about what the text it just read is asking of it. So when the SDK wants the model to use `AskUserQuestion` on Claude Code, all it can actually do is return prose that names the tool and describes how to use it. The model reads the prose, decides to call the tool, and on its next turn the CLI sees the answer in whatever form the model passes it back. The shape of the answer is still enforced by the step's `response` schema — that's unchanged. What changes from a naive prose skill is _which prose_ gets emitted and _how reliably_ it steers the model. Everything in the rest of this section is downstream of that constraint. The primitives render XML tags; the preamble maps those tags to host-specific tools via a markdown table. The "capability system" is `resolveTools()` picking which tool name (if any) each primitive gets. There is no secret channel. ### Why primitives still matter Given that everything is prose, a reasonable question is: why not just let authors write the prose themselves? Three reasons, all load-bearing: **1. Centralized tuning.** "Ask the user which option they want" is a request. "Use the AskUserQuestion tool with these exact options, one answer per invocation, do not paraphrase the options" is a specification. The second is the prose that actually produces reliable behavior on Claude Code. Figuring it out takes iteration against real models. When the SDK owns that prose, one tuning pass benefits every skill. **2. Host portability without rewriting.** If an author hardcodes Claude Code's tool name in their skill, the skill breaks on Codex. If they abstract to a primitive, the SDK swaps the prose per host automatically. The author writes intent once; the SDK translates. **3. SDK improvements propagate.** This is the biggest argument. If six months from now someone finds a better way to phrase structured-question prose for Codex — fewer tokens, more reliable parsing, cleaner failure modes — the SDK ships the improvement and every skill using `askUser` gets it for free. No skill prose refactoring. The SDK becomes the place where prompt engineering compounds, instead of being re-done inside every skill by every author. That last point is the real pitch. Skills written against primitives inherit prompt-engineering work done in the SDK. Skills written as raw prose don't. ### Two mechanisms for steering the model The SDK has two levers for calibrated prose: **Preamble at session start.** When the CLI starts, it emits a one-time preamble that sets conventions for the session. The preamble is a markdown table mapping XML tags to tools: ``` You are following a structured workflow driven by a skill CLI. Each step provides a prompt and a JSON schema for the expected output. Follow the prompt instructions precisely and return output matching the schema. Step prompts use XML tags. Follow sections in the order they appear. | Tag | Tool | How to use | |-----|------|-----------| | `` | — | Behavioral directives. Follow as persona/tone guidelines. | | `` | — | Task instructions. The work to perform. | | `` | AskUserQuestion | Present `