Uma skill instalada direto do repositorio publico ja funciona — mas funciona de forma genérica. Ela nao conhece o seu cliente, o seu vocabulario, o seu stack, as suas regras de compliance. O salto de qualidade entre uma skill boa e uma skill excelente esta em uma camada fina: o domínio que voce injeta nela.

Customizar uma skill nao é refazer ela. É pegar uma base que ja resolve o problema generico (revisar codigo, gerar documentacao, planejar feature) e adicionar as 5–10 perguntas, 3 termos tecnicos e 2 regras de negocio que transformam a skill em uma colega de equipe que fala o idioma da sua empresa.

Antes de customizar, voce precisa enxergar a anatomia. Toda skill tem 3 camadas: o frontmatter YAML (metadados de ativacao), o corpo em Markdown (instrucoes para o agente) e, opcionalmente, arquivos de referencia em references/. A maior parte das customizacoes acontece nas duas primeiras.

---
name: minha-skill
description: Use when X happens. Triggers: keyword1, keyword2.
---

# Skill Body

## When to use

Descreva os cenarios onde o agente DEVE carregar esta skill.
Inclua exemplos de frases do usuario que devem ativar.

## Workflow

1. Read the relevant project files
2. Ask the domain-specific questions in references/QUESTIONS.md
3. Produce the output document at docs/output.md
4. Validate against the checklist in references/CHECKLIST.md

## Output format

Sempre devolva um resumo em 3 bullets + caminho do arquivo gerado.

Cada parte tem um papel diferente:

• • name — identificador unico. Usado pelo agente internamente e por voce no terminal (/minha-skill).
• • description — o campo mais critico. É o que o agente lê pra decidir se carrega a skill ou nao. Triggers ruins = skill morta.
• • When to use — cenarios em prosa. Reforça os triggers e adiciona contexto.
• • Workflow — passos numerados. É o roteiro que o agente segue.
• • Output format — define o formato de saida. Sem isso o agente improvisa.

A description ideal tem 3 partes: quando ativar (cenario em prosa), triggers explicitos (palavras-chave) e, opcionalmente, contra-indicacoes (quando NAO ativar). Esse formato reduz drasticamente falso positivo e falso negativo.

# Exemplo 1 — Skill de revisao de PR
description: Revisa pull requests
description: Use ao revisar PRs em monorepo TypeScript com Turborepo.
Triggers: revisar PR, code review, analisar diff, checar mudancas.
NAO usar para revisao de docs ou changelog.

# Exemplo 2 — Skill de migration SQL
description: Cria migrations de banco
description: Use ao criar/ajustar migrations Postgres com Prisma
em ambiente multi-tenant. Triggers: migration, alter table,
adicionar coluna, schema change, prisma migrate.

# Exemplo 3 — Skill de checklist de compliance
description: Ajuda com compliance
description: Use antes de fazer deploy em ambiente que processa
dados de cartao (PCI-DSS). Triggers: deploy, release, producao,
pagamento, cartao, PCI. Bloqueia o deploy se faltar item.

Observe o padrao: cada description virou uma frase + lista de triggers + opcional bloqueio. Esse e o formato que o agente usa melhor para decidir ativacao.

Muita skill carrega templates: arquivos em references/ ou templates/ com perguntas, checklists ou modelos de documento. Customizar uma skill geralmente significa editar esses arquivos — nao a SKILL.md em si.

Exemplo: a skill /grill-with-docs usa um arquivo QUESTIONS.md com perguntas genericas pra desafiar seu plano. Pra um time que trabalha com regulacao fiscal brasileira, essas perguntas sao insuficientes. Voce adiciona as perguntas do dominio fiscal sem mexer no resto.

# QUESTIONS.md (template original)

## Architecture
- Por que essa solucao e nao outra?
- Quais alternativas voce considerou?
- O que acontece se a carga 10x?

## Data
- Como esses dados sao persistidos?
- Qual o owner do schema?

## Fiscal (BR) — adicionado pelo time
- Esta operacao gera fato gerador de ICMS?
- Tem substituicao tributaria (ICMS-ST) envolvida?
- Estado de origem e destino sao os mesmos? Se nao,
  qual a aliquota interestadual aplicavel?
- O CFOP escolhido bate com a natureza da operacao?
- Existe regime especial (Simples, MEI, Lucro Real)
  que muda o calculo?
- Como o XML da NFe vai refletir essa mudanca?

Note que voce acrescenta, nao remove. Mantem o que veio do upstream (boas praticas gerais de arquitetura e dados) e injeta o conhecimento de dominio. Assim, quando o time fiscal usa /grill-with-docs, ele recebe um interrogatorio que cobre tanto arquitetura geral quanto regras fiscais brasileiras.

Duas estrategias dominam no mundo real: forkar o repo inteiro de skills (voce vira dono de tudo) ou override local em ~/.claude/skills/ (voce mantem o upstream limpo e sobrescreve so o que precisa). Cada uma tem trade-off claro.

A escolha quase nunca é binaria — é um caminho de decisao baseado em quantas skills voce muda e quao critico é manter sync com a comunidade.

Customizacao sem versionamento é perda de tempo. Em algum momento voce vai querer voltar atras, comparar versoes ou compartilhar com o time. A pratica que funciona melhor: branch separado para customizacoes + rebase periodico com upstream.

# 1. Clone o repo de skills (publico ou fork do time)
git clone https://github.com/seu-org/skills.git
cd skills

# 2. Crie um branch para suas customizacoes do dominio
git checkout -b custom/fiscal-br

# 3. Customize as skills (edite SKILL.md, references/, etc)
$EDITOR grill-with-docs/references/QUESTIONS.md

# 4. Commit com mensagem que explica O QUE de dominio mudou
git add grill-with-docs/
git commit -m "grill-with-docs: adiciona perguntas fiscais BR (ICMS-ST, CFOP)"

# 5. Periodicamente, pegue updates do upstream
git fetch origin main
git rebase origin/main

# 6. Se houver conflito, resolva preservando seu dominio
#    Em geral conflitos sao em paragrafos de exemplo,
#    nao em estrutura — facil de resolver.

# 7. Empurre para o seu fork ou repo do time
git push origin custom/fiscal-br --force-with-lease

Tres regras que evitam dor:

• • Commits pequenos por dominio. "adiciona perguntas fiscais" é um commit; "ajusta workflow do grill" é outro. Faz rebase ser barato.
• • Rebase, nao merge. Mantem historico linear; quando voce volta no log, ve exatamente quais skills voce customizou em ordem.
• • Tag de versao quando estabilizar. git tag fiscal-v1.0. Da pra rollback rapido se uma customizacao der ruim.

Vamos juntar tudo em um caso real. Voce é tech lead em uma fintech brasileira. A skill /grill-with-docs da context-mode faz um interrogatorio bom no plano antes de codar, mas nao conhece compliance fiscal. Vamos customizar passo a passo.

# Passo 1: copia para override local
mkdir -p ~/.claude/skills/grill-with-docs-fiscal
cp -r ./grill-with-docs/* ~/.claude/skills/grill-with-docs-fiscal/

# Passo 2: SKILL.md — antes e depois
---
name: grill-with-docs-fiscal
description: Grilling session that challenges your plan
  against the existing domain model.
description: Grilling session that challenges your plan
  against the domain model AND Brazilian fiscal rules.
  Triggers: grill, desafiar plano, plano fiscal, ICMS,
  ICMS-ST, CFOP, NFe, substituicao tributaria, fiscal BR.
  NAO usar para revisao puramente de UI/frontend.
---

# Passo 3: references/QUESTIONS.md — adiciona secao
## Domain Questions — Fiscal BR

### Operacao
- Esta operacao gera fato gerador de ICMS?
- Tem ICMS-ST (substituicao tributaria)?
- Existe DIFAL entre estados envolvidos?
- O CFOP escolhido bate com a natureza da operacao?

### Regime
- Cliente esta em Simples Nacional, Lucro Real ou Presumido?
- Tem regime especial (RETID, Reintegra, Zona Franca)?

### Documento fiscal
- Como NFe vai refletir a mudanca?
- Precisa de carta de correcao para historico?
- Vai impactar SPED Fiscal ou EFD-Contribuicoes?

### Compliance
- A regra esta no nosso parecer juridico fiscal vigente?
- Quem é o owner contabil para validar?

# Passo 4: commit no branch de customizacoes
cd ~/skills-fork
git checkout -b custom/fiscal-br
git add grill-with-docs-fiscal/
git commit -m "grill-with-docs-fiscal: customiza com regras fiscais BR

- adiciona triggers ICMS, ICMS-ST, CFOP, NFe
- adiciona secao Domain Questions com 15 perguntas fiscais
- mantem questoes genericas de arquitetura do upstream"

Resultado: quando voce ou alguem do time roda /grill-with-docs-fiscal num plano que envolve emissao de NFe, o agente passa pelas 15 perguntas fiscais alem das genericas. O plano que sai dali ja considerou substituicao tributaria, DIFAL e SPED — coisa que a skill generica jamais ia perguntar.

Customizacao individual é bom; customizacao compartilhada é multiplicador. Quando o time inteiro usa a mesma versao customizada das skills, as decisoes ficam consistentes — todo PR é revisado com o mesmo rigor, todo plano passa pelo mesmo grill.

# Repo: github.com/empresa/skills-team

# Dev novo: instala todas as skills do time
git clone git@github.com:empresa/skills-team.git ~/.claude/skills

# Dev existente: pega atualizacoes
cd ~/.claude/skills
git pull origin main

# Customizou algo? Manda PR para o monorepo do time
git checkout -b feat/grill-fiscal-novas-perguntas
$EDITOR grill-with-docs-fiscal/references/QUESTIONS.md
git commit -m "grill-fiscal: 3 perguntas sobre EFD-Reinf"
git push origin feat/grill-fiscal-novas-perguntas
gh pr create --fill

Esse fluxo transforma cada melhoria individual em ativo do time. Quando alguem descobre que falta uma pergunta importante, é PR — nao um arquivo na maquina dele que ninguem mais vai usar.

Nem toda necessidade é customizacao. As vezes o que voce precisa é uma skill nova — o workflow é tao diferente que estender uma existente fica pior do que comecar do zero. Quatro perguntas resolvem essa duvida.

Hora de colocar a mao. O exercicio é simples e curto, mas é o que separa quem so leu de quem realmente aprendeu a customizar.