Skills in the Claude Agent SDK

What skills are

Skills are reusable prompt modules that the agent loads on demand. Instead of writing lengthy instructions in the system prompt that consume context window space on every turn, you write them once in a skill file. The agent loads the full content only when it decides the skill is relevant.

The system prompt carries a lightweight description of each skill. The agent reads those descriptions, recognizes when a task matches, and pulls in the full instructions. Context stays clean. The agent gets specialized guidance exactly when it needs it.

Skills in the Agent SDK work identically to skills in Claude Code. Same file format, same folder structure. If you have already built skills for Claude Code, they work here without modification.

The folder structure

Create a .claude folder in your project directory if it does not exist. Inside it, create a folder for each skill. Each skill folder contains a single SKILL.md file:

project/
├── .claude/
│   └── skills/
│       └── meeting-notes/
│           └── SKILL.md
├── src/
│   └── agent.ts

Anatomy of a skill file

A skill file has two parts separated by YAML frontmatter:

---
name: meeting-notes
description: Use this skill when processing meeting transcripts, raw meeting notes, or when asked to format, summarize, or structure notes from a meeting or call.
---

## Meeting Notes Format

When processing meeting notes, always structure the output as follows:

**Header:** Include the date, meeting title, and attendees.

**Key Decisions:** List each decision made, one per line. Use the format: "Decision: [what was decided]"

**Action Items:** List each action item with owner and deadline. Format: "[ ] [Task] — [Owner] by [Date]"

**Next Steps:** Summarize the immediate next actions in 2-3 sentences.

Always output in markdown format.

The frontmatter is what the agent reads automatically. The name matches the folder name. The description tells the agent when to apply the skill. Write it clearly — this is how the agent decides whether to load the full instructions.

The body is what the agent reads when it uses the skill. Write this as specific instructions: exact output format, required fields, decision rules. The more precise the better.

Enabling skills in your agent

Two requirements:

for await (const message of query(messages(), {
  model: "claude-sonnet-4-5",
  tools: ["read", "write", "skill"],  // skill tool must be included
  settingSources: ["project"],         // must load project settings
  permissionMode: "bypassPermissions",
  dangerouslyAllowBypassPermissions: true,
})) {
  // handle messages
}

If you use tools: [...], the "skill" tool must be explicitly listed. If you omit the tools option entirely, all tools are available including skill by default.

settingSources: ["project"] is required. Without it, the agent cannot find the skill files in your .claude folder.

Testing a skill

Send a message that clearly matches your skill's description:

async function* messages() {
  yield {
    role: "user" as const,
    content: `Here are the raw notes from our meeting:
    
Attendees: Sarah (PM), Jake (Engineering)
We decided to move the launch date to June 15.
Jake will finish the API integration by June 1.
Sarah will update the client by end of week.`,
  };
}

The agent should recognize this as a meeting notes task, load the skill, and produce output that matches your format specification exactly.

Building a skill library for your practice

Skills compound over time. Every time you find yourself writing the same instructions across multiple agents or repeating the same output format requirements, that is a skill opportunity.

Common skills for operator workflows:

• Client brief — structure for pre-meeting research and context
• Weekly report — format for client status updates
• Competitive summary — structure for market research output
• Meeting notes — standardized format for call documentation
• Email draft — tone and format guidelines for client communication

Each skill you define becomes reusable across every agent you build. An agent that formats meeting notes for three different clients uses the same meeting-notes skill for all three — you change the system prompt or message context, not the skill itself.

> Skills vs system prompts: System prompts are for instructions that always apply. Skills are for instructions that apply conditionally. If you want the agent to always respond in a specific tone, put that in the system prompt. If you want it to follow a specific format only when processing meeting notes, that is a skill.

---

Author: FractionalSkill