O guia completo para desenvolver habilidades para Claude/Codex

A era de tratar a IA como um chatbot genérico acabou oficialmente. Enquanto 99% dos usuários ainda escrevem mensagens básicas, o 1% mais avançado está desenvolvendo habilidades. Essa é a diferença entre ter um brinquedo e ter um funcionário especializado, disponível 24 horas por dia, 7 dias por semana.

Mas para chegar lá, você precisa parar de escrever prompts e começar a entregar código usando habilidades.

Aqui está o guia técnico completo para o novo padrão de competências. Lançadas pela Anthropic em outubro de 2025, as skills não são apenas instruções; são pacotes dinâmicos e organizados que permitem aos agentes carregar contexto sob demanda. O que antes era um recurso exclusivo evoluiu para um padrão aberto, com grandes plataformas como OpenAI e Microsoft adotando a especificação, e ferramentas como a Vercel…

habilidades.sh

CLI que torna o gerenciamento de habilidades acessível a desenvolvedores em todo o mundo.

Análise das competências dos agentes:

Diferentemente da chamada de funções ou execução de código tradicionais, as habilidades operam por meio de expansão sofisticada de prompts e modificação de contexto; elas ensinam o agente a pensar e abordar problemas em vez de simplesmente executar funções predefinidas.

Uma habilidade é enganosamente simples em sua estrutura:

your-skill-name/
├── SKILL.md              # Required - main skill file
├── scripts/              # Optional - executable code
│   ├── process_data.py
│   └── validate.sh
├── references/           # Optional - documentation
│   ├── api-guide.md
│   └── examples/
└── assets/               # Optional - templates, fonts, icons
    └── report-template.md

A essência de toda habilidade é o

skill.md arquivo, que contém o frontmatter YAML para metadados e o conteúdo Markdown para instruções:

---
name: project-workspace-setup
description: Automates complete project workspace creation including pages, databases, and templates. Use when user asks to "set up a new project", "create a workspace", or "initialize a project structure".
---

# Project Workspace Setup

## Instructions
[Step-by-step guidance for Claude to follow]

## Examples
[Concrete usage scenarios]

## Troubleshooting
[Common issues and solutions]

As habilidades são muito simples e intencionais, o que as torna acessíveis a pessoas sem conhecimento de desenvolvimento, mantendo-se robustas o suficiente para implantações em escala empresarial.

Como as habilidades funcionam na prática:

Compreender como as habilidades funcionam internamente é crucial para criar habilidades eficazes. De acordo com uma análise técnica aprofundada, as habilidades representam uma arquitetura de meta-ferramenta baseada em instruções que opera de forma fundamentalmente diferente das ferramentas tradicionais de IA.

o sistema de divulgação progressiva de três níveis

Nível 1 – frontmatter YAML (sempre carregado): o nome e a descrição da habilidade são inseridos no prompt do sistema de Claude. Isso fornece informações suficientes para que Claude decida quando carregar a habilidade completa sem consumir tokens desnecessários.

Nível 2 –

HABILIDADE.md

Corpo (carregado quando relevante): quando o Claude determina que uma habilidade é relevante, ele carrega as instruções completas do corpo em Markdown. Isso contém orientações detalhadas passo a passo, exemplos e boas práticas.

Nível 3 – recursos vinculados (carregados conforme necessário): arquivos adicionais nos diretórios scripts/, references/ e assets/ são acessados ​​somente quando especificamente necessários, minimizando ainda mais o uso de tokens.

Essa abordagem de divulgação progressiva significa que as habilidades podem ser incrivelmente detalhadas sem sobrecarregar a janela de contexto; o Claude carrega apenas o que precisa, quando precisa.

o padrão de duas mensagens e a metacomunicação

Um dos aspectos mais engenhosos das habilidades é como elas lidam com a visibilidade. Quando Claude ativa uma habilidade, o sistema envia dois tipos de mensagens:

• Mensagens visíveis ao usuário (isMeta: false): estas aparecem no histórico da conversa.
• Mensagens meta (isMeta: true): contêm as instruções completas da habilidade e são enviadas para a API do Claude, mas nunca são exibidas aos usuários.

Essa separação resolve um problema crítico de UX: os usuários precisam de transparência sobre quais habilidades estão sendo executadas, mas não precisam ver milhares de palavras de instruções técnicas poluindo a interface do chat.

Desenvolvendo sua primeira habilidade:

Passo 1: identifique seu caso de uso.

Antes de escrever qualquer código, identifique 2 a 3 cenários concretos que sua habilidade deve abranger. As categorias mais comuns são:

Categoria 1: Criação de documentos e ativos usada para gerar resultados consistentes e de alta qualidade, como documentos, apresentações ou designs. Exemplo: a habilidade de design front-end que produz interfaces web profissionais em vez de soluções genéricas de IA.

Categoria 2: Automação de fluxo de trabalho – processos de várias etapas que se beneficiam de uma metodologia consistente. Exemplo: a habilidade de criação de habilidades que orienta os usuários na criação de novas habilidades.

Categoria 3: Aprimoramento do MCP, fornecendo orientação de fluxo de trabalho com base nas integrações do servidor do Protocolo de Contexto de Modelo (MCP). Exemplo: a habilidade de revisão de código do Sentry que analisa e corrige automaticamente erros em solicitações de pull do GitHub usando dados de monitoramento de erros.

Etapa 2: definir os critérios de sucesso

Como você saberá se sua habilidade funciona? Defina metas mensuráveis:

• Acionamento preciso: a habilidade deve ser carregada em 90% das consultas relevantes.
• Eficiência da ferramenta: fluxos de trabalho completos em X chamadas de ferramenta (em comparação com a linha de base)
• Taxa de erros: zero chamadas de API com falha por fluxo de trabalho.
• Consistência: a mesma tarefa produz resultados semelhantes em todas as sessões.

Passo 3: escreva descrições eficazes

O campo de descrição é crucial, pois é ele que o Claude usa para decidir quando carregar sua habilidade. Use esta estrutura:

[What it does] + [When to use it] + [Key capabilities]

Good Example:

description: Analyzes Figma design files and generates developer handoff documentation. Use when user uploads .fig files, asks for "design specs", "component documentation", or "design-to-code handoff".

Bad Example:
description: Helps with projects.

Inclua frases-chave que os usuários realmente usariam, mencione tipos de arquivo relevantes e declare claramente qual problema a habilidade resolve.

Passo 4: Estruture suas instruções

---
name: your-skill
description: [Clear, specific description]
---

# Your Skill Name

## Instructions
Step 1: [First major step with clear explanation]
Step 2: [Second major step]
...

## Examples
Example 1: [Common scenario]
User says: "Set up a new marketing campaign"
Actions:
1. Fetch existing campaigns via MCP
2. Create new campaign with provided parameters
Result: Campaign created with confirmation link

## Troubleshooting
Error: [Common error message]
Cause: [Why it happens]
Solution: [How to fix]

Etapa 5: teste iterativamente

A abordagem mais eficaz é iterar em uma única tarefa desafiadora até que Claude tenha sucesso e, em seguida, incorporar essa abordagem à sua habilidade. Teste para:

• Acionamento: carrega quando deveria? Evita falsos positivos?
• Funcionalidade: produz resultados corretos de forma consistente?
• Desempenho: é melhor do que a linha de base (sem habilidade)?

oHABILIDADES.shCLI

No início de 2026, a Vercel lançou

skills.sh

Uma ferramenta de linha de comando que se tornou o equivalente ao npm para agentes de IA. Essa CLI ajuda a instalar e gerenciar habilidades em diferentes plataformas de IA.

Instalação básica:

# Install a skill from GitHub
npx skills add vercel-labs/agent-skills

# Install a specific skill from a repo
npx skills add vercel-labs/agent-skills@vercel-react-best-practices

# Install from a direct path
npx skills add https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design-guidelines

# List installed skills
npx skills list

# Check for updates
npx skills check

# Update all skills
npx skills update

o habilidades.sh

A CLI detecta automaticamente quais agentes de IA para codificação você tem instalados e configura as habilidades de acordo. Atualmente, ela suporta mais de 35 agentes, incluindo Claude Code, Cursor, Codex, Open Code, Windsurf e muitos outros.

A plataforma inclui rankings de popularidade baseados em telemetria de instalação, navegação categorizada por caso de uso, funcionalidade de busca para encontrar habilidades relevantes e links diretos para instalação com um único comando.

casos de uso no mundo real

Estudo de caso 1: transformação do design de front-end

Ao ser solicitado a criar uma landing page, o código Claude, sem a habilidade de design front-end, produz um resultado genérico, funcional, mas inconfundivelmente gerado por IA. No entanto, com a habilidade apropriada, a mesma tarefa resulta em um site profissional e moderno, com padrões de design sofisticados, espaçamento adequado e elementos de interface do usuário contemporâneos.

Isso ilustra um princípio fundamental: as habilidades incorporam conhecimento especializado que vai além dos dados de treinamento de Claude. A habilidade de design front-end contém a sabedoria destilada de designers profissionais — teoria das cores, princípios de layout, diretrizes de acessibilidade — agrupada em conhecimento procedimental.

Estudo de caso 2: Criação de documentos empresariais

As habilidades pré-configuradas da Anthropic para PowerPoint, Excel, Word e PDF demonstram capacidades de nível empresarial. Essas habilidades permitem:

• Consistência da marca: aplicar automaticamente os guias de estilo corporativos.
• Aderência ao modelo: seguir as estruturas de documentos organizacionais.
• Inteligência de fórmulas: gere fórmulas complexas do Excel corretamente.
• Preenchimento de formulários PDF: preenchimento programático de formulários PDF preenchíveis

Organizações que utilizam essas habilidades relatam que tarefas que antes levavam mais de 30 minutos agora são concluídas em menos de 3 minutos.

Estudo de caso 3: orquestração multi-MCP

Considere um fluxo de trabalho que vai do projeto ao desenvolvimento e abrange vários serviços:

Phase 1: Design Export (Figma MCP)
- Export design assets from Figma
- Generate design specifications
- Create asset manifest

Phase 2: Asset Storage (Google Drive MCP)
- Create project folder
- Upload all assets
- Generate shareable links

Phase 3: Task Creation (Linear MCP)
- Create development tasks
- Attach asset links to tasks
- Assign to engineering team

Phase 4: Notification (Slack MCP)
- Post handoff summary
- Include asset links and task references

Uma habilidade que orquestra esse fluxo de trabalho elimina a necessidade de coordenação manual, garante que as etapas ocorram na ordem correta e lida com a recuperação de erros automaticamente.

Padrões avançados e melhores práticas

Padrão 1: seleção de ferramentas sensível ao contexto

Habilidades inteligentes se adaptam com base no contexto. Para armazenamento de arquivos:

Decision Tree:
1. Check file type and size
2. Determine best storage:
   - Large files (>10MB): Cloud storage MCP
   - Collaborative docs: Notion/Docs MCP
   - Code files: GitHub MCP
   - Temporary files: Local storage
3. Execute with appropriate tool
4. Explain choice to user

Esse padrão proporciona transparência e, ao mesmo tempo, otimiza para o caso de uso específico.

Padrão 2: inteligência específica de domínio

As habilidades podem incorporar conhecimento especializado. Uma habilidade em conformidade financeira pode:

Before Processing (Compliance Check):
1. Fetch transaction details via MCP
2. Apply compliance rules:
   - Check sanctions lists
   - Verify jurisdiction allowances
   - Assess risk level
3. Document compliance decision

Processing:
IF compliance passed:
  - Process transaction
  - Apply fraud checks
ELSE:
  - Flag for review
  - Create compliance case

Isso incorpora conhecimentos especializados em regulamentação que Claude não possui inerentemente.

Padrão 3: refinamento iterativo

Para resultados críticos em termos de qualidade:

Initial Draft:
- Generate first version
- Save to temporary file

Quality Check:
- Run validation script
- Identify issues

Refinement Loop:
- Address each issue
- Regenerate affected sections
- Re-validate
- Repeat until quality threshold met

Esse padrão é particularmente eficaz para geração de documentos, revisão de código e análise de dados.

Considerações sobre segurança e confiança

As habilidades são poderosas, podem executar código e invocar ferramentas. Esse poder exige cuidadosas considerações de segurança:

o modelo de confiança

A Anthropic recomenda enfaticamente o uso de habilidades apenas de fontes confiáveis:

• Habilidades criadas pela ação humana: mantidas e verificadas profissionalmente.
• Habilidades autodesenvolvidas: você controla o código.
• Habilidades dos parceiros: de parceiros comerciais verificados

As habilidades da comunidade devem ser revisadas antes da instalação, pois uma habilidade maliciosa pode direcionar o Claude a executar operações não intencionais.

capacidades restritas

As habilidades são executadas em ambientes controlados:

• claude.ai Restrito a pacotes pré-instalados, acesso limitado à rede.
• Claude Code: acesso total à rede, mas local à máquina do usuário.
• API: executa em um contêiner de execução de código com permissões configuráveis.

O frontmatter do YAML pode especificar `allowed-tools` para limitar quais APIs uma skill pode acessar:

allowed-tools: "Bash(python:*) Bash(npm:*) WebFetch"

o futuro das habilidades de agentes

A indústria de IA está mudando o foco das capacidades brutas dos modelos para a utilidade prática.

As habilidades representam essa evolução, passando de demonstrações impressionantes para fluxos de trabalho de produção que geram valor comercial mensurável.

com base nas trajetórias atuais:

1. Habilidades como diferencial competitivo: empresas com bibliotecas de habilidades robustas terão uma vantagem em produtividade. As pioneiras estão construindo repositórios internos de habilidades como ativos estratégicos.

2. Mercados de habilidades: já estamos vendo surgir mercados de habilidades comerciais, semelhantes às lojas de aplicativos, onde habilidades especializadas podem ser adquiridas para setores ou casos de uso específicos.

3. Criação de habilidades assistida por IA: a habilidade de criação de habilidades demonstra a capacidade de IA de construir habilidades. Essa melhoria recursiva acelerará as versões futuras, que poderão gerar habilidades complexas a partir de descrições em linguagem natural.

4. Habilidades para orquestração de agentes: à medida que os sistemas multiagentes se tornam mais comuns, as habilidades evoluirão para coordenar múltiplos agentes de IA trabalhando em conjunto em projetos complexos.

5. Habilidades regulatórias e de conformidade em setores altamente regulamentados (finanças, saúde, direito), incluindo a capacidade de codificar regras de conformidade e trilhas de auditoria, tornar-se-ão essenciais.

recomendações práticas

Para desenvolvedores individuais:

Comece devagar: desenvolva uma habilidade para algo que você faz repetidamente. O investimento de tempo compensa rapidamente quando você elimina o trabalho repetitivo.

Use o criador de habilidades: habilidade criador de habilidades de antrópico (disponível em

claude.ai

e o código Claude) podem estruturar sua primeira habilidade em 15 a 30 minutos.

Junte-se à comunidade: explore o diretório de habilidades em

skills.sh

Instale habilidades populares e aprenda com exemplos do mundo real.

Para equipes e organizações:

Identificar fluxos de trabalho de alto valor: em que situações os membros da equipe explicam repetidamente os mesmos processos para a IA? Esses são candidatos ideais para o desenvolvimento de habilidades.

Crie um repositório de habilidades: controle as versões das suas habilidades organizacionais no Git. Compartilhe-as entre equipes e faça iterações com base no feedback.

Padronizar com base na especificação aberta: desenvolver habilidades usando o padrão aberto para garantir a portabilidade à medida que o cenário da IA ​​evolui.

Invista na manutenção de habilidades: assim como qualquer código, as habilidades precisam ser atualizadas. Atribua responsabilidades e estabeleça processos de revisão.

para empresas

Aproveitar a implementação organizacional: utilize controles administrativos para provisionar habilidades em todo o espaço de trabalho, garantindo operações consistentes.

Estabeleça parcerias com fornecedores: muitas ferramentas SaaS agora oferecem habilidades oficiais (Atlassian, Notion, Figma, etc.). Elas se integram perfeitamente aos seus fluxos de trabalho existentes.

Desenvolver habilidades de conformidade: codificar os requisitos regulamentares como habilidades para garantir que o trabalho assistido por IA atenda aos padrões.

Medir o ROI: acompanhar a economia de tempo, a redução de erros e as melhorias na consistência. As habilidades devem demonstrar um claro valor comercial.

Solução de problemas comuns

A habilidade não será ativada.

Problema : a skill nunca carrega automaticamente. Solução : revise a descrição para incluir frases específicas que os usuários realmente usariam. Teste variações de como os usuários poderiam formular a solicitação.

acionamento de habilidades com muita frequência

Problema : sobrecarga de habilidades para consultas irrelevantes Solução: adicione gatilhos negativos e seja mais específico sobre o escopo. Exemplo: não use para exploração simples de dados (use a habilidade de visualização de dados em vez disso).

instruções não seguidas

Problema : a habilidade carrega, mas Claude não segue as instruções .

Solução :

• Mantenha as instruções concisas, utilizando marcadores.
• Coloque as instruções críticas no topo com cabeçalhos como `## CRÍTICO`:
• Para validação determinística, considere agrupar scripts executáveis ​​em vez de depender da linguagem natural.

falhas de conexão mcp

Problema : a habilidade carrega, mas as chamadas MCP falham. Solução :

• Verifique se o servidor MCP está conectado (Configurações > Extensões).
• Verifique as chaves de API e a autenticação.
• testar mcp de forma independente sem a habilidade
• Verifique se os nomes das ferramentas correspondem exatamente à documentação do servidor MCP (diferenciando maiúsculas de minúsculas).

conclusão:

As habilidades dos agentes representam uma evolução fundamental na forma como trabalhamos com IA. Em vez de tratar cada conversa como uma página em branco, as habilidades nos permitem construir conhecimento organizacional, codificar as melhores práticas e criar assistentes de IA especializados que realmente entendem nossos domínios. O padrão aberto garante que não haja dependência de tecnologia proprietária, mas sim um ecossistema onde a inovação pode florescer. Seja você um desenvolvedor individual criando ferramentas de produtividade, uma equipe padronizando fluxos de trabalho ou uma empresa implementando IA em escala, as habilidades fornecem a estrutura para transformar IA de propósito geral em parceiros especializados. A barreira de entrada nunca foi tão baixa. Com ferramentas como a

habilidades.sh

Com a CLI e o marketplace de habilidades, criar e implantar uma habilidade leva minutos, não dias. A curva de aprendizado é suave: comece com uma habilidade simples para uma tarefa que você realiza com frequência e vá evoluindo a partir daí. Ao olharmos para um futuro onde agentes de IA lidam com trabalhos cada vez mais complexos, as habilidades serão o diferencial entre as organizações que simplesmente usam IA e aquelas que realmente a aproveitam como uma vantagem estratégica. A questão não é se você deve investir em habilidades, mas sim com que rapidez você consegue começar a desenvolvê-las. Bem-vindos à era dos agentes de IA especializados. Bem-vindos à era das habilidades.

Texto original em inglês: https://x.com/rohit4verse/status/2021622526112358663