A skill installed directly from the public repository already works — but it works generically. It doesn't know your customer, your vocabulary, your stack, or your compliance rules. The quality gap between a skill good is a skill excellent it’s in a thin layer: the domain you inject into it.

Customizing a skill doesn't mean redoing it. It means taking a foundation that already solves the generic problem (reviewing code, generating documentation, planning a feature) and adding the 5–10 questions, 3 technical terms, and 2 business rules that turn the skill into a teammate who speaks your company’s language.

Before customizing, you need to understand its anatomy. Every skill has 3 layers: the YAML frontmatter (activation metadata), the body in Markdown (instructions for the agent) and, optionally, reference files in references/. Most of the customization happens in the first two.

---
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.

Each part has a different role:

• • name — unique identifier. Used internally by the agent and by you in the terminal (/minha-skill).
• • description — the most critical field. It's what the agent reads to decide whether to load the skill. Bad triggers = a dead skill.
• • When to use — scenarios in prose. Reinforces the triggers and adds context.
• • Workflow — numbered steps. It's the playbook the agent follows.
• • Output format — defines the output format. Without it, the agent improvises.

The ideal description has 3 parts: when to activate (scenario in prose), explicit triggers (keywords) and, optionally, contraindications (when not to activate). This format drastically reduces false positives and false negatives.

# 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.

Notice the pattern: each description became a phrase + list of triggers + optional blocking. This is the format the agent uses best to decide when to activate.

A lot of skills load templates: files in references/ or templates/ with questions, checklists, or document templates. Customizing a skill usually means editing these files — not the SKILL.md itself.

Example: the skill /grill-with-docs uses a file QUESTIONS.md with generic questions to challenge your plan. For a team that works with Brazilian tax regulations, these questions aren't enough. You adds the tax domain questions without changing the rest.

# 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?

Notice that you adds, doesn't remove it. It keeps what came from upstream (general architecture and data best practices) and injects domain knowledge. That way, when the tax team uses /grill-with-docs, they get an interrogation that covers both overall architecture how much Brazilian tax rules.

Two strategies dominate in the real world: fork the entire repo of skills (you become responsible for everything) or local override in ~/.claude/skills/ (you keep the upstream clean and override only what you need). Each has a clear trade-off.

The choice is almost never binary—it’s a decision path based on how many skills you change and how critical it is to stay in sync with the community.

Customization without version control is a waste of time. At some point, you'll want to roll back, compare versions, or share with the team. The practice that works best: separate branch for customizations + periodic rebase with 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

Three rules that prevent pain:

• • Small commits by domain. "add tax questions" is one commit; "adjust the grill workflow" is another. Makes rebasing cheap.
• • Rebase, don't merge. Keeps the history linear; when you go back through the log, you can see exactly which skills you customized, in order.
• • Version tag when stable. git tag fiscal-v1.0. You can roll back quickly if a customization goes wrong.

Let's bring it all together in a real case. You're a tech lead at a Brazilian fintech. The skill /grill-with-docs of the context-mode does a good grilling in the planning phase before coding, but doesn’t know tax compliance. We’ll customize it step by step.

# 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"

Result: when you or someone on the team runs /grill-with-docs-fiscal in a plan involving NFe issuance, the agent goes through the 15 compliance questions in addition to the general ones. The plan that comes out of it has already accounted for tax substitution, DIFAL, and SPED — things the generic skill would never ask about.

Individual customization is good; shared customization is a multiplier. When the whole team uses the same customized version of the skills, decisions stay consistent — every PR gets reviewed with the same rigor, and every plan goes through the same grilling.

# 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

This workflow turns each individual improvement into a team asset. When someone realizes an important question is missing, it becomes a PR — not a file on their machine that nobody else will use.

Not every need calls for customization. Sometimes what you need is a skill new — the workflow is so different that extending an existing one is worse than starting from scratch. Four questions resolve that uncertainty.

Time to get hands-on. The exercise is simple and short, but it’s what separates those who have only read from those who have really learned to customize.