Una skill instalada directamente desde el repositorio público ya funciona — pero funciona de forma genérica. No conoce a tu cliente, tu vocabulario, tu stack ni tus reglas de compliance. El salto de calidad entre una skill buena y es una skill excelente está en una capa fina: el dominio que inyectas en ella.

Personalizar una skill no es rehacerla. Es tomar una base que ya resuelve el problema genérico (revisar código, generar documentación, planificar una funcionalidad) y agregar las 5–10 preguntas, 3 términos técnicos y 2 reglas de negocio que transforman la skill en una colega de equipo que habla el idioma de tu empresa.

Antes de personalizar, necesitas ver la anatomía. Toda skill tiene 3 capas: el frontmatter YAML (metadatos de activación), el cuerpo en Markdown (instrucciones para el agente) y, opcionalmente, archivos de referencia en references/. La mayoría de las personalizaciones ocurre en las dos primeras.

---
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 tiene un papel diferente:

• • name — identificador único. El agente lo usa internamente y tú, en la terminal (/minha-skill).
• • description — el campo más crítico. Es lo que el agente lee para decidir si carga la skill o no. Triggers deficientes = skill muerta.
• • Cuándo usar — escenarios en prosa. Refuerza los triggers y agrega contexto.
• • Workflow — pasos numerados. Es la ruta que sigue el agente.
• • Output format — define el formato de salida. Sin esto, el agente improvisa.

La description ideal tiene 3 partes: cuándo activar (escenario en prosa), disparadores explícitos (palabras clave) y, opcionalmente, contraindicaciones (cuándo NO activar). Este formato reduce drásticamente los falsos positivos y los falsos negativos.

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

Observa el patrón: cada description se convirtió en una frase + lista de activadores + bloqueo opcional. Este es el formato que el agente usa mejor para decidir cuándo activarse.

Se carga demasiada skill templates: archivos en references/ o templates/ con preguntas, listas de control o modelos de documentos. Personalizar una skill generalmente significa editar estos archivos, no el archivo SKILL.md en sí.

Ejemplo: la skill /grill-with-docs usa un archivo QUESTIONS.md con preguntas genéricas para cuestionar tu plan. Para un equipo que trabaja con regulación fiscal brasileña, estas preguntas son insuficientes. Tú agrega las preguntas del dominio fiscal sin tocar el 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?

Observa que tú agrega, no elimina. Mantiene lo que viene del upstream (buenas prácticas generales de arquitectura y datos) y inyecta el conocimiento del dominio. Así, cuando el equipo fiscal usa /grill-with-docs, recibe un interrogatorio que cubre tanto arquitectura general cuánto reglas fiscales brasileñas.

Dos estrategias dominan en el mundo real: hacer fork de todo el repo de skills (te conviertes en responsable de todo) o override local en ~/.claude/skills/ (tú mantienes limpio el upstream y sobrescribes solo lo que necesitas). Cada una tiene un trade-off claro.

La elección casi nunca es binaria: es un camino de decisión según cuántas skills cambies y qué tan importante sea mantener la sincronización con la comunidad.

Personalizar sin control de versiones es una pérdida de tiempo. En algún momento querrás volver atrás, comparar versiones o compartir con el equipo. La práctica que mejor funciona: rama separada para personalizaciones + rebase periódico con 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 reglas que evitan problemas:

• • Commits pequeños por dominio. "agregar preguntas fiscales" es un commit; "ajustar el workflow del grill" es otro. Hace que el rebase sea barato.
• • Rebase, no merge. Mantiene un historial lineal; cuando vuelves al log, ves exactamente qué skills personalizaste y en qué orden.
• • Etiqueta de versión cuando se estabilice. git tag fiscal-v1.0. Puedes revertir rápidamente si una personalización sale mal.

Vamos a juntar todo en un caso real. Eres tech lead en una fintech brasileña. La skill /grill-with-docs de context-mode hace un buen interrogatorio durante la planificación antes de programar, pero no conoce el cumplimiento fiscal. Vamos a personalizarlo paso a paso.

# 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: cuando tú o alguien del equipo ejecuta /grill-with-docs-fiscal en un plan que implica emitir NFe, el agente pasa por las 15 preguntas fiscales además de las genéricas. El plan que sale de ahí ya consideró la sustitución tributaria, DIFAL y SPED, algo que la skill genérica nunca te preguntaría.

La personalización individual es buena; la personalización compartida es un multiplicador. Cuando todo el equipo usa la misma versión personalizada de las skills, las decisiones son coherentes: todos los PR se revisan con el mismo rigor y todos los planes pasan por el mismo interrogatorio.

# 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

Este flujo convierte cada mejora individual en un activo del equipo. Cuando alguien descubre que falta una pregunta importante, es un PR — no un archivo en su máquina que nadie más va a usar.

No todas las necesidades requieren personalización. A veces lo que necesitas es una skill nueva — el workflow es tan diferente que extender uno existente resulta peor que empezar desde cero. Cuatro preguntas resuelven esa duda.

Es hora de ponerse manos a la obra. El ejercicio es sencillo y breve, pero es lo que distingue a quien solo leyó de quien realmente aprendió a personalizar.