Agent Skills

Purpose and Scope

Agent Skills are reusable, filesystem-based capabilities that make a Managed Agent better at a domain-specific workflow. In the product docs, a skill is a directory containing instructions and supporting files, with SKILL.md as the central authoring file for custom skills. In this SDK repository, the Agent Skills story appears in two connected places: the generated beta Managed Agents API types that let an agent reference skills, and the Node-only agent toolset plumbing that downloads those skills into a working directory before a session tool runner begins work.

The important distinction for SDK users is that skills are attached to agents, but they are realized locally by the runtime that operates the agent toolset. A pre-built Anthropic skill and a custom uploaded skill both become entries on the session agent, and the toolset treats those entries as skill IDs plus optional versions. The SDK-generated resources keep the API surface typed, while the toolset code handles session lookup, version resolution, archive download, extraction, path naming, and cleanup.

Sources: src/resources/beta/agents/index.ts, src/resources/beta/agents/agents.ts, src/tools/agent-toolset/skills.ts

Relevant Source Files

• src/resources/beta/agents/index.ts — re-exports the generated Managed Agents resource and public skill-related types, including Anthropic skill, custom skill, and skill parameter shapes.
• src/resources/beta/agents.ts — provides the beta agents module entrypoint by re-exporting the generated agents index.
• src/resources/beta/agents/agents.ts — implements the beta agents resource methods used to create, retrieve, update, list, and archive agents, with the managed agents beta header attached by the SDK.
• src/resources/beta/agents/versions.ts — implements listing agent versions, which matters when skill attachments are part of versioned agent definitions.
• src/tools/agent-toolset/skills.ts — implements Node-only setup for downloading the session agent's skills into the work directory and cleaning them up afterward.
• src/tools/agent-toolset/fs-util.ts — supplies shared file-tool constants and path confinement helpers; setupSkills uses the directory creation mode from this module.

Core Concepts

A skill attachment is not the same thing as a one-off prompt. A prompt affects the current conversation immediately, while a skill is a reusable filesystem resource that can be loaded when relevant. The generated beta agents index makes this visible by exporting BetaManagedAgentsAnthropicSkill, BetaManagedAgentsAnthropicSkillParams, BetaManagedAgentsCustomSkill, BetaManagedAgentsCustomSkillParams, and BetaManagedAgentsSkillParams. Those names are the SDK-facing vocabulary for the two kinds of skills described in the docs: Anthropic-provided skills and workspace-specific custom skills.

The agent resource is the attachment point. client.beta.agents.create sends a body to /v1/agents?beta=true, and client.beta.agents.update posts changes to an existing agent. Both methods merge any caller-provided betas with the managed agents beta value before sending headers. That means application code should think of skills as part of an agent's configured capability set, not as ad hoc files copied into a session by user code. Once an agent is created or updated with the right skill references, later sessions can resolve the agent and discover the skill list.

Sources: src/resources/beta/agents/index.ts, src/resources/beta/agents/agents.ts

System-to-Code Mapping

The versioning model has two layers. Agent versions are exposed through client.beta.agents.versions.list(agentID), returning a paginated cursor of agent records. Skill versions are handled inside the toolset setup flow: the session agent's skill entry may contain an alias such as latest, but the skill version download endpoints require a concrete version identifier. The helper named resolveSkillVersion exists to turn the session's skill version field into the concrete value used for retrieval and download.

Sources: src/resources/beta/agents/versions.ts, src/tools/agent-toolset/skills.ts

Execution Flow

setupSkills(ctx) is the operational center of this page. It is explicitly Node-only, because it imports Node modules such as node:fs/promises, node:path, node:child_process, and streams. The function is also deliberately a no-op unless the tool context includes both ctx.client and ctx.sessionId. That makes it safe to call from a session tool runner setup path without forcing every environment to support skill downloads. When those fields are present, it retrieves the session, reads session.agent.skills, and processes each skill independently.

For every skill on the resolved session agent, the setup flow resolves the requested version, retrieves that version's metadata, chooses a destination directory, downloads the archive, and extracts it. The destination root is {ctx.workdir}/skills, and each individual skill is placed under a directory derived from the version name. The code reduces the version name to a single path component with path.basename(version.name.trim()); empty, current-directory, and parent-directory names fall back to the skill_id. This preserves human-readable skill names when safe while keeping malicious or malformed names from escaping the skills area.

Failure handling is intentionally tolerant. A download, retrieval, or extraction failure for one skill is logged with the skill ID and does not block the remaining skills from being downloaded. After successful extraction, the function records the created destination path and returns a cleanup callback. Callers should invoke that cleanup callback after the work item finishes so that downloaded skill directories do not accumulate across sessions in the same work directory. This is especially important for long-lived workers that process multiple Managed Agent sessions.

Sources: src/tools/agent-toolset/skills.ts, src/tools/agent-toolset/fs-util.ts

API Components and Reference

The generated agent resource exposes the usual lifecycle operations: create(params, options?), retrieve(agentID, params?, options?), update(agentID, params, options?), list(params?, options?), and archive(agentID, params?, options?). The version resource exposes list(agentID, params?, options?). Each beta agents method shown in the source sends requests with ?beta=true and builds an anthropic-beta header that includes managed-agents-2026-04-01, plus any beta values supplied through the betas parameter. Pagination uses PageCursor and PagePromise for list-style APIs.

A minimal attachment-oriented workflow is therefore: create or update an agent with model, name, and skill-related fields; start or retrieve a session for that agent through the beta sessions surface; call the Node agent toolset setup after the work directory is available; run the session tools; and finally call the cleanup function. The exact skill creation API is outside these source snippets, but the setup code demonstrates the runtime contract it expects: skill records contain skill_id and optional version, and the SDK client has beta skill version retrieval and download methods available to obtain the archived files.

import Anthropic from '@anthropic-ai/sdk';
 
const client = new Anthropic();
 
const agent = await client.beta.agents.create({
  model: 'claude-sonnet-4-6',
  name: 'Spreadsheet specialist',
  // Attach skill parameters supported by the generated Managed Agents types.
});
 
for await (const version of client.beta.agents.versions.list(agent.id)) {
  console.log(version.id);
}

Sources: src/resources/beta/agents/agents.ts, src/resources/beta/agents/versions.ts, src/resources/beta/agents/index.ts

Implementation Details and Safety Notes

The filesystem details are worth understanding before embedding the agent toolset in infrastructure. setupSkills removes any existing destination directory before recreating it, uses DIR_CREATE_MODE from fs-util, and then extracts the downloaded archive into that directory. fs-util defines DIR_CREATE_MODE as 0o755, alongside broader file-tool helpers for canonicalization and confinement. Although setupSkills performs its own destination-prefix check for skill names, the surrounding toolset also contains symlink-aware path confinement utilities because file tools need to defend against workdir escape attempts.

When authoring or approving custom skills, treat the downloaded archive as executable operational context, not just documentation. The official guidance describes skills as folders that can include instructions, scripts, and resources, and enterprise review should pay attention to code execution, network access, MCP references, and credentials. From the SDK side, the practical next step is to make skill setup part of the same lifecycle as session workdir creation and teardown. Read the Managed Agents setup and session pages next to see where agent creation, session execution, and cleanup fit together.