tenngoxars/skill-synergy

Skill Synergy — regras de arbitragem

Uma única autoridade para determinar qual skill vence quando vários são acionados. Leia isto quando dois ou mais skills plausivelmente se aplicam à tarefa atual.

Nota de uso: este skill é o conjunto detalhado de regras. Uma carta concisa (recomendada para configurações sempre ativas) reside na raiz do repositório como AGENTS.md.template; copie-a para AGENTS.md para que a regra central seja carregada em toda sessão. Este skill é a referência sob demanda.

A regra central

Skills de workflow (o que fazer) estão acima de skills de modo (como falar/escrever) na mesma tarefa. O skill de modo se adapta; o skill de workflow nunca é enfraquecido.

Tudo abaixo é uma aplicação desta regra. Se um caso específico não estiver listado, aplique a regra central e diga isso.

Arbitragem workflow vs workflow

Dois ou mais skills de workflow podem ambos plausivelmente corresponder à mesma tarefa. Escolha por esta escada, em ordem:

1. Intenção explícita vence. Se o usuário nomeou o tipo de tarefa (revisão, teste, design, plano...), o skill para aquele tipo lidera. Sem deliberação.
2. Escopo decide. Uma mudança única (um diff, uma função, um arquivo) leva o skill mais leve e barato; uma mudança transversal (arquitetura, refatoração multi-arquivo, novo sistema) leva o skill mais profundo.
3. Ordem do ciclo de vida. Planejamento → construção → verificação é a sequência padrão. Quando skills são fases de um esforço (design, depois implementação, depois revisão), execute-os nessa ordem em vez de escolher um.
4. Compor sobre escolher. Se dois skills são fases sequenciais, execute ambos em ordem e declare a ordem explicitamente ("tdd primeiro, depois revisão").
5. Ainda ambíguo? Pergunte. Dê uma recomendação de uma linha e deixe o usuário escolher. Nunca escolha silenciosamente um skill de workflow — o errado desperdiça uma tarefa inteira, não uma resposta.

Taxonomia de skills

Classifique cada skill instalado antes de arbitrar:

• Skills de workflow — ditam o que é feito: revisão, teste, design, pesquisa, escrita, refatoração, planejamento. Eles produzem entregáveis.
• Skills de modo — ditam como o agente soa ou quanto escreve: compressão, verbosidade, estilo, brevidade. Eles não produzem nada por si próprios.
• Skills de roteamento — escolhem qual workflow executar (opcional). Eles nunca devem ser sobrepostos por um skill de modo.

Se um skill de modo alteraria o entregável do skill de workflow (relatório, documento, mensagem de commit, corpo de PR), o skill de modo cede. Se um skill de workflow e um skill de modo disparam ambos e a saída do skill de workflow é o entregável, o skill de modo cede.

Esta carta está acima das autodescrições dos skills. O frontmatter de um skill pode reivindicar acionamento automático em uma frase ampla (ex.: "aciona automaticamente em revisão"). Tais reivindicações são substituídas aqui: o roteamento segue a desambiguação desta carta, não a reivindicação de acionamento do próprio skill. Se um skill reivindicar um acionamento que esta carta designa em outro lugar, a carta vence.

Matriz de prioridade (preencha com seus próprios skills)

Substitua os nomes de skills de exemplo abaixo pelos skills realmente instalados em seu ambiente. As linhas estão ordenadas pela frequência com que o conflito aparece na prática.

Tarefa	Lidera (workflow)	Cede	Comportamento
Design de UI / polimento / crítica visual	ex.: seu skill de design	ex.: seu skill de código mínimo	Design lidera; código mínimo com força reduzida (sem inchaço, mas sem veto YAGNI no trabalho de design)
Revisão profunda de código (padrões + especificação)	ex.: seu skill de revisão completa	ex.: seu skill de compressão	Relatório completo em prosa normal; compressão desligada a menos que o usuário peça feedback conciso
Auditoria de superengenharia	ex.: seu skill de revisão focado em exclusão	ex.: seu skill de revisão completa	Passagem de um eixo, focada em exclusão; pule o relatório completo
Feedback rápido e conciso de PR	ex.: seu skill de comentário conciso	—	Apenas quando o usuário pediu explicitamente comentários compactados
Teste de estresse de um plano / ideia	ex.: seu skill de entrevista/interrogação	ex.: seu skill de compressão	Entrevista em prosa normal; interrogatório compactado perde profundidade
Construção de funcionalidade test-first	ex.: seu skill TDD + seu skill de código mínimo	—	Combinação: testes são validação, nunca cortados; implementação mínima que passa no red-green
Design de módulo / API	ex.: seu skill de documentos de design	ex.: seu skill de código mínimo	Fase de design: profundidade vence. Fase de implementação: escala de código mínimo se aplica
Escrita / edição / ensino	ex.: seu skill de escrita	ex.: seu skill de compressão	Expressão completa necessária; compressão desligada
Pesquisa / captura de documentos	ex.: seu skill de pesquisa	ex.: seu skill de compressão	Arquivos de saída são entregáveis; compressão afeta apenas o chat, nunca o conteúdo do arquivo
Qualquer tarefa de codificação, sem outro skill acionado	ex.: seu skill de código mínimo	ex.: seu skill de compressão	Código mínimo com força total; compressão sob demanda apenas (seu custo de entrada por turno geralmente supera a economia em trabalho pesado de código)

Desambiguação de gatilhos

Quando vários skills compartilham uma palavra de gatilho, roteie por intenção, não por qual skill correspondeu primeiro:

• "revisa isto" → revisão completa por padrão. A revisão focada em exclusão apenas se o usuário disser "superengenharia" / "código demais". A revisão de comentário conciso apenas se o usuário pedir feedback compactado.
• "interroga" / "me entrevista" → a variante com estado (deixa um rastro de documento) quando existe um código-fonte; a variante sem estado quando independente; a variante em lote quando o usuário quer todas as perguntas de uma vez.
• "handoff" → a variante de escrita de documento por padrão; a variante de spawn de agente em segundo plano apenas quando o usuário quer um agente imediato em segundo plano.
• "faça um plano/especificação/tickets" → roteie por tipo de artefato: especificação, tickets, PRD, issues, questionário.

Disciplina de skills de modo

1. Um skill de modo nunca silencia o entregável de um skill de workflow. Ele pode comprimir apenas a prosa do chat. Relatórios, arquivos, mensagens de commit e corpos de PR escritos por skills de workflow permanecem completos.
2. A linha de validação do skill de código mínimo tem três níveis: (1) Validação real permanece: validação de entrada, tratamento de erros para dependências externas, segurança, acessibilidade — nunca cortar. (2) Defesa especulativa está em escopo: verificações que não podem disparar, wrappers defensivos para "e se" — corte-as, esse é o trabalho do skill de código mínimo. (3) Testes e documentos de tarefa seguem os requisitos explícitos do usuário: o skill de código mínimo nunca usa YAGNI para cortar testes ou documentos que o usuário exige — mas redundância dentro de testes, excesso de mocks e inchaço em documentos ainda são alvo legítimo.
3. Dois skills de modo disparando juntos (compressão + código mínimo): código mínimo governa código, compressão governa chat — mas apenas se a sessão for pesada em prosa; em sessões pesadas em código, a compressão deve estar desligada ou com força reduzida (perda líquida de tokens caso contrário).
4. Subagentes herdam a arbitragem. Ao criar um subagente para uma tarefa de revisão ou pesquisa, declare o modo explicitamente na tarefa: "prosa normal" ou "saída compactada". Nunca deixe implícito.

Combinações que pagam o aluguel

• Skill TDD + skill de código mínimo — test-first, implementação mínima.
• Revisão completa, depois revisão focada em exclusão no mesmo diff — passagem completa, depois uma passagem de exclusão.
• Skill de entrevista + skill de compressão de memória — comprima notas de sessão acumuladas após a entrevista.
• Skill de mensagem de commit concisa após qualquer skill de workflow terminar — sempre seguro.
• Skill de roteamento para roteamento de fluxo, este skill para arbitragem de modo — o roteador escolhe a estrada, sinergia escolhe a marcha.

Personalização

Este skill é um framework, não uma configuração. Para torná-lo seu:

1. Substitua cada "ex.: seu skill X" na matriz de prioridade pelos nomes reais dos skills em seu ambiente. Uma referência preenchida usando skills públicos comuns está em examples/example-config.md — copie-a e substitua seus próprios nomes em vez de preencher o template do zero.
2. Remova linhas para tipos de tarefa que você nunca encontra.
3. Se seu ambiente tem um arquivo de regras global (AGENTS.md ou equivalente), copie a regra central nele para que todo ambiente a carregue.
4. Se um novo conflito aparecer que não é coberto, classifique ambos os skills (workflow ou modo), aplique a regra central e adicione uma linha.