Introdução

As Skills são utilizadas para automatizar trabalhos repetitivos, ou seja, se tiver alguma tarefa que é feita diariamente, semanalmente ou então sempre que acontecer algum "gatilho", provavelmente pode ser automatizado utilizando uma Skill.

Alguns exemplos de trabalhos repetitivos:

• Escrever commits.
• Escrever comentários do que foi desenvolvido na atividade.
• Atualizar uma versão da tag, algo como de 1.0.1 para 1.1.0.
• Criar um ADR.
• Escrever um release notes para lançamento de versão.

Além de automatizar, a Skill pode ajudar a padronizar muitos desses trabalhos, usando como exemplo a escrita de um ADR, é um documento que via as boas práticas é melhor quando está padronizado.

Sendo assim a Skill pode ajudar a garantir que esse padrão vai ser seguido por todos do time, e também por chats diferentes, porque cada chat tem o seu contexto.

Como criar

A Skill pode ser criada dentro do diretório .claude/skills/[nome-da-skill]/SKILL.md. O nome da Skill é dado pelo nome do diretório.

Dentro do arquivo SKILL.md vai ficar as instruções que serão passadas a skill.

Como usar

A skill pode ser utilizada automaticamente quando a IA entende que existe uma Skill para fazer um trabalho específico.

E também pode ser invocada passando diretamente no prompt, algo como Use a Skill X para fazer Y, ou então chamando diretamente com o comando Use a skill /nome-da-skill.

Boas práticas

Nome e descrição

A escrita da Skill é um arquivo markdown, porém nas primeiras linhas é necessário passar pelo menos duas configurações, de nome e descrição.

Dessa forma:

name: [nome-da-skill]
description: [descricao-da-skill]

O nome deve ser o mesmo que está no diretório.

Já a descrição é útil e importante para que a IA entenda o que essa Skill faz, e com o melhor entendimento, a IA pode invocar quando achar necessário.

Uma boa prática é colocar nessa descrição quando a IA deve utilizar, algo como:

• Use quando precisar revisar o código
• Use quando precisar criar uma mensagem de commit
• Use para verificar o módulo de autenticação

Não é necessário criar um texto longo, mas é ideal descrever de forma clara o que a Skill faz e quando deve ser utilizado.

Instruções

Coloque as instruções do que precisa ser realizado, faça com uma descrição clara e concisa, o ideal é que esse arquivo não fique muito grande, até 300 linhas é o ideal.

Separe os tópicos com títulos e subtítulos do markdown, dessa forma facilita a leitura e organização das instruções no arquivo.

Use bullet points, os modelos de inteligência artificial preferem ler listas com instruções diretas do que ler longos textos e ter que interpretar o que precisa ser feito.

Desabilitar invocação pelo modelo

Por padrão, toda Skill no projeto, pode ser chamado diretamente pela IA enquanto está trabalhando. Porém é possível desabilitar esse comportamento e prevenir a chamada pelo modelo.

Dessa forma a Skill só poderá ser invocada manualmente pelo terminal.

Essa configuração é realizada no bloco de configurações da skill passando a chave disable-model-invocation como true.

Argument Hint

É possível definir argumentos que podem ser passados e ajudar na execução da Skill.

Essa definição também é feita no bloco de configurações da skill passando a chave argument-hint com o argumento desejado, exemplo: argument-hint: <branch-or-path>, argument-hint: <adr-name>

Definir a saída

Essa é a melhor configuração para padronização de retorno.

Voltando ao exemplo do ADR, caso queira que a Skill sempre retorne ou crie o ADR com o mesmo padrão de informações, o ideal é indicar para a Skill o que é esperado no retorno, por exemplo:

## Output

Always use this structure to output data

- Title:
- Date:
- Status: Accept/Suspend/Reject
- Context:
- Decision:

Com isso, sempre que a Skill for executada, ela vai retornar exatamente esses dados.

Definir o que não deve ser feito

Tão importante quanto definir o que fazer, é definir o que não fazer, porque isso garante que a IA não irá "alucinar" e fazer o que não foi pedido.

Utilize o mesmo padrão de separar por markdown e colocar os bullet lists, para manter a consistência no arquivo e facilitar a leitura.

Melhoria incremental

A ideia é que as skills ajudem no trabalho diário removendo o trabalho repetitivo, e para que a skill continue sendo útil, o ideal é revisar o seu trabalho entregue, e melhorar a sua documentação do que fazer, do que não fazer, adicionar mais exemplos.

Dessa forma com o passar do tempo e das atividades a Skill vai ficar cada vez mais completa e assertiva.

Exemplo completo de Skill

---
name: criar-adr
description: Cria um ADR (Architecture Decision Record) padronizado a partir de uma decisão técnica tomada pelo time. Use quando o usuário pedir para registrar, documentar ou formalizar uma decisão de arquitetura, quando falar em "ADR", "decisão técnica" ou "registro de decisão", e também quando uma escolha relevante de tecnologia, padrão ou ferramenta for definida durante a conversa.
argument-hint: <titulo-da-decisao>
---

## Contexto

ADRs registram decisões de arquitetura relevantes e o motivo por trás delas.
O objetivo é que qualquer pessoa que entre no projeto depois entenda **por que**
a decisão foi tomada, não apenas **qual** foi a decisão.

ADRs existentes ficam em `docs/adr/`.

## Tarefa

Escreva um ADR sobre a decisão indicada em `$ARGUMENTS`.

- Leia os ADRs já existentes em `docs/adr/` para seguir o mesmo estilo e numeração.
- Numere o novo arquivo em sequência: `docs/adr/NNNN-titulo-em-kebab-case.md`.
- Levante o contexto na conversa atual, nos arquivos do projeto e no histórico do Git.
- Registre pelo menos uma alternativa que foi considerada e descartada.
- Descreva as consequências da decisão, tanto as positivas quanto as negativas.
- Se faltar informação essencial (motivo, alternativas, responsável), pergunte
  antes de escrever em vez de supor.

## Status

- **Aceito** — decisão em vigor
- **Proposto** — em discussão, ainda não vale
- **Substituído** — trocado por outro ADR (cite qual)
- **Descontinuado** — não vale mais e não foi substituído

## Output

Use sempre esta estrutura, nesta ordem:

# NNNN - <título da decisão>

- **Data:** AAAA-MM-DD
- **Status:** Aceito | Proposto | Substituído | Descontinuado
- **Responsáveis:** <nomes ou time>

## Contexto

Qual problema levou a essa decisão. Dois ou três parágrafos, no máximo.

## Decisão

O que foi decidido, em uma frase direta e no presente.

## Alternativas consideradas

- **<alternativa>** — por que foi descartada.

## Consequências

- **Positivas:** o que melhora.
- **Negativas:** o custo aceito, dívidas técnicas ou limitações.

## O que não fazer

- Não altere ADRs já existentes; para reverter uma decisão, crie um novo ADR
  com status **Substituído** apontando para o anterior.
- Não invente alternativas, benchmarks ou números que não estejam na conversa
  ou no projeto.
- Não descreva implementação, passo a passo ou código — ADR registra decisão,
  não tutorial.
- Não escreva ADR para decisões triviais e reversíveis, como formatação de código
  ou nome de variável.
- Não deixe a seção de consequências apenas com pontos positivos.

Conclusão

As Skills ajudam e muito no trabalho do dia a dia, ajudando em tarefas repetitivas, manter padrões de escrita, padrões de código, verificações no repositório e muitos outros trabalhos que podem ser automatizados.

Caso tenha alguma sugestão de melhoria nesse artigo, entre em contato comigo no Linkedln :)