cline-sdk

SKILL.md

Cline SDK Skill

Consolidated skill for building AI agents with the Cline SDK. Use the decision trees below to find the right entry point and API surface, then load detailed references.

Critical Rules

Follow these rules in all Cline SDK code:

Install with npm install @cline/sdk. The @cline/sdk package re-exports @cline/core, not every sub-package directly. Core re-exports the public SDK surface such as ClineCore, Agent, createAgentRuntime, createTool, built-in tool helpers, provider helpers, and the Llms namespace. Import from @cline/agents, @cline/llms, or @cline/shared only when you need APIs that core does not re-export, such as AgentRuntime, createAgent, or some low-level types.

Requires Node.js 22 or later.

Use createTool() from @cline/sdk (or @cline/shared) to define tools. Tool names must be snake_case.

Prefer returning structured error data from tool execute functions when the agent can recover. Direct Agent converts thrown tool errors into error tool results; ClineCore can also count repeated failed tool turns toward its mistake-limit handling.

Use lifecycle: { completesRun: true } on tools that should end the agent loop (e.g. a "submit answer" tool).

When using ClineCore, always call dispose() when done to clean up resources.

The direct Agent and ClineCore have different event systems. For Agent: use agent.subscribe() to get AgentRuntimeEvent types, text streaming is "assistant-text-delta", and result text is result.outputText. For ClineCore: use cline.subscribe() to get CoreSessionEvent types. Render user-facing text, reasoning, and tool activity from "agent_event" payloads (content_start, content_update, content_end, done). Treat "chunk" events as raw transport chunks with { stream, chunk, ts }, not as typed text deltas. ClineCore result text is result.text. There is no top-level onEvent field on AgentRuntimeConfig; use agent.subscribe() or hooks.onEvent instead. Do not use "content_update" or "content_start" with agent.subscribe(); those are host-facing AgentEvent types carried inside ClineCore agent_event events.

For direct Agent, plugins are simple runtime plugins with setup(context) returning { tools, hooks }. For ClineCore, extensions are AgentPlugin objects with manifest, setup(api, ctx), and optional hooks. Do not use ClineCore plugin examples inside direct Agent.plugins.

Plugin skills are file-based, not registered. There is no registerSkill() and no api.registerSkill. A plugin ships skills as SKILL.md files under <package>/skills/<name>/SKILL.md (package shape required); the host discovers them and surfaces them as /slash-commands automatically -- do not call registerCommand for skills. Plugin MCP servers use api.registerMcpServer() with the "mcp" capability. Configured agents (agent profiles) are YAML files in .cline/agents/ loaded as subagent_<name> tools when enableSpawnAgent is true.

How to Use This Skill