Skill Author — Meta-Skill de Governanca do Kit

Cria e mantem as outras skills com qualidade. Sem esta skill, o kit cresce por copia-cola e cada nova skill diverge das convencoes — divida tecnica acumula em meses.

Governanca Global

Esta skill segue GLOBAL.md, policies/execution.md, policies/evals.md, policies/handoffs.md, policies/writing-clarity.md, policies/source-driven.md, policies/verification-before-completion.md e policies/mcp-builder-patterns.md (quando skill criada expõe MCP tool).

Inspirado no padrao "skill-creator" da Anthropic (skill meta de criacao/avaliacao de skills disponivel no plugin oficial anthropic-skills), adaptado as convencoes deste kit: numeracao sequencial, frontmatter YAML, secao "Governanca Global", integracao com pipeline (orchestrator, context manager, documenter, reviewer). Esta skill nao depende do plugin Anthropic — e implementacao propria com convencoes do dev-team-kit.

Quando Usar

• adicionar nova skill (numero >= 34, sequencial)
• refatorar skill existente (split, merge, deprecation)
• avaliar qualidade de skill (description triggering, completude, redundancia)
• otimizar description para melhor triggering em conversas reais
• onboarding: ensinar contribuidor novo a estrutura
• antes de publicar release: revisar todas as skills modificadas

Quando Nao Usar

• editar conteudo de uma skill especifica que ja existe e funciona (use Edit direto)
• criar persona, policy, command (use template proprio de cada)
• documentar processo do projeto consumidor (use skill 28 CLAUDE.md Generator)

Entradas Esperadas

• intencao: criar / editar / avaliar / otimizar
• (criar) nome da nova skill, dominio, gap que preenche
• (editar) caminho da skill alvo, mudanca proposta
• (eval) caminho da skill alvo + criterios

Saidas Esperadas

• (criar) skills/NN-nome/SKILL.md + atualizacoes em plugin.json, README, AGENTS, CHANGELOG
• (editar) diff cirurgico + justificativa
• (eval) relatorio de qualidade com score + acoes
• handoff para reviewer (skill 11)

Convencoes do Kit (obrigatorias)

Numeracao

• sequencial (proxima livre): consultar ls skills/
• numero nunca se reutiliza apos deprecation (skill 16 e exemplo — absorvida pela model-routing policy, numero permanece vago)
• formato: NN-nome-com-hifen

Estrutura de SKILL.md

Toda skill segue este template (campos obrigatorios marcados ★):

---
name: nome-curto-com-hifen ★
description: | ★
  Uma frase de propósito (≤160 chars). Trigger em: ≤12 frases.
  Teto total 400 chars — a description vai no system prompt de todo turno.
argument-hint: "[descricao dos argumentos opcional]"
allowed-tools: Read, Grep, Glob, Bash(comando *), Edit, Write
---

# Nome da Skill — Subtitulo Descritivo ★

Uma frase introdutoria sobre o proposito. ★

## Governanca Global ★
Lista de policies que esta skill segue.

## Quando Usar ★
3-7 bullets concretos.

## Quando Nao Usar ★
3-5 bullets concretos para evitar acionamento errado.

## Entradas Esperadas
O que a skill recebe.

## Saidas Esperadas ★
O que a skill produz (formato, caminho, criterios).

## Responsabilidades / Protocolo ★
Conteudo principal. Pode ter sub-secoes.

## Heuristicas / Boas Praticas
Especificas do dominio.

## Anti-Padroes
O que evitar (especifico, nao generico).

## Gotchas
Falhas REAIS ja vistas ao usar esta skill, uma linha cada, no formato "o que parece / o que e de fato / como detectar".
Comece vazia e cresca a cada falha (nao invente gotcha para preencher a secao). Ver "Gotchas" abaixo.

## Evidencia de Conclusao ★
Como saber se a skill cumpriu seu objetivo.

## Handoff ★
Para qual skill/persona/agente entregar resultado.

## Integracao com Pipeline ★
Como esta skill se conecta com Orchestrator (09), Context Manager (08), Documenter (10), Reviewer (11) e outras relevantes.

Gotchas (a secao de maior valor)

Origem: "Lessons from building Claude Code: how we use skills" (claude.dev). O que o modelo ja sabe nao precisa estar na skill; o que ele erra repetidamente, sim.

• Cada gotcha vem de uma falha observada, nao de previsao. Fontes validas: um learned-skill aceito (.bot/learned-skills/), um bug que voltou, um comentario de review repetido, uma linha do CHANGELOG com "corrigido". Se nao ha fonte, nao escreva.
• Formato: uma linha — sintoma → causa real → como confirmar. Ex.: "staging responde 200 mesmo com o webhook falho → olhe payment_events para o estado real".
• Especifico do seu sistema: "valide inputs" e generico e nao entra; "a tabela subscriptions e append-only, use a maior version" entra.
• Mantenha: quando um learned-skill com files: da skill for aceito, promova a regra para a secao Gotchas e marque o learned-skill superseded (ver policies/learned-skills.md).
• node scripts/skill-health.mjs lista as skills ainda sem a secao (informativo — nao e erro: skill nova pode nao ter falha conhecida ainda).

Description: Triggering

A description no frontmatter e o catalogo do harness: Claude/Codex/Grok injetam name + description de todas as skills do plugin em todo turno. O body e lazy; a description nao. Otimizar para descoberta e budget:

Boa description (≤400 chars, ≤12 triggers):

description: |
  Scan SAST via Semgrep e CodeQL. Use antes de release ou em PRs grandes.
  Trigger em: "semgrep", "codeql", "static analysis", "scan de seguranca", "SAST", "varredura".

Description ruim:

description: Skill que faz coisas relacionadas a seguranca.

Description gorda (tambem ruim): 800–1200 chars com 30+ triggers. Codex emite "Skill descriptions were shortened" e corta os triggers do fim. Prosa de protocolo vai no body.

Medir: node scripts/skill-catalog-budget.mjs. Policy: policies/skill-manifest.md.

Allowed-tools

Listar o minimo necessario. Cada tool a mais e risco a mais.

• skills puramente de planejamento: Read, Grep, Glob apenas
• skills que escrevem doc: + Write, Edit
• skills que rodam comando: + Bash(comando especifico *) — escopar com glob
• skills destrutivas: explicitar e exigir aprovacao

Verbosidade

• SKILL.md cabe em 300-400 linhas quando possivel
• exemplos longos vao para docs/skill-guides/<nome>.md (carregado sob demanda)
• templates reutilizaveis vao para templates/

Pipeline de Criacao de Skill Nova

Fase 1: Spec da skill (antes de escrever)

Brainstorm:

• Gap real? Que problema esta skill resolve que nenhuma outra resolve hoje?
• Overlap? Que skills existentes tocam dominios proximos? Como evitar duplicacao?
• Trigger natural? Que palavras um usuario diria quando precisar disso?
• Output? O que esta skill produz que outras consomem?
• Custo? Vale criar skill ou e melhor adicionar secao em skill existente?

Se >50% das respostas indicarem que basta editar skill existente, nao crie skill nova.

Fase 2: Numero + diretorio

# Proxima skill livre
ls skills/ | grep -oE '^[0-9]+' | sort -n | tail -5
# Ex: ultima e 33, proxima e 34

mkdir skills/34-novo-nome

Fase 3: SKILL.md

Usar o template acima. Validar:

• todos os campos ★ preenchidos
• description com trigger words
• governance section listando policies relevantes
• integracao com pipeline declarada

Fase 4: Registrar

Skill nova:

1. .claude-plugin/plugin.json — adicionar caminho na lista skills
2. README.md — linha na tabela "The N Specialists" + bump nos contadores (badge, hero, install)
3. README.pt-BR.md — espelhar
4. AGENTS.md — somente se a skill introduzir slash command novo (tabela de comandos)
5. docs/WIKI.md + docs/WIKI.pt-BR.md — entrada completa formato aihero
6. docs/SKILLS-OVERVIEW.md — entrada curta no índice
7. CHANGELOG.md — entrada Added/Changed

Se a skill tiver subagent dispatchavel (.claude/agents/X.md):

• adicionar ao agents em plugin.json
• listar na tabela de Subagents do README (ambos idiomas) + WIKI

Se a skill tiver slash command (.claude/commands/X.md):

• adicionar ao commands em plugin.json
• tabela de commands em README (ambos) + AGENTS.md + WIKI (ambos) + SKILLS-OVERVIEW
• se introduz pipeline novo: criar programs/<nome>.md e registrar no programs/README.md
• se exerce autoridade sobre outras skills (tipo /constitution): atualizar skills relevantes para consulta-lo
• atualizar policies/handoffs.md se afeta a cadeia canonica

Eval coverage:

• evals/commands/<nome>/golden.json (3-4 casos: happy path, edge, anti-padroes)
• se apoiado por subagent com protocol shell: tambem evals/protocol-shells/<subagent>/

Prosa gerada pela skill:

• Se a skill produz qualquer prosa que humanos vão ler (docs, summarys, PRDs, copy), referenciar policies/anti-ai-writing.md na seção de governança e oferecer /humanize como passe final.

Consistency check:

• adicionar assercao em scripts/check-consistency.mjs (command registrado em plugin.json + skills criticas referenciam se aplicavel)
• rodar node scripts/check-consistency.mjs — deve passar antes de commit

Release hygiene (em main):

• bump semver em README badges, plugin.json, mcp-server/package.json, SKILLS-OVERVIEW header
• git tag vX.Y.Z -m "..." + gh release create vX.Y.Z

Fase 5: Eval

Rodar checklist (evals/skill-quality.md — criar se nao existir):

Score total / 30. Threshold para merge: >= 22.

Fase 6: Handoff

Despachar reviewer (subagent ou skill 11) para validacao final antes de merge.

Pipeline de Edicao

Para mudancas estruturais (>20 linhas alteradas):

1. Spec da mudanca — o que muda, por que, qual impacto downstream
2. Diff cirurgico — preservar estrutura existente
3. Atualizar referencias cruzadas — outras skills que mencionam esta
4. Re-run eval — score nao deve cair
5. CHANGELOG — registrar mudanca

Para mudancas pequenas (typo, clarification): Edit direto, mencionar em commit message.

Pipeline de Avaliacao

# Avaliar uma skill
/skill-author --action=eval --skill=skills/05-qa-testing/

# Output esperado:
# - score 0-30 com breakdown
# - top 3 melhorias prioritarias
# - comparacao com skills do mesmo dominio

Skills com score < 18: rotular como needs-rewrite no CHANGELOG e priorizar.

Pipeline de Otimizacao de Description

Description controla descoberta. Otimizar quando:

• skill nao e acionada quando deveria (usuario descreve, agente nao escolhe)
• skill e acionada erradamente (overlap com outra)

Tecnica:

1. Coletar 5-10 transcricoes onde a skill deveria ter sido acionada
2. Listar palavras/frases recorrentes
3. Adicionar como "Trigger em:" na description
4. Re-testar com as mesmas transcricoes — se alguma ainda nao aciona, voltar ao passo 2 com aquela transcricao especifica (a frase que faltou ainda nao esta nos triggers); repetir ate as 5-10 acionarem. Adicionar trigger novo sem re-testar as anteriores corre o risco de criar overlap com outra skill sem perceber.

Anti-Padroes (em criacao de skill)

"Skill kitchen-sink"

Skill que faz 8 coisas diferentes. Quebrar em 2-3 skills focadas.

"Skill com description vaga"

"Skill que ajuda com codigo." → nao trigga nunca.

"Skill que duplica outra"

Antes de criar, grep -r "<dominio>" skills/. Se 2+ skills tocam, e edicao, nao criacao.

"Skill sem handoff"

Skill que produz output mas nao declara para quem entregar = dead end no pipeline.

"Skill sem anti-padroes"

Lista de "boas praticas" generica, sem armadilhas concretas. Anti-padroes vem de bug real ou erro recorrente.

"Skill com 1000 linhas"

Indica falta de modularizacao. Mover exemplos para docs/skill-guides/. Quebrar se for caso.

"Tools demais"

allowed-tools: * — risco operacional. Listar so o que precisa.

Evidencia de Conclusao

(Criacao)

• skills/NN-nome/SKILL.md criado
• registrada nos 5 lugares (plugin.json, README.md, README.pt-BR.md, AGENTS.md se houver slash command, CHANGELOG.md)
• score eval >= 22
• review aprovado

(Edicao)

• diff cirurgico aplicado
• referencias cruzadas atualizadas
• score eval mantido ou melhorado

(Eval)

• relatorio com score + breakdown + acoes priorizadas

Handoff

• Reviewer (skill 11): valida qualidade final antes de merge
• Documenter (skill 10): atualiza docs externos se skill afeta interface publica
• Orchestrator (skill 09): registra nova capacidade no roteamento
• Context Manager (skill 08): atualiza working set se skill modifica fluxos comuns

Integracao com Pipeline

• esta skill e meta — opera sobre as outras
• chamada por contribuidores quando adicionam capacidade
• chamada em release prep para auditar consistencia
• complementa Repo Auditor (skill 18) que opera sobre projetos consumidores