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:

.claude-plugin/plugin.json — adicionar caminho na lista skills
README.md — linha na tabela "The N Specialists" + bump nos contadores (badge, hero, install)
README.pt-BR.md — espelhar
AGENTS.md — somente se a skill introduzir slash command novo (tabela de comandos)
docs/WIKI.md + docs/WIKI.pt-BR.md — entrada completa formato aihero
docs/SKILLS-OVERVIEW.md — entrada curta no índice
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):

Criterio	Score 0-3
Triggering: description tem palavras-gatilho concretas?	0-3
Quando usar: 3+ bullets concretos?	0-3
Quando NAO usar: 3+ bullets concretos?	0-3
Output esperado: formato e caminho declarados?	0-3
Tools: minimo necessario?	0-3
Anti-padroes: lista de armadilhas reais?	0-3
Integracao: aponta para skills upstream/downstream?	0-3
Verbosidade: cabe em 400 linhas?	0-3
Writing clarity: respeita `policies/writing-clarity.md`?	0-3
Anti-rationalization: skill rigida tem tabela de vies?	0-3 (N/A se flexivel)

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):

Spec da mudanca — o que muda, por que, qual impacto downstream
Diff cirurgico — preservar estrutura existente
Atualizar referencias cruzadas — outras skills que mencionam esta
Re-run eval — score nao deve cair
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:

Coletar 5-10 transcricoes onde a skill deveria ter sido acionada
Listar palavras/frases recorrentes
Adicionar como "Trigger em:" na description
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