Skills, commands and plugins

Package reusable instructions, explicit commands and session-local capability bundles.

For the TypeScript examples, use the TypeScript setup, including "type": "module" and the tsx runner. Use a skill for reusable instructions the model can load, a command for a prompt your application invokes explicitly, and an inline plugin to bundle related definitions. All three can be supplied programmatically without creating configuration files on the runtime host.

​

Run a namespaced command

Use the quickstart setup with OPENAI_API_KEY. Save this as commands.ts and run node --env-file=.env --import tsx commands.ts.

import { Agent, defineCommand, definePlugin, shutdown } from "cognitio-agent-sdk"

const editorial = definePlugin({
  name: "editorial",
  commands: [defineCommand({
    name: "review",
    description: "Rewrite one passage for clarity.",
    template: "Rewrite this passage in plain English, preserving its meaning: $ARGUMENTS",
  })],
})
const agent = new Agent({
  model: "openai/gpt-4.1-mini",
  plugins: [editorial],
  disallowedTools: ["*"],
  maxTurns: 2,
})
try {
  const session = await agent.createSession({ title: "Editorial review" })
  const result = await session.command("editorial:review", "Utilize the system to facilitate the operation.")
  if (result.subtype !== "success") throw new Error(`Command ended: ${result.subtype}`)
  console.log(result.text)
} finally {
  await agent.close().finally(() => shutdown())
}

An inline plugin namespaces its commands as plugin:command; here that is editorial:review. A command registered directly in Agent.commands keeps its own name. $ARGUMENTS is replaced by the argument string supplied to session.command().

Commands run a model turn in the existing session and return a terminal result. They can select an agent/model, apply tool restrictions or delegate as a subtask. They do not execute concurrently with another active query in that session.

​

Let the model load a skill

This separate example registers a skill directly. Its name is therefore plain-writing, without a plugin prefix.

import { Agent, defineSkill, shutdown } from "cognitio-agent-sdk"

const agent = new Agent({
  model: "openai/gpt-4.1-mini",
  skills: [defineSkill({
    name: "plain-writing",
    description: "Rewrite technical prose in clear, concrete language.",
    content: "Use short paragraphs. Replace vague verbs with concrete actions. Preserve the original facts.",
  })],
  allowedTools: ["skill"],
  maxTurns: 3,
})
try {
  const result = await agent.run(
    "Load plain-writing and rewrite: 'The utilization of this functionality facilitates better outcomes.'",
    { signal: AbortSignal.timeout(60_000) },
  )
  if (result.subtype !== "success") throw new Error(`Run ended: ${result.subtype}`)
  console.log(result.text)
} finally {
  await agent.close().finally(() => shutdown())
}

The facade hides skill by default, so enable it deliberately. A skill description helps the model decide whether to load its content; registration alone does not guarantee invocation. Optional fields include baseDir, allowedTools, model and disableModelInvocation. Setting disableModelInvocation prevents autonomous model invocation of that skill.

Skills provide instructions, not a trusted execution boundary. A model can still make mistakes, and application side effects need validation and permissions independent of prompt text.

​

Bundle related capabilities

An inline plugin can include skills, commands, agents, hooks and MCP descriptors. Skill, command and agent names receive the plugin namespace; inspect session.getAppliedSettings() for the effective configuration and diagnostics. Use unique plugin names within a session.

Programmatic definitions work with the SDK’s default empty settingSources. They are held in runtime memory, so re-register the intended definitions when resuming after a runtime restart. Persisting a transcript does not persist JavaScript callbacks or all runtime overrides.

​

Load a compatible local plugin

claudeCompat("/absolute/plugin/path") describes a supported local Claude-compatible plugin directory. This is an advanced compatibility path: it translates supported components, and unsupported components appear as diagnostics. It does not provide the Claude SDK API or guarantee every behavior of the original plugin. Paths refer to files the runtime can access; inspect diagnostics before relying on the plugin. Remote marketplace installation is outside v2.

Filesystem instruction and skill discovery is separately controlled by defaults and isolation and settingSources. You do not need to enable filesystem discovery to use the programmatic examples above.