Getting Started

@contentful/skill-kit is a TypeScript SDK for building agent skills. Workflow skills are typed state machines — steps with prompts, ArkType schemas, and explicit transitions where the agent sees one step at a time. Reference skills are on-demand topic loaders for progressive disclosure of large docs. Composite skills combine multiple sub-skills and reference topics under a single dispatcher. All compile into self-contained packages that agents invoke via Bash.

Installation

Published to GitHub Packages. Configure your .npmrc first:

@contentful:registry=https://npm.pkg.github.com/

Then install:

pnpm add @contentful/skill-kit

Define a skill

A minimal two-step workflow skill:

import { skill, type, terminal } from '@contentful/skill-kit';

export default skill({
  name: 'greet',
  entry: 'ask',
})
  .step('ask', {
    prompt: 'Ask the user for their name.',
    response: type({ name: 'string' }),
    next: 'welcome',
  })
  .step('welcome', {
    prompt: ({ store }) => `Say hello to ${store.steps.ask.name}.`,
    response: type({ message: 'string' }),
    next: terminal,
  })
  .build();

skill() returns a builder. .step() adds steps with a prompt, an ArkType response schema, and a transition. .build() freezes the definition. The agent sees one step at a time, returns structured output matching the schema, and the skill decides what happens next.

The store gives every step typed access to all prior step results. In the welcome step, store.steps.ask.name is typed as string automatically — the SDK knows the ask step is guaranteed to have run before welcome, so the access is non-optional. No manual wiring, no null checks.

Run it without an agent

Use runSkill and mockModel to drive a skill through its steps in a test:

import { runSkill, mockModel } from '@contentful/skill-kit/test';
import greet from './skill.ts';

const result = await runSkill(greet, {
  model: mockModel({
    ask: { name: 'Alice' },
    welcome: { message: 'Hello, Alice!' },
  }),
});

// result.path    -> ['ask', 'welcome']
// result.response  -> { message: 'Hello, Alice!' }

mockModel maps step names to canned responses. runSkill drives the skill to completion and returns the full execution trace — path visited, outputs per step, and the final output.

Next steps