Estenda agentes com skills
Controle quais skills Claude pode invocar em sessões do Claude Agent SDK, despache comandos por nome e crie skills que suas sessões descobrem
Agent Skills estendem Claude com capacidades especializadas que Claude invoca quando relevante. Skills são empacotadas como arquivos SKILL.md contendo instruções, descrições e recursos de suporte opcionais. Esta página também cobre comandos em sessões do Agent SDK.
Para informações abrangentes sobre skills, incluindo benefícios, arquitetura e diretrizes de autoria, consulte a visão geral de Agent Skills.
Como skills funcionam com o Agent SDK
Ao usar o Claude Agent SDK, skills são:
- Definidas como artefatos do sistema de arquivos: você cria cada skill como um arquivo
SKILL.mdem seu próprio diretório, como.claude/skills/<name>/SKILL.md - Carregadas do sistema de arquivos: o SDK carrega skills dos locais do sistema de arquivos governados por
settingSources(TypeScript) ousetting_sources(Python) - Descobertas automaticamente: uma vez que as configurações do sistema de arquivos são carregadas, o SDK descobre metadados de skill na inicialização a partir de diretórios de usuário e projeto, e carrega o conteúdo completo quando Claude invoca a skill
- Invocadas pelo modelo: Claude escolhe autonomamente quando usá-las com base no contexto
- Invocadas pelo usuário: você despache uma skill diretamente enviando
/<name>em um prompt. Consulte Comandos em sessões do Agent SDK - Escopo via opção
skills: skills descobertas são habilitadas por padrão. Passe uma lista de nomes de skills,"all"ou[]para controlar quais skills Claude pode invocar
Diferentemente de subagentes, que você pode definir na opção agents, você cria skills como arquivos em disco. O SDK não fornece uma API programática para registrá-las.
Use skills com o Agent SDK
Defina a opção skills em query() para controlar quais skills Claude pode invocar na sessão. Quando omitida, skills descobertas são habilitadas e a ferramenta Skill está disponível, correspondendo ao comportamento da CLI. Passe "all" para deixar Claude invocar cada skill descoberta, uma lista de nomes de skills para permitir apenas aquelas, ou [] para deixar Claude invocar nenhuma.
Por exemplo, para deixar Claude invocar apenas duas skills nomeadas:
options = ClaudeAgentOptions(skills=["pdf", "docx"])
const options = { skills: ["pdf", "docx"] };
Configure skills em uma sessão
Quando você define skills, o SDK adiciona a ferramenta Skill a allowedTools automaticamente. Se você também passar uma lista explícita de tools, inclua "Skill" nessa lista para que Claude possa invocar skills.
Uma vez configurado, Claude descobre automaticamente skills do sistema de arquivos e as invoca quando relevante para a solicitação do usuário.
O exemplo a seguir habilita cada skill descoberta em uma sessão e pré-aprova as ferramentas que skills comumente precisam. O exemplo define cwd para o diretório de trabalho atual do processo, portanto execute-o dentro de um projeto que tenha um diretório .claude/skills/ no diretório atual ou em qualquer pai até a raiz do repositório:
import asyncio
import os
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
options = ClaudeAgentOptions(
cwd=os.getcwd(), # .claude/skills/ here or in a parent directory
setting_sources=["user", "project"], # Load skills from filesystem
skills="all", # Let Claude invoke every discovered skill
allowed_tools=["Read", "Write", "Bash"],
)
async for message in query(
prompt="Help me process this PDF document", options=options
):
print(message)
asyncio.run(main())
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "Help me process this PDF document",
options: {
cwd: process.cwd(), // .claude/skills/ here or in a parent directory
settingSources: ["user", "project"], // Load skills from filesystem
skills: "all", // Let Claude invoke every discovered skill
allowedTools: ["Read", "Write", "Bash"]
}
})) {
console.log(message);
}
Confirme skills carregadas
Perto do início do stream, o SDK produz uma mensagem de sistema com subtipo init. Verifique seu array skills para confirmar que suas skills foram carregadas antes de Claude começar a trabalhar. O array inclui as skills invocáveis pelo usuário que você definiu com um campo frontmatter description ou when_to_use, junto com skills agrupadas incluídas com Claude Code.
O array lista apenas skills invocáveis pelo usuário. Uma skill com user-invocable: false em seu frontmatter carrega e permanece disponível para Claude, mas não aparece no array. O array lista as mesmas skills independentemente de estarem ou não em sua lista skills.
Permita apenas skills específicas
Para deixar Claude invocar apenas skills específicas, passe seus nomes na lista skills. Os nomes correspondem ao campo name em SKILL.md ou ao nome do diretório da skill. Use plugin:skill para skills fornecidas por plugin.
A lista leva apenas nomes de skills exatos. Se uma entrada não puder funcionar como um nome exato, query() rejeita a lista antes da sessão começar. Consulte Erro de nome de skill inválido para as regras de nome e o erro que cada SDK levanta.
O modelo não vê skills não listadas e a ferramenta Skill as rejeita, enquanto seus arquivos permanecem em disco e permanecem acessíveis através de Read e Bash. Restringir a lista não restringe despacho por nome.
Para deixar Claude invocar cada skill descoberta, passe skills: "all" em vez de um curinga.
Comandos em sessões do Agent SDK
Esta seção é a documentação de comando do SDK. Um comando é qualquer coisa que você executa enviando /<name> em um prompt. As entradas na superfície de comando diferem no que as respalda:
- Comandos integrados: executam lógica codificada no processo Claude Code que o SDK executa, por exemplo
/compact - Skills agrupadas: artefatos de prompt incluídos com Claude Code, por exemplo
/code-review - Suas skills: artefatos de prompt que você cria, cada um um diretório contendo um arquivo
SKILL.md. O nome de uma skill invocável pelo usuário se une à superfície automaticamente, portanto despachar seu próprio/security-checke executar um integrado funcionam da mesma forma - Arquivos de comando personalizados: uma forma de artefato mais antiga com o mesmo comportamento, arquivos Markdown simples em
.claude/commands/cujos nomes de arquivo se tornam nomes de comando. Skills são seu sucessor recomendado
Por padrão, tanto você quanto Claude podem invocar qualquer skill. Você pode restringir qualquer caminho através do frontmatter da skill. Para uma definição dos dois termos, consulte as entradas Comando e Skill do glossário. Consulte Comandos em Claude Code para cada integrado e Estenda Claude com skills para o guia completo de ambas as formas de artefato.
Descubra comandos disponíveis
Você pode despachar comandos que funcionam sem um terminal interativo através do SDK. A mensagem system/init lista os disponíveis em sua sessão em seu campo slash_commands. Comandos que precisam de um terminal interativo, como /theme e /terminal-setup, não aparecem na lista. Acesse o campo quando sua sessão começar:
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "Hello Claude",
options: { maxTurns: 1 }
})) {
if (message.type === "system" && message.subtype === "init") {
console.log("Available commands:", message.slash_commands);
}
}
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage
async def main():
async for message in query(prompt="Hello Claude", options=ClaudeAgentOptions(max_turns=1)):
if isinstance(message, SystemMessage) and message.subtype == "init":
print("Available commands:", message.data["slash_commands"])
asyncio.run(main())
A lista impressa mistura comandos integrados, skills agrupadas, suas skills invocáveis pelo usuário e arquivos .claude/commands/:
Available commands: ["clear", "compact", "context", "usage", "code-review", "verify", "security-check", ...]
Uma skill com user-invocable: false em seu frontmatter não aparece nesta lista ou no array skills de Confirme skills carregadas. Sessões que configuram servidores MCP também podem expor prompts MCP como comandos.
Despache comandos por nome
Envie um comando incluindo-o em sua string de prompt, da mesma forma que você envia texto regular. O despacho não depende da opção skills. Enviar /<name> executa uma skill invocável pelo usuário mesmo quando sua lista skills a omite. Comandos que atuam no histórico de conversa, como /compact, precisam de mensagens anteriores para trabalhar.
Compacte histórico com `/compact`
O comando /compact reduz o tamanho do seu histórico de conversa resumindo mensagens mais antigas enquanto preserva contexto importante. A compactação precisa de uma conversa existente com mensagens anteriores suficientes para resumir. Este exemplo tem uma conversa primeiro, depois a compacta e lê a mensagem de sistema compact_boundary que relata o resultado:
import { query } from "@anthropic-ai/claude-agent-sdk";
// Compaction needs existing history, so have a conversation first
try {
for await (const message of query({
prompt: "Explain what this project does",
options: { maxTurns: 2 }
})) {
if (message.type === "result" && message.subtype === "success") {
console.log(message.result);
}
}
} catch (error) {
// A single-shot query() throws after yielding an error result,
// so the follow-up query below still runs.
console.error(`Session ended with an error: ${error}`);
}
// Compact the same conversation
for await (const message of query({
prompt: "/compact",
options: { continue: true, maxTurns: 1 }
})) {
if (message.type === "system" && message.subtype === "compact_boundary") {
console.log("Compaction completed");
console.log("Pre-compaction tokens:", message.compact_metadata.pre_tokens);
console.log("Trigger:", message.compact_metadata.trigger);
// Example output:
// Compaction completed
// Pre-compaction tokens: 1842
// Trigger: manual
}
}
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage, SystemMessage
async def main():
# Compaction needs existing history, so have a conversation first
try:
async for message in query(
prompt="Explain what this project does",
options=ClaudeAgentOptions(max_turns=2),
):
if isinstance(message, ResultMessage) and message.subtype == "success":
print(message.result)
except Exception as error:
# A single-shot query() raises after yielding an error result,
# so the follow-up query below still runs.
print(f"Session ended with an error: {error}")
# Compact the same conversation
async for message in query(
prompt="/compact",
options=ClaudeAgentOptions(continue_conversation=True, max_turns=1),
):
if isinstance(message, SystemMessage) and message.subtype == "compact_boundary":
print("Compaction completed")
print("Pre-compaction tokens:", message.data["compact_metadata"]["pre_tokens"])
print("Trigger:", message.data["compact_metadata"]["trigger"])
# Example output:
# Compaction completed
# Pre-compaction tokens: 1842
# Trigger: manual
asyncio.run(main())
Redefina contexto com `/clear`
O comando /clear redefine a conversa para um contexto vazio, portanto prompts subsequentes começam sem histórico de conversa anterior. A conversa anterior permanece em disco. Você pode retornar a essa conversa passando seu ID de sessão para a opção resume.
/clear é útil em modo de entrada de streaming, onde você envia múltiplos prompts sobre uma única conexão. Para chamadas query() únicas, cada chamada já começa com contexto vazio, portanto enviar /clear não tem efeito prático. Comece uma nova query() em vez disso.
Crie skills
Crie cada skill como um diretório contendo um arquivo SKILL.md com frontmatter YAML e conteúdo Markdown. O campo description determina quando Claude invoca sua skill.
Exemplo de estrutura de diretório:
.claude/skills/security-check/
└── SKILL.md
Escolha um nível de descoberta
Salve skills em um dos dois níveis de descoberta mais comuns:
- Skills de projeto:
.claude/skills/, disponíveis apenas no projeto atual - Skills pessoais:
~/.claude/skills/, disponíveis em todos os seus projetos
Se você tem arquivos de comando personalizados existentes em .claude/commands/, eles continuam funcionando. Um arquivo de comando em .claude/commands/deploy.md cria /deploy e funciona da mesma forma que uma skill em .claude/skills/deploy/SKILL.md faria. Se um arquivo de comando e uma skill compartilham um nome, consulte Resolva skills que compartilham um nome para qual executa. O SDK carrega arquivos .claude/commands/ e ~/.claude/commands/ dos mesmos dois escopos que skills. Consulte Estenda Claude com skills para o guia completo de ambas as formas de artefato.
Crie e despache sua primeira skill
Para ver o fluxo completo, crie .claude/skills/security-check/SKILL.md:
---
name: security-check
description: Run a security vulnerability scan
---
Analyze the codebase for security vulnerabilities including:
- SQL injection risks
- XSS vulnerabilities
- Exposed credentials
- Insecure configurations
Uma vez que o arquivo existe, a skill está disponível através do SDK. Claude a invoca quando uma solicitação corresponde à sua descrição, e você pode despachá-la diretamente:
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "/security-check",
options: { maxTurns: 10 }
})) {
if (message.type === "result" && message.subtype === "success") {
console.log(message.result);
}
}
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage
async def main():
async for message in query(
prompt="/security-check", options=ClaudeAgentOptions(max_turns=10)
):
if isinstance(message, ResultMessage) and message.subtype == "success":
print(message.result)
asyncio.run(main())
Uma execução bem-sucedida termina com um resultado success cujo texto carrega as descobertas da varredura. Contra um pequeno aplicativo Express com problemas semeados, o texto do resultado começa:
**Security scan of `app.js` — 4 findings (most severe first):**
1. **SQL Injection** (line 8) — `req.query.name` is concatenated directly into the SQL string. Trivially exploitable (`' OR '1'='1`, `'; DROP TABLE users;--`). **Fix:** use parameterized queries, e.g. `db.query("SELECT * FROM users WHERE name = ?", [req.query.name], cb)`.
...
O nome da skill também aparece no array slash_commands da mensagem init.
Pré-aprove ferramentas para skills
Skills executam com as ferramentas da sessão. O exemplo abaixo pré-aprova Read, Grep e Glob com allowedTools (allowed_tools em Python), portanto Claude pode inspecionar arquivos enquanto executa a skill security-check sem parar para aprovação:
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
options = ClaudeAgentOptions(
setting_sources=["user", "project"], # Load skills from filesystem
skills="all",
allowed_tools=["Read", "Grep", "Glob"],
)
async def main():
async for message in query(prompt="Check this project for security issues", options=options):
print(message)
asyncio.run(main())
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "Check this project for security issues",
options: {
settingSources: ["user", "project"], // Load skills from filesystem
skills: "all",
allowedTools: ["Read", "Grep", "Glob"]
}
})) {
console.log(message);
}
No stream, a invocação de skill aparece como um uso de ferramenta Skill, seguido por chamadas Read nos arquivos do projeto. A execução termina com um resultado success cujo texto carrega as descobertas.
A lista pré-aprova as ferramentas nomeadas em vez de restringir as outras. Para o fluxo de permissão completo, incluindo modos de permissão e o callback canUseTool, consulte Permissões.
Solução de problemas
Skills não encontradas
Verifique a configuração settingSources: o SDK descobre skills através das fontes de configuração user e project. Se você definir settingSources/setting_sources explicitamente e omitir essas fontes, o SDK não carrega skills:
# Skills not loaded: setting_sources excludes user and project
options = ClaudeAgentOptions(setting_sources=[], skills="all")
# Skills loaded: user and project sources included
options = ClaudeAgentOptions(
setting_sources=["user", "project"],
skills="all",
)
// Skills not loaded: settingSources excludes user and project
const optionsWithoutSkills = {
settingSources: [],
skills: "all"
};
// Skills loaded: user and project sources included
const optionsWithSkills = {
settingSources: ["user", "project"],
skills: "all"
};
Para qual diretório de skill cada fonte carrega, consulte a tabela de fontes do sistema de arquivos. Para mais detalhes sobre settingSources/setting_sources, consulte a referência TypeScript SDK ou referência Python SDK.
Verifique o diretório de trabalho: o SDK carrega skills de .claude/skills/ na opção cwd e em cada diretório pai até a raiz do repositório. Certifique-se de que cwd aponta para ou abaixo do diretório contendo .claude/skills/, dentro do mesmo repositório:
# Ensure your cwd points to the directory containing .claude/skills/
options = ClaudeAgentOptions(
cwd="/path/to/project", # .claude/skills/ here or in a parent directory
setting_sources=["user", "project"], # Loads skills from these sources
skills="all",
)
// Ensure your cwd points to the directory containing .claude/skills/
const options = {
cwd: "/path/to/project", // .claude/skills/ here or in a parent directory
settingSources: ["user", "project"], // Loads skills from these sources
skills: "all"
};
Consulte Use skills com o Agent SDK para o padrão completo.
Verifique o local do sistema de arquivos:
# Check project skills
ls .claude/skills/*/SKILL.md
# Check personal skills
ls ~/.claude/skills/*/SKILL.md
Skill não sendo usada
Verifique a opção skills: se você passou uma lista skills, confirme que o nome da skill está incluído. Quando Claude tenta invocar uma skill não listada, a ferramenta Skill retorna Skill <name> is not in this session's skills allowlist. Adicione o nome à sua lista, ou despache a skill diretamente enviando /<name> em um prompt, que funciona sem listar.
Verifique a descrição: certifique-se de que é específica e inclui palavras-chave relevantes. Consulte Práticas recomendadas de Agent Skills para orientação sobre como escrever descrições eficazes.
Erro de nome de skill inválido
Quando um nome em sua lista skills não pode funcionar como um nome de skill exato, query() rejeita a lista antes de iniciar o processo Claude Code. Os nomes que acionam a rejeição incluem:
- Um nome vazio
- Um nome contendo parênteses, vírgulas ou caracteres de controle
- Um nome preenchido com espaço em branco
- Uma forma curinga como um
*simples ou um sufixo:*
Cada SDK superficializa a rejeição de forma diferente:
O SDK TypeScript lança um Error declarando a regra que a entrada quebrou. Por exemplo, skills: ["docs:*"] lança:
Invalid skill name "docs:*": wildcard-suffix names are not allowed; list each skill by its exact name.
Um nome vazio relata Skill names must be non-empty strings.
Antes do TypeScript Agent SDK 0.3.221, o SDK não executava esta verificação.
O SDK Python levanta ValueError declarando a regra que a entrada quebrou. Por exemplo, skills=["docs:*"] levanta:
ValueError: Invalid skill name 'docs:*': wildcard-suffix names are not allowed; list each skill by its exact name.
Um nome vazio relata Skill names must be non-empty strings.
Antes do Python Agent SDK 0.2.129, o SDK não executava esta verificação.
Solução de problemas adicional
Para solução de problemas geral de skills, como erros de sintaxe YAML e depuração, consulte a seção de solução de problemas de skills do Claude Code.
Próximos passos
O guia de skills do Claude Code cobre autoria em profundidade. Sua orientação se aplica a sessões do SDK. Comece com estas seções:
- Referência de frontmatter: cada campo suportado
- Passe argumentos para skills:
$ARGUMENTS,$0,$1e empilhamento de skills. A tabela de substituição completa adiciona argumentos nomeados e as variáveis${CLAUDE_*} - Injete contexto dinâmico: linhas
!`command`que executam antes de Claude ver o conteúdo da skill - Escolha onde skills carregam: cada local de skill, namespacing de plugin e qual skill executa quando dois compartilham um nome
Recursos relacionados
- Comandos em Claude Code: a superfície de comando completa, incluindo cada integrado
- Visão geral de Agent Skills: visão geral conceitual, benefícios e arquitetura
- Práticas recomendadas de Agent Skills: diretrizes de autoria para skills eficazes
- Livro de receitas de Agent Skills: skills de exemplo e templates
- Subagentes no SDK: agentes similares baseados em sistema de arquivos com opções programáticas
- Visão geral do SDK: conceitos gerais do SDK
- Referência TypeScript SDK: documentação completa da API
- Referência Python SDK: documentação completa da API