Skills with Claude Agent SDK

Claude Agent SDK is a programmatic way to build agentic apps with a Claude Code-like execution model.

Skills in SDK are filesystem-based and enabled through agent configuration.

What Agent SDK Requires

From official docs, to use skills in Agent SDK you must:

1. Allow the Skill tool in allowed_tools
2. Set setting_sources to include "user" or "project" (or both)
3. Store skills in supported filesystem locations (for example .claude/skills/...)

Unlike Claude Code CLI behavior, skills are not programmatically registered in Agent SDK.
They must exist as files on disk.

Minimal Configuration Pattern

{
  "allowed_tools": ["Task", "Skill", "Write", "Bash", "WebSearch", "WebFetch"],
  "setting_sources": ["user", "project"]
}

Task is needed to dispatch subagents.
Skill is needed for skill discovery/use.

Multi-Agent Research Pattern

A strong Agent SDK pattern is:

1. Main agent orchestrates the task
2. Main agent dispatches specialized subagents in parallel
3. Main agent synthesizes outputs into one final artifact

Typical subagents:

• Docs researcher: official documentation extraction
• Repo analyzer: repository structure/code analysis
• Web researcher: tutorials, community content, external references

Where to Apply Skills

You can apply skills at multiple levels, but a common design is:

• Main agent uses one methodology skill (for example learning-a-tool)
• Subagents stay focused on retrieval/extraction prompts and tool use

This keeps orchestration policy centralized and avoids duplicating methodology across subagents.

Agent Definition Shape

In SDK, each subagent definition typically includes:

• description (when to dispatch)
• prompt (process/output format)
• tools (strictly scoped set)

Important: every tool referenced by subagents must also be permitted by the parent allowed_tools policy.

How This Fits with Subagents

• Parent agent can orchestrate the task.
• Subagents can run isolated work with scoped tool access.
• Skills provide repeatable procedure inside each delegated step.

Use subagents for isolation/parallelization; use skills for consistency.

MCP Integration Pattern

When external systems are needed (for example Notion), configure MCP servers in the SDK runtime and allow corresponding MCP tools.

Practical flow:

1. Configure MCP server command/env
2. Add MCP tool names to allowed_tools (explicit or wildcard pattern)
3. Let agents call MCP tools for read/write operations

This is useful for publishing generated artifacts (for example writing a markdown resource guide into Notion blocks).

Plan-Then-Execute Pattern

For long research tasks, ask for a plan first, then execute:

1. Generate plan (delegation + synthesis outline)
2. Confirm/adjust scope
3. Run parallel subagent tasks
4. Synthesize and write outputs

This improves controllability and avoids unnecessary tool usage.

Safety and Ops Guardrails

• Add user confirmations for potentially destructive tools (Write, Bash) where possible.
• Add interrupts/cancellation handling for long-running subagent jobs.
• Bound runtime with token/time/tool-call limits.
• Log delegated tasks, tool calls, and output artifacts for auditability.

Best Practices

• Keep skill scope narrow and composable.
• Store skills in project scope when they are repo-specific.
• Use user scope for personal reusable skills.
• Test activation behavior with representative prompts before production.
• Validate subagent output contracts before final synthesis.