O Claude Code vem com um assistente de IA de propósito geral. As Skills permitem que você o especialize. Uma skill é um arquivo markdown que ensina ao Claude Code como lidar com um tipo específico de tarefa: fazer deploy no Kubernetes, escrever migrações de banco de dados, revisar pull requests ou seguir as convenções de codificação da sua equipe.
A diferença entre "escreva um componente React" e "escreva um componente React seguindo nosso design system, usando nossos custom hooks, com error boundaries adequados e atributos de acessibilidade" é uma skill.
A documentação oficial do Claude Code agora torna uma coisa explícita: os comandos personalizados (custom commands) foram mesclados às skills. Arquivos existentes em .claude/commands/ ainda funcionam, mas as skills são a abstração recomendada porque suportam metadados mais ricos, arquivos de suporte e carregamento automático. Se você está padronizando um workflow de equipe hoje, construa-o primeiro como uma skill e trate os comandos legados como um caminho de compatibilidade.
O Que as Skills Realmente São
Uma skill reside em um diretório com um ponto de entrada SKILL.md. O Claude pode carregá-la automaticamente quando a descrição corresponde à tarefa atual, ou você pode invocá-la diretamente com /nome-da-skill.
.claude/
skills/
deploy/
SKILL.md # /deploy
review-pr/
SKILL.md # /review-pr
write-test/
SKILL.md # /write-test
O Claude ainda suporta .claude/commands/deploy.md, e o comando de barra ainda funcionará. Mas a versão moderna é .claude/skills/deploy/SKILL.md.
Isso parece uma pequena mudança de nomenclatura. Mas importa porque as skills podem carregar arquivos de suporte, frontmatter, controles de invocação e dicas de subagentes. Um arquivo de comando simples pode dizer ao Claude o que fazer. Uma skill pode dizer ao Claude como sua equipe espera que o trabalho seja feito.
Escrevendo Sua Primeira Skill
Aqui está um exemplo prático: uma skill que reforça as convenções de mensagens de commit da sua equipe.
Crie .claude/skills/commit/SKILL.md:
---
name: commit
description: Generate and validate conventional commits for this repo.
---
# Commit Workflow
## Steps
1. Run `git diff --staged` to see what's being committed
2. Analyze the changes and categorize: feat, fix, refactor, docs, test, chore
3. Write a commit message following our convention:
- Format: `type(scope): description`
- Scope is the package or module name
- Description is imperative mood, lowercase, no period
- Body explains WHY, not WHAT
4. If changes touch multiple scopes, create separate commits
5. Run `git commit -m "message"` with the generated message
## Rules
- Never use `--no-verify` to skip hooks
- Never amend published commits
- If tests fail in pre-commit, fix the issue first
## Examples
- `feat(billing): add stripe webhook handler`
- `fix(auth): handle expired refresh tokens`
- `refactor(api): extract rate limiter to shared package`
Agora o /commit dá ao Claude Code um workflow estruturado em vez de uma instrução vaga de "commite minhas alterações".
Se você já possui arquivos de comando legados, mantenha-os funcionando enquanto migra, mas não continue investindo no layout antigo. Os documentos oficiais são claros que as skills são o caminho a seguir.
Onde as Skills Residem Agora
O Claude Code atualmente descobre skills em quatro locais:
- skills pessoais:
~/.claude/skills/<nome-da-skill>/SKILL.md - skills do projeto:
.claude/skills/<nome-da-skill>/SKILL.md - skills de projeto aninhadas em monorepos
- skills fornecidas por plugins
Isso oferece uma divisão clara:
- skills pessoais para seu próprio estilo de trabalho
- skills de projeto para convenções do repositório
- skills de plugin para workflows empacotados reutilizáveis
Para adoção pela equipe, envie as skills do projeto para o repositório. Essa é a diferença entre "eu tenho um prompt legal no meu laptop" e "a equipe agora tem um workflow repetível".
Padrões de Design de Skills
O Padrão Checklist
Melhor para tarefas com múltiplas etapas de verificação.
# Pre-Deploy Checklist
Before deploying, verify each item:
- [ ] `pnpm typecheck` passes
- [ ] `pnpm test` passes
- [ ] No console.log statements in production code
- [ ] Environment variables documented in .env.example
- [ ] Database migrations are reversible
- [ ] API changes are backward compatible
If any check fails, stop and report the issue. Do not proceed with deployment.
O Padrão Árvore de Decisão
Melhor para tarefas onde a abordagem depende do contexto.
# Bug Fix Workflow
1. Reproduce the bug (find or write a failing test)
2. Identify the root cause:
- If it's a type error → fix the type definition at the source
- If it's a race condition → add proper locking/sequencing
- If it's a missing validation → add schema validation at the boundary
- If it's a logic error → fix and add regression test
3. Verify the fix doesn't break existing tests
4. Write a test that would have caught this bug
O Padrão Template
Melhor para gerar saídas consistentes.
# New API Endpoint
Create a new API endpoint following our conventions:
## File Structure
- Route handler: `apps/api/src/routes/{resource}/{action}.ts`
- Schema: `apps/api/src/schemas/{resource}.ts`
- Test: `apps/api/src/routes/{resource}/__tests__/{action}.test.ts`
## Required Elements
- Zod schema for request validation
- Authentication middleware
- Rate limiting
- Structured error responses using errorResponse()
- Success responses using successResponse()
- OpenAPI documentation comments
Instalando Skills da Comunidade
O ecossistema do Claude Code possui uma biblioteca crescente de skills da comunidade. Instale-as com:
npx add-skill username/repo-name -y
Coleções de skills populares:
coreyhaines31/marketingskills(29 skills de marketing/SEO)hedging8563/lemondata-api-skill(integração com a API LemonData)
As skills instaladas aparecem em ~/.claude/commands/ e funcionam em todos os projetos.
Os pacotes de skills instalados expõem cada vez mais skills adequadas em vez de apenas markdown de comando de barra. Se você mantém seu próprio repositório, o padrão de OpenCode + LemonData também se aplica aqui: mantenha a skill próxima ao workflow, não escondida em arquivos de prompt ad hoc.
Skills de Projeto vs Globais
| Localização | Escopo | Caso de Uso |
|---|---|---|
.claude/skills/ |
Apenas este projeto | Convenções do projeto, workflows de deploy |
~/.claude/skills/ |
Todos os projetos | Preferências pessoais, hábitos reutilizáveis |
.claude/commands/ |
Compatibilidade legada | Arquivos de comando de barra antigos que ainda funcionam |
As skills de projeto devem ser commitadas no seu repositório para que toda a equipe se beneficie. As skills globais são para preferências pessoais de workflow.
Avançado: Skills com Hooks
As skills podem referenciar hooks (comandos shell que rodam em eventos específicos) para aplicação automatizada:
# Pre-Commit Check
Before any commit, the following hooks run automatically:
- `pre-commit`: runs typecheck + lint
- `post-commit`: updates changelog
If a hook fails, investigate the error output and fix the issue.
Do not use --no-verify to bypass hooks.
Os próprios hooks são configurados em .claude/settings.json:
{
"hooks": {
"pre-commit": "pnpm typecheck && pnpm lint-staged"
}
}
É aqui que as skills se tornam mais do que trechos de prompt. Uma configuração de equipe útil geralmente tem três camadas:
- uma skill que diz ao Claude o workflow
- hooks que reforçam o workflow
- documentação do repositório que explica o workflow para humanos
Se uma dessas camadas estiver faltando, o sistema se torna frágil. Uma skill sem hooks torna-se apenas consultiva. Hooks sem skills tornam-se opacos. Documentação sem nenhum dos dois torna-se uma política obsoleta que ninguém segue.
Arquivos de Suporte São o Real Upgrade
O motivo mais importante para preferir skills em vez do antigo markdown de comando são os arquivos de suporte (supporting files).
Com um arquivo de comando, tudo tem que viver em um único bloco. Com um diretório de skill, você pode manter:
- templates
- exemplos
- auxiliares de shell (shell helpers)
- notas de referência mais longas
- scripts validadores
Isso permite que você mantenha o SKILL.md curto e com alto sinal, enquanto ainda fornece ao Claude material estruturado para consultar quando necessário.
Isso é especialmente útil para:
- workflows de implantação
- checklists de migração de schema
- processos de code review de várias etapas
- playbooks de integração específicos do produto
Se sua equipe também estiver usando vários modelos ou várias ferramentas de codificação, combine esta página com a comparação de modelos de codificação e o guia de configuração Cursor / Cline / Windsurf. Boas skills importam mais quando o modelo subjacente ou o editor muda.
Dicas para Skills Eficazes
Seja específico sobre caminhos de arquivos e convenções de nomenclatura. "Crie um componente" é vago. "Crie um componente em
src/components/ui/usando a nomenclatura PascalCase" é acionável.Inclua exemplos de saída correta. O Claude Code aprende melhor com exemplos do que com regras abstratas.
Defina o que NÃO fazer. "Nunca use o tipo
any" é mais fácil de aplicar do que "use tipos adequados".Mantenha as skills focadas. Uma skill por workflow. Uma skill de 200 linhas que cobre tudo é menos útil do que cinco skills de 40 linhas que lidam bem com uma tarefa cada.
Versione suas skills. À medida que suas convenções evoluem, atualize as skills. Skills desatualizadas são piores do que nenhuma skill porque reforçam padrões antigos.
Decida se a skill deve carregar automaticamente ou apenas rodar manualmente. Muitas equipes esquecem disso e depois se perguntam por que o Claude invoca uma skill de deploy em conversas não relacionadas.
Impacto no Mundo Real
Equipes que adotam skills relatam melhorias consistentes:
- Os ciclos de code review diminuem porque as convenções são aplicadas antes da revisão
- O tempo de onboarding diminui porque os novos desenvolvedores recebem a mesma orientação que os veteranos
- A qualidade do código gerado por IA melhora porque a IA tem contexto explícito sobre os padrões do projeto
O investimento é pequeno (30 minutos para escrever suas primeiras skills) e o retorno se acumula a cada interação.
O modelo mental mais útil é este: uma skill não é um atalho para o Claude. É um artefato de workflow versionado para sua equipe.
Se você escrever apenas uma skill, que seja aquela que codifica a decisão repetida de maior custo em sua base de código.
Construa com IA, guiado por suas próprias regras. O LemonData oferece uma única API key para modelos de codificação de diversos provedores, para que, uma vez que seus workflows estejam codificados como skills, você possa trocar de modelo sem reconstruir todo o seu conjunto de ferramentas.