| name | skawld-sdk-dev |
| description | Build and run AI agents with the Skawld Agent SDK (@skawld/agent-sdk), a TypeScript/Bun agent harness with tools, sessions, permissions, hooks, streaming events, MCP, skills, and subagents. Use this skill whenever the user is writing code against @skawld/agent-sdk, importing Agent/Session/AnthropicProvider/OpenAIResponsesProvider/defaultTools, embedding an agent loop into a Node or Bun app, wiring custom tools, permission callbacks, hooks (preToolUse/postToolUse/userPromptSubmit/stop/preCompact), the AskUser tool, MCP servers, skills, or subagents, streaming agent events, steering or interrupting a run mid-flight, persisting/resuming sessions, or asks "how do I build an agent with skawld". |
Skawld Agent SDK Development
Overview
The Skawld Agent SDK (@skawld/agent-sdk) is an open-source TypeScript agent harness for software-engineering tasks — a Claude Code-style agent loop you embed into any Node.js 18+ or Bun 1.1+ app with a single import. This skill teaches how to use the SDK (run an agent, stream events, persist sessions) and how to build with it (custom tools, permission callbacks, MCP servers, skills, subagents).
It is ESM-only. The core engine makes zero I/O assumptions — no console output, no terminal escapes inside the engine. The embedding app owns all I/O by consuming the event stream.
Scope: This skill handles building/using agents with @skawld/agent-sdk (the Skawld harness). It does NOT cover the Anthropic Claude API directly (use claude-api), the Claude Agent SDK from Anthropic (different package), generic MCP-server authoring (use mcp-builder), or non-skawld agent frameworks.
When to use
Trigger this skill when the user:
- Imports from
@skawld/agent-sdk, @skawld/agent-sdk/providers, /tools, /sessions, or /permissions.
- Constructs
new Agent({...}), calls agent.session(), or iterates session.run(prompt).
- Wires providers (
AnthropicProvider, OpenAIChatCompletionsProvider, OpenAIResponsesProvider).
- Builds custom tools, a
canUseTool permission callback, permission rules, MCP servers, skills, or subagents.
- Streams agent events, persists/resumes sessions, handles compaction, or handles SDK errors.
Package map
Import only from these four public subpaths (controlled via the exports map):
| Subpath | Exports |
|---|
@skawld/agent-sdk | Agent, Session, defaultTools, connectMcpServers, core types, Event types + isSubagentEvent/isHookErrorEvent, Hooks types, AskUserHandler types, error classes, CompactionStrategy |
@skawld/agent-sdk/providers | AnthropicProvider, OpenAIChatCompletionsProvider, OpenAIResponsesProvider, BaseProvider |
@skawld/agent-sdk/tools | ToolRegistry, defaultTools, built-in tool classes, MCP tool helpers, task types |
@skawld/agent-sdk/sessions | SqliteSessionStore, InMemorySessionStore, SessionStore + task persistence types |
@skawld/agent-sdk/permissions | PermissionEngine, CanUseTool callback types, permission rule types |
Official documentation
The canonical, always-current docs live at https://skawld.com/docs. The nav has three groups (mirrored here exactly). Link the user to the page that matches their question; each maps to a section in this skill's references, which carry the same 📖 Docs: page links.
Getting started
Concepts
Reference
Page order: Introduction → Install → Quickstart → Overview → Agent → Sessions → Events → Providers → Tools → MCP → Permissions → Skills → Subagents → Compaction → Errors → Configuration → Public API.
Quick start
import { Agent } from "@skawld/agent-sdk";
import { AnthropicProvider } from "@skawld/agent-sdk/providers";
import { defaultTools } from "@skawld/agent-sdk/tools";
const agent = new Agent({
provider: new AnthropicProvider(),
model: "claude-opus-4-5",
tools: defaultTools(),
permissions: { mode: "default" },
});
const session = await agent.session();
for await (const event of session.run("List the files in the current directory.")) {
if (event.type === "assistant") {
for (const block of event.message.content) {
if (block.type === "text") process.stdout.write(block.);
}
}
(event. === ) ;
(event. === ) { .(event..); ; }
}
agent.();
Install with bun add @skawld/agent-sdk (Bun recommended; npm/pnpm/yarn also work).
Core mental model
Agent = long-lived config: provider, model, tools, permissions, session store, MCP servers. Construct once.agent.session() = create or resume a conversation. On the FIRST call it lazily connects MCP servers, loads skills, loads subagents, and allocates the SQLite store. Pass { id } to resume a persisted session.session.run(prompt) = one user turn. Returns an AsyncIterable<Event>. The loop runs until the model stops calling tools, then emits a result event. Only one run can be active per session at a time (throws ConfigError otherwise).- Events are the only output channel — the engine never writes to a console. Consume them to render UI, log, or drive a CLI.
agent.close() releases resources. Always call it.
Task-based guidance
| Task | Where to look |
|---|
| Set up a consumer project (package.json, tsconfig, ESM, env) | references/project-setup.md |
Construct an Agent, all AgentOptions fields | references/api-reference.md → AgentOptions |
Run a turn, RunOptions (images, thinking, effort, temperature) | references/api-reference.md → Session & RunOptions |
| Handle every event type in the stream | references/api-reference.md → Event union |
| Pick/configure a provider; OpenAI-compatible endpoints (Ollama/vLLM/Groq) | references/api-reference.md → Providers |
| Built-in tools: exact params & scope; Task tools | references/tools-catalog.md |
Data shapes (Message, ContentBlock, Usage, StopReason) | references/api-reference.md → Common types |
Permissions: modes, rules, canUseTool callback | references/building-agents.md → Permissions |
Hooks: preToolUse/postToolUse/userPromptSubmit/stop/preCompact | references/building-agents.md → Hooks |
Ask the user mid-run (AskUser tool + handler) | references/building-agents.md → AskUser |
| Steer / interrupt an active run | references/api-reference.md → Session; references/recipes.md #12 |
Persist & resume sessions; custom SessionStore | references/building-agents.md → Sessions; api-reference.md → SessionStore |
Write a custom Tool | references/building-agents.md → Custom tools |
| Connect MCP servers (stdio + HTTP) | references/building-agents.md → MCP |
Critical rules (do not violate)
- Always provide
model — the SDK has no default model. Use a real model id for the chosen provider (e.g. "claude-opus-4-5" for Anthropic, "gpt-5" for OpenAI).
- Always
await agent.close() when done, or the SQLite store / MCP child processes leak.
- Import only from the four public subpaths. Never reach into
dist/ internals or src/.
- The engine is I/O-free. Render output by consuming events, not by expecting the SDK to print.
- One active run per session. Calling
run() again before the previous iterator finishes throws ConfigError. Use a second session for concurrency.
- Read-before-Edit is enforced by the
Edit tool — the model must Read a file before Edit succeeds on it.
- Permission
mode defaults to "default" (write/exec tools require approval via canUseTool or rules). acceptEdits auto-allows writes; yolo auto-allows everything. Read-scoped and Task tools are always allowed.
References
references/project-setup.md — consumer package.json/tsconfig/ESM, install, env vars, on-disk layout.references/api-reference.md — exact signatures: AgentOptions (incl. hooks/askUser), RunOptions, Session (incl. steer/interrupt), the Event union, provider constructors + OpenAI-compatible endpoints, data shapes, SessionStore, errors, lifecycle.references/tools-catalog.md — built-in tool params/scope, the Task tools and persistent task model, plus the conditionally-registered AskUser/Skill/Subagent tools.references/building-agents.md — extending the SDK: permissions, hooks, AskUser, sessions/stores, custom tools, MCP, skills, subagents, custom providers, custom compaction.references/recipes.md — copy-paste patterns: streaming UI, permission callback, rules, resume, abort, steer/interrupt, hooks + AskUser, images/thinking, MCP, REPL, offline testing.assets/starter-app/ — a complete runnable terminal-agent scaffold (package.json + tsconfig + src) to copy and adapt.
When a detail is not covered here, the authoritative sources are the published docs at https://skawld.com/docs (see the per-concept link table above), the SDK's own spec_docs/ (numbered 00- through 12-), and src/sdk.ts (the curated public export surface). Note: the config-file loader (src/config/) is a stub in v1 — configure agents in code via AgentOptions (the docs' Configuration page covers those knobs).
