@agentskit/templates

Authoring toolkit for AgentsKit extensions — validated Tool, Skill, Adapter factories + secure on-disk scaffolds.

Authoring toolkit for generating AgentsKit extensions: validated ToolDefinition / SkillDefinition / AdapterFactory objects and on-disk scaffolds (package.json, tsup, tests, README). Depends only on @agentskit/core.

For full application starters, see agentskit init. @agentskit/templates is the lower-level programmatic toolkit for extension packages — it is not the implementation behind agentskit init.

#When to use

You publish custom tools, skills, adapters, memory, embedders, or flows as standalone packages.
You want consistent blueprints (tsup, vitest, TypeScript) across internal plugins.
You need runtime validation before registering a template with a runtime or marketplace.

#Install

npm install @agentskit/templates @agentskit/core

#Public API

Export	Role
`createToolTemplate(config)`	Build a `ToolDefinition` with validation
`createSkillTemplate(config)`	Build a `SkillDefinition` with validation + `metadata` passthrough
`createAdapterTemplate(config)`	Build an `AdapterFactory` + `name` + optional `capabilities`
`scaffold(config)`	Write a full package directory (async, atomic)
`validateScaffoldConfig(config)`	Validate scaffold input before write
`validateToolTemplate` / `validateSkillTemplate` / `validateAdapterTemplate`	Assert well-formed definitions
`SCAFFOLD_TYPES`	Tuple of the eight allowed types

#`createToolTemplate`

ToolTemplateConfig extends a partial tool with required name and optional description, schema (JSON Schema object), execute, tags, category, requiresConfirmation, init, dispose, and base merge.

import { createToolTemplate } from '@agentskit/templates'

export const rollDice = createToolTemplate({
  name: 'roll_dice',
  description: 'Roll an N-sided die once.',
  schema: {
    type: 'object',
    properties: { sides: { type: 'number', minimum: 2 } },
    required: ['sides'],
  },
  async execute(args) {
    const sides = Number(args.sides)
    return String(1 + Math.floor(Math.random() * sides))
  },
})

Validation throws if name/description are empty after trim, schema is not a plain object, or execute is not a function.

#`createSkillTemplate`

Requires name, description, and systemPrompt (trim non-empty). Optional: examples, tools, delegates, finite temperature, metadata, onActivate, base.

import { createSkillTemplate } from '@agentskit/templates'

export const researcher = createSkillTemplate({
  name: 'researcher',
  description: 'Gather facts before writing.',
  systemPrompt: 'You are a careful researcher. Cite sources when possible.',
  tools: ['web_search'],
  metadata: { team: 'research' },
})

#`createAdapterTemplate`

Requires non-empty name and createSource. Optional capabilities passthrough.

import { createAdapterTemplate } from '@agentskit/templates'

export const myAdapter = createAdapterTemplate({
  name: 'my-llm',
  capabilities: { tools: true, streaming: true },
  createSource: (request) => {
    throw new Error('Implement streaming to your backend')
  },
})

#`scaffold`

Creates a directory join(dir, name) with:

package.json, tsconfig.json, tsup.config.ts
src/index.ts (named-export stub — no default export in source)
tests/index.test.ts (contract tests)
README.md (+ flow.yaml for type: 'flow')

import { scaffold } from '@agentskit/templates'
import { join } from 'node:path'

const files = await scaffold({
  type: 'tool',
  name: 'my-company-search',
  dir: join(process.cwd(), 'packages'),
  description: 'Internal web search tool',
  // overwrite: false by default
})
console.log('Created:', files)

Security: config validated first; unscoped kebab-case names only; existing destinations fail unless overwrite: true; symlink destination roots rejected; sibling staging

atomic rename; cleanup on failure. Returned paths are final, not staging.

Dependencies generated: @agentskit/core ^1.0.0 always; flow also @agentskit/runtime ^0.10.0. No wildcards. No unused adapters/memory deps.

Scoped packages are not supported in this beta; a future minor may add them with an explicit migration.

#Troubleshooting

Error	Cause
`Tool name must be a non-empty string`	Pass a trim-non-empty `name`.
`requires a schema`	JSON Schema plain object required (not null/array).
`Skill ... systemPrompt`	Skills must define behavior via `systemPrompt`.
`Adapter ... createSource`	Factory must expose `createSource(request)`.
`Destination already exists`	Choose another name/dir or pass `overwrite: true`.
`Refusing to ... symlink`	Point `dir` at a real directory, not a symlink target name.
`not a safe unscoped npm package id`	Use kebab-case like `my-search` (no scopes yet).

#See also

Start here · Packages · TypeDoc (@agentskit/templates) · @agentskit/core · Tools · Skills · Adapters

#Stability

Tier: beta (hardened scaffold/validation surface; not yet stable)
Promotion path: RFC 0014
Contract: evolving under beta semver (breaking changes allowed in minors with CHANGELOG notes)

Explore nearby

✎ Edit this page on GitHub·Found a problem? Open an issue →·How to contribute →