Skills Constitution (Constituição de Habilidades)

Resumo: Meta-regra que se sobrepõe a todas as skills/ferramentas/plugins. Toda invocação de capacidade deve passar por este filtro.

v2.25.0 (atual) — Artigo 5º "Recomendação na Resposta" extremamente econômico em tokens: a fonte de recomendações mudou de "pesquisa completa no GitHub" para leitura de snapshot local de rankings (data/skill_rankings.json + scripts/recommend_skills.py — zero rede, ~20KB, correspondência puramente determinística + exclusão automática de skills já instaladas); novo scripts/update_skill_rankings.py para busca de baixa frequência de rankings oficiais (quemsah/awesome-claude-plugins, indexando 36k+ repositórios) recriando o snapshot; snapshots expirados (>30 dias) apenas geram aviso, sem pull automático; o passo 5 agora inclui validação suave da fonte de recomendação (marcar "snapshot local de rankings" = melhor prática para economia de tokens). v2.24.0 — Governança de skills invisíveis + portaria "verificação única por tarefa, liberação para todo o percurso" + índice leve. Cinco correções comprovadas: ① parse_frontmatter agora suporta escalares de bloco YAML (>/| e variações dobradas) — versão antiga transformava a descrição de 137 skills (incluindo ponytail) em um único caractere >, tornando-as impossíveis de encontrar na busca (caso típico: usuário instalou ponytail, com 116k★ no GitHub, mas ela nunca era chamada); ② Limite superior da descrição no índice aumentou de 200 para 2000 — palavras-gatilho (como "lazy mode" do ponytail, localizadas após o 400º caractere) não são mais truncadas e descartadas; ③ Passe de nível de tarefa para a portaria — as três verificações realizadas no início da tarefa (seja por injeção da plataforma ou passo 1 PASS) liberam todo o percurso; a interceptação foi movida para um aviso único no início da tarefa (usuário explicitou: verificações feitas no início, não interromper no meio); ④ Novo scripts/skill_doctor.py: diagnóstico automático de skills corrompidas/invisíveis (8 tipos de verificação) + --fix para reparo automático + --quarantine para isolar corrompidas + --emit-min-index para índice leve (~20% do volume do índice completo, parte truncada mantém palavras-gatilho de cauda longa, skills de nicho economizam tokens ainda podem ser encontradas); ⑤ Extração de âncoras do grafo agora fixada nos primeiros 200 caracteres + expansão de stopwords em três lotes + limite superior de DF de 0,05 para 0,035 — a descrição mais ampla gerou um aglomerado de 752 nós; agora restaurado para a disciplina ≤80 (testes de regressão 106/106). v2.23.0 — Grafo de habilidades (inspirado na inteligência relacional pré-computada do GitNexus): sobre a árvore de habilidades, é sobreposto um grafo de relações determinísticas (skill_graph.json, gerado automaticamente durante a reconstrução da árvore). Três tipos de arestas são extraídos deterministicamente sem dependências externas — chains_to (interseção dos schemas de saída→entrada do registry), co_anchor (âncoras de entidades compartilhadas, com filtragem de stopwords e frequência de documentos), alternative (soluções alternativas de alta sobreposição na mesma categoria); propagação de rótulos determinística forma clusters funcionais. Três aplicações: ① O bloco de injeção é reduzido de "lista completa de categorias" para "grafo da linha de tarefas das skills âncora" (com rastreabilidade de "por que é relevante", economizando tokens); ② A portaria passo 3 adiciona validação de evidência de grafo Layer F — a skill referenciada deve estar conectada ao grafo âncora da tarefa; sem evidência de cluster com conectividade, resulta em FAIL; ③ Arestas de alternativa não são usadas como credencial de liberação nem participam da clusterização (disciplina do GitNexus: apenas arestas estruturais passam por detecção de comunidade). Na ausência do grafo, todo o comportamento da cadeia permanece idêntico à versão anterior (apenas adiciona, não remove).

Histórico completo de versões em CHANGELOG.md.

⚠️ Filtro Prévio: Classificação do Tipo de Tarefa (Cláusula Zero)

Esta Constituição aplica-se apenas a "tarefas profissionais", não a perguntas e respostas simples. Antes de executar, classifique:

Tipo de Tarefa	Características	Verificar Skills?
Pergunta Simples	Tradução, revisão, explicação de conceito, conhecimento geral	❌ Pular
Tarefa Profissional	Codificação, raspagem de dados, operações de arquivo, chamadas de API, análise complexa	✅ Obrigatório
Tarefa Ambígua	Incerteza se necessita de ferramentas profissionais	✅ Verificar (melhor prevenir)

Critérios de Julgamento:

Tarefa envolve sistema de arquivos, requisições de rede, execução de código, ferramentas profissionais → Tarefa Profissional
Tarefa é apenas processamento de texto, perguntas de conhecimento, explicação simples → Tarefa Simples

Auto-isenção: Esta Constituição em si é uma meta-regra. A execução de suas cláusulas não requer nova verificação de skills (evitando loop infinito).

Fallback para Erro de Julgamento (Cláusula Zero-C): Se o Agente classificar incorretamente o tipo de tarefa (ex.: tratar uma tarefa profissional como pergunta simples), o usuário tem o direito de apontar ("Isto é uma tarefa profissional, você deve verificar as skills"). Nesse caso, o Agente deve:

Desculpar-se e reconhecer o erro de julgamento
Imediatamente retornar ao fluxo completo da Constituição (começando pela verificação de memória)
Registrar este erro de julgamento na camada de memória (MISJUDGMENTS), para evitar repetição

Problema

O maior desperdício no ecossistema de Agentes: instalar um monte de Skills e ainda assim tentar resolver tarefas manualmente, ou escolher com base na memória, julgar mal as capacidades, nunca pesquisar. Esta Constituição transforma "verificar capacidade → corresponder → usar obrigatoriamente → pesquisar → recomendar" em um fluxo obrigatório, e usa uma portaria (constitution-check) para transformar "contar com a boa vontade" em algo "verificável e passível de interceptação".

Conceitos Principais (Independentes de Plataforma)

Esta Constituição usa os seguintes termos genéricos. Os equivalentes específicos de cada plataforma podem ser encontrados na Tabela de Mapeamento de Plataformas.

Termo Genérico	Significado	Exemplos por Plataforma
Registro de Capacidades	Lista de todas as skills/ferramentas/plugins disponíveis atualmente para o Agente	available_skills / tools / plugins / extensions / Gems / MCP servers
Descrição da Skill	Instruções sobre as condições de ativação de cada capacidade	description / trigger / when_to_use / system prompt
Índice de Skills	Árvore de skills classificadas por função (pré-gerada, para acelerar a correspondência). ⚠️ O arquivo `skill_tree.json` no repositório é um snapshot/exemplo do autor. O usuário deve executar `scripts/build_skill_tree.py` para gerar seu próprio índice	skill_tree.json (snapshot do autor) / Sua árvore de skills gerada
Descoberta de Skills	Pesquisar por novas capacidades instaláveis	find-skills / GPT Store / SkillHub / MCP Registry / Extensions
Camada de Memória	Armazenamento de regras persistido entre sessões	MEMORY.md / CLAUDE.md / AGENTS.md / Custom Instructions / .cursorrules
Arquivo de Skill	Documento estruturado que define uma capacidade	SKILL.md / GPT Actions / MCP Config / Gem Instructions

Cláusulas da Constituição

Artigo Zero: Verificar Memória (Pre-Check Memory)

Antes de executar qualquer tarefa, é obrigatório consultar a camada de memória/regras da plataforma para confirmar se há regras relevantes, contexto histórico ou itens pendentes.

Caminhos da Camada de Memória por Plataforma:

Plataforma	Caminho da Camada de Memória
WorkBuddy	`~/.workbuddy/MEMORY.md` + projeto `.workbuddy/memory/`
Claude Code	`CLAUDE.md` ou `.claude/CLAUDE.md`
Cursor	`.cursorrules` + `.cursor/rules/`
Windsurf	`.windsurfrules`
Cline	`.clinerules`
ChatGPT	Custom Instructions
Gemini	Gem Instructions
Codex	AGENTS.md
Regra Geral	`RULES.md` na raiz do projeto ou `.agent/rules.md`

Ordem de Verificação de Memória:

Memória do usuário (preferências de longo prazo, regras rígidas)
Memória do projeto (convenções do projeto atual, decisões históricas)
Pipeline do dia (registro de trabalho do dia, evitar repetição)

Conteúdo Obrigatório na Camada de Memória (premissa de auto-inicialização: fazer com que "verificar memória" realmente descubra skills, novo na v2.3.0):

Para que a Constituição se auto-inicialize, a camada de memória deve manter os seguintes dois tipos de entradas:

Entrada	Conteúdo	Exemplo
`INSTALLED_SKILLS`	Lista de skills instaladas (nome + descrição em uma frase)	`file-ops: Ferramenta de leitura/escrita de arquivos, usada para ler o índice de skills`
`SKILL_INDEX_PATH`	Caminho para o arquivo de índice de skills (sua árvore, não o snapshot do autor)	`<diretório de skills da sua plataforma>/skill_tree.json` (ex.: `~/.claude/skills/`)

Exemplo:

INSTALLED_SKILLS:
- file-ops: Ferramenta de leitura/escrita de arquivos, usada para ler o índice de skills
- find-skills: Ferramenta de pesquisa de skills, usada para descobrir novas capacidades
- agent-memory: Sistema de gerenciamento de memória

SKILL_INDEX_PATH: <seu diretório de skills>/skill_tree.json

Mantendo a camada de memória neste formato, o Agente, ao verificar a memória, pode "lembrar" da lista de skills, sem necessidade de escaneamento em tempo real, resolvendo o problema de inicialização a frio.

Artigo 1: Verificar Primeiro (Pre-Check)

Antes de executar qualquer tarefa profissional, é obrigatório primeiro verificar o registro de capacidades para determinar se há alguma capacidade relevante para a tarefa atual.

Caminho Otimizado (novo na v2.2.0; corrigido na v2.7.0):

Primeiro, verifique o registro de capacidades da sua plataforma (lista de skills/ferramentas/plugins disponíveis, ex.: Claude Code ~/.claude/skills, Cursor .cursor/rules, WorkBuddy available_skills); se houver uma árvore de skills local, priorize-a (execute scripts/build_skill_tree.py para gerar seu próprio índice)
Localize o ramo funcional com base no tipo de tarefa
Dentro do ramo, corresponda a descrição
Se não houver correspondência, faça uma varredura completa (fallback)

Reforço de Execução (novo na v2.5.0, passo incondicional; v2.11.0, lista de correspondências obrigatória):

"Verificar o índice de skills primeiro" deve ser uma ação incondicional, não algo como "verifico se achar necessário":

Qualquer tarefa profissional (incluindo tarefas do tipo "verificar instalação/biblioteca", como confirmar se uma biblioteca Python está instalada) deve primeiro ler o índice da árvore de skills. É proibido pular com base em "isso não precisa verificar skills" — pular baseado em julgamento é exatamente o comportamento que esta Constituição visa prevenir (lição: em execução real, ao verificar cognee, o usuário flagrou o agente pulando a árvore de skills).
O índice da árvore de skills deve incluir skills (independentes + plugins, v2.21.0) e bibliotecas/ferramentas Python instaladas (categoria 🧩), um único ponto de entrada para verificar tudo.

No início da tarefa, deve-se relatar explicitamente o resultado das "Três Verificações da Constituição", tornando o fluxo visível e auditável pelo usuário. v2.11.0 obrigatório: ② A árvore de skills deve listar a lista de nomes de skills correspondentes (nome + justificativa), proibido apenas escrever "árvore de skills lida":

【Três Verificações da Constituição】
① Memória ✅ Verificada (usuário/projeto/pipeline do dia)
② Árvore de skills ✅ Lida (lista de skills correspondentes: `git-workflow-and-versioning` (código/implantação), `web-deploy-github` (push GitHub)…)
③ Correspondência ✅ Encontrada X → Usá-la para executar; Nenhuma → Explicar "árvore de skills sem correspondência" e então usar capacidades gerais/sistema de arquivos

v2.11.0 Validação Rígida Relacionada à Tarefa (Layer C): Quando a tarefa contém palavras-chave como "código/codificação/programação/desenvolvimento/escrever um/implementar/git/github/push/commit/deploy/implantação/raspador/raspagem/página web/frontend/documento/dados/e-mail/imagem/vídeo", a saída deve citar o nome real da skill na categoria correspondente do skill_tree.json (ex.: git-workflow-and-versioning). Apenas escrever "consultei skills-constitution" ou "li a árvore de skills" sem o nome específico da skill → Portaria FAIL
Isenção para perguntas e respostas simples (tradução/revisão/explicação de conceitos)

Suplemento ao Artigo 1: Cobertura de Plataformas de Mecanismo Duplo (v2.21.0)

Em plataformas como ZCode / Claude Code / DeepSeek Harness (dsh), as capacidades vêm de dois mecanismos paralelos — skills independentes (SKILL.md no diretório de skills) e skills de plugins (SKILL.md dentro do pacote do plugin). Esta Constituição, quando se refere a "registro de capacidades / biblioteca de skills / árvore de skills", cobre ambos simultaneamente:

Mesmo peso: Skills de plugins e skills independentes têm status idêntico no fluxo "verificar primeiro → corresponder e usar obrigatoriamente". É proibido contornar a correspondência sob o pretexto de "é um plugin, não uma skill"
Nome de chamada completo: O nome de chamada de uma skill de plugin geralmente é plugin:skill (ex.: document-skills:docx, computer-use:computer-use). Após a correspondência, deve ser chamada pelo nome completo (em plataformas de mecanismo duplo, nomes de skills nus podem não ser carregados pelo mecanismo de Skill)
Inclusão automática na árvore: build_skill_tree.py escaneia automaticamente o cache de plugins, compila na árvore de skills e anota o nome de chamada (caminhos de plataforma conhecidos são descobertos automaticamente; outras plataformas usam a variável de ambiente PLUGIN_CACHE_DIRS ou o arquivo plugin_roots.json na raiz do repositório para especificar diretórios de cache; plugins/mercados desativados são excluídos automaticamente)
Mesmas regras para capacidades anexas de plugins: Comandos de barra / ferramentas MCP fornecidos por plugins também pertencem ao "registro de capacidades". Quando uma capacidade existente está disponível, é proibido reinventar a roda usando capacidades gerais

Artigo 2: Corresponder e Usar Obrigatoriamente (Mandatory Use)

Sempre que a tarefa for relacionada ou parcialmente relacionada à descrição de uma capacidade → carregue incondicionalmente essa capacidade com prioridade e execute de acordo com suas instruções.

Comportamentos Proibidos:

❌ Contornar a capacidade e usar capacidades gerais diretamente
❌ Escolher capacidades com base na memória, sem ler a descrição
❌ Quando houver múltiplas correspondências, escolher uma aleatoriamente (deve ordenar por relevância e selecionar a melhor)

Cláusula de Prevalência: Mesmo que uma capacidade diga "Posso fazer isso diretamente", ela deve primeiro passar pela confirmação desta Constituição de que não há uma capacidade melhor correspondente.

Artigo 3: Sem Correspondência → Descoberta de Skills (Search First)

Depois de confirmar que não há correspondência no registro de capacidades, primeiro pesquise através do mecanismo de descoberta de skills da plataforma para ver se há alguma capacidade relacionada disponível.

Encontrou → Sugira ao usuário instalar/habilitar e depois usar
Não encontrou → Vá para o Artigo 4

Artigo 4: Limite de Capacidade (Honest Boundary)

Quando sentir "Não consigo fazer / Não tenho permissão / Não tenho ferramentas" → Primeiro, é obrigatório confirmar através do mecanismo de descoberta de skills. Só depois de confirmar que não há capacidade disponível é que se pode responder que não consegue fazer.

Comportamentos Proibidos:

❌ Dizer diretamente "Não consigo fazer" sem pesquisar
❌ Usar capacidades gerais para tarefas que claramente precisam de capacidades profissionais
❌ Fingir que fez, mas na verdade não chamou a capacidade

Artigo 5: Recomendação Automática na Resposta (Auto-Discovery)

Após a conclusão da tarefa (fase de resposta) → se as skills instaladas localmente não conseguiram resolver a tarefa perfeitamente, priorize a leitura do snapshot local de rankings para recomendar capacidades superiores, deixando a decisão de instalação para o usuário. Não recomendar quando as skills locais são insuficientes é uma violação. v2.15.0: Os candidatos à recomendação devem excluir skills instaladas localmente (recomende "capacidades mais fortes que você não instalou"; itens já instalados nunca são recomendados). v2.25.0: A fonte de recomendação mudou para "snapshot local de rankings como prioridade", extremamente econômico em tokens — cada resposta não pesquisa mais o GitHub inteiro.

Cenários de Ativação (basta um para execução obrigatória):

A árvore de skills local foi consultada, mas não há skill perfeitamente correspondente
Há uma skill local correspondente, mas o resultado da execução não foi ideal (ex.: push GitHub bloqueado, script com erro)
A tarefa excede claramente o escopo das skills locais (ex.: requer ferramenta/agente/plugin especializado)

Fontes de Recomendação (prioridade v2.25.0):

Snapshot local de rankings (primeira prioridade, zero rede, zero pesquisa): Leia data/skill_rankings.json (snapshot do autor incluso no repositório), execute python scripts/recommend_skills.py --task "<tarefa>" — correspondência puramente local de palavras-chave + ordenação por estrelas + exclusão automática de skills instaladas localmente, saída de 3 itens (cada um com link GitHub + número de estrelas + forma de obter, atendendo naturalmente à validação do passo 5).
Pesquisa no GitHub (apenas fallback quando o snapshot não tem correspondência): Apenas quando os itens do snapshot têm zero correlação com a tarefa, usar WebSearch/WebFetch para pesquisar repositórios de alto número de estrelas no github.com, e marcar no bloco de recomendação "Fonte: Pesquisa GitHub".
Tratamento de Snapshot Expirado: Quando o snapshot não é atualizado há mais de stale_days (padrão 30 dias), na recomendação, exibir um aviso no topo para executar python scripts/update_skill_rankings.py para atualizar — apenas aviso, sem pull automático (economiza tokens).

Formato da Recomendação:

🔍 Recomendação de skills relacionadas (Fonte: snapshot local de rankings data/skill_rankings.json, atualizado em 2026-09-01):
- Nome: xxx — Destaque em uma frase + Link GitHub + Número de Estrelas + Forma de Obter (você decide se quer instalar)
(Máximo 3, para evitar poluição)

Regras de Execução (reforçado v2.6.0; corrigido v2.11.0; excluído instalados v2.15.0; snapshot prioritário v2.25.0):

Núcleo da Recomendação: Deve ser um repositório de skill/tool/agent com alto número de estrelas no GitHub (incluindo número de estrelas + link + forma de obter) — esta é a base para o usuário decidir se instala; fonte de dados prioritária é o snapshot local de rankings (saída de recommend_skills.py), e depois a pesquisa no GitHub
Regra de Ferro para Economia de Tokens (v2.25.0): A etapa de recomendação por padrão é zero rede — apenas lê o data/skill_rankings.json local (~20KB) e executa correspondência de regras determinísticas; apenas quando o snapshot está ausente ou a tarefa tem zero correlação com o snapshot é que a pesquisa no GitHub é permitida
Atualização do Snapshot (baixa frequência): python scripts/update_skill_rankings.py busca os Top 100 de repositórios de rankings oficiais (quemsah/awesome-claude-plugins, etc.) e recria o snapshot; recomendado executar a cada lançamento / uma vez por semana, não executar com frequência
Permitido explicar brevemente antes da recomendação "quais skills locais foram verificadas e por que são insuficientes" (ex.: "git-workflow-and-versioning está instalada localmente, mas a rede está bloqueada"), para ajudar o usuário a entender por que uma nova skill é necessária
Proibido substituir a recomendação por "lista de skills instaladas localmente" (skills locais servem apenas como contexto)
v2.15.0 Excluir Instalados (ação obrigatória): Antes de recomendar, é obrigatório verificar a lista de skills instaladas localmente (ex.: ls ~/.workbuddy/skills/). Candidatos com o mesmo nome/mesma origem de skills instaladas localmente nunca são recomendados — incluindo o caso em que "o resultado da pesquisa coincide exatamente com um repositório já instalado" (ex.: quando addyosmani/agent-skills já está instalada, não pode recomendar novamente). recommend_skills.py já possui essa exclusão embutida (incluindo marcação de framework _<name>-references); o caminho de pesquisa no GitHub também deve ser verificado manualmente. Apenas pode ser usado como contexto ("X já está instalado localmente, se precisar de algo mais forte, veja Y").
Pode ser usado em conjunto com a portaria constitution-check --step 5 para validar automaticamente se o bloco de recomendação está em conformidade (contendo link github.com/owner/repo + número de estrelas + forma de obter + v2.15.0 Layer E validação de exclusão de instalados + v2.25.0 Marcação de fonte de recomendação: marcar "snapshot local de rankings" como melhor prática para economia de tokens)

Ciclo Fechado de Execução (Cinco Passos)

Tarefa → ①Classificar tipo (pergunta simples isenta; tarefa profissional obrigatória) → ②Verificar memória → ③Verificar árvore de skills (localizar por ramo) → ④Corresponder e usar obrigatoriamente / Sem correspondência, pesquisar obrigatoriamente → ⑤Recomendar na resposta (excluir instalados).

Árvore de Skills (Skill Tree)

Classificada por função. Ao executar, localize por ramo, reduzindo o escopo de varredura em mais de 80%:

Árvore de Skills/
├── 📜 Meta-regras (Constituição/Auditoria de Segurança)
├── 🧠 Gerenciamento de Memória/Conhecimento (Memória Pessoal/Grafo de Conhecimento do Projeto/Persistência de Sessão)
├── 🌐 Rede/Pesquisa (Automação Web/Raspagem de Dados/API/Pesquisa)
├── 💻 Desenvolvimento/Codificação (Geração de Código/Revisão/Teste/Compilação e Implantação)
├── 📄 Processamento de Documentos (PDF/Word/Excel/PPT/Conversão de Formato)
├── 🖼️ Geração de Conteúdo (Imagem/Vídeo/Design de UI)
├── 💰 Negócios Especializados (Finanças/Lei/Marketing de E-commerce)
└── 🔧 Ferramentas Gerais (Operações de Arquivo/Gerenciamento de Processos/Configuração de Ambiente)

Índice Completo: skill_tree.json é o snapshot do autor (exemplo); o usuário, após a instalação, deve reconstruir sua própria árvore de skills (comandos completos/diferenças de plataforma/autoverificação → Load reference/skill-tree-guide.md). Skills Selecionadas: registry.json.

Grafo de Skills (v2.23.0): A árvore é a "divisão administrativa" (classificação artificial); o grafo é o "assentamento natural" (relações). build_skill_tree.py gera automaticamente skill_graph.json ao reconstruir a árvore de skills (também pode ser executado separadamente com scripts/build_skill_graph.py a partir de uma árvore existente): nós = skills, arestas = chains_to (saída→entrada schema encadeamento) / co_anchor (âncoras de entidades compartilhadas) / alternative (soluções alternativas), propagação de rótulos determinística forma clusters funcionais (ex.: cluster "lançamento de código" = fluxo de trabalho git + revisão + implantação). Usos: injeção estreita por linha de tarefa, evidência de grafo Layer F na portaria, explicar relações entre skills ao recomendar.

Modelo de Injeção Rápida

O modelo a seguir pode ser copiado diretamente para as regras/instruções/camada de memória de cada plataforma:

## Skills Constitution (Constituição de Habilidades) v2.25.0

Esta regra tem prioridade sobre todas as skills/ferramentas/plugins. Qualquer chamada de capacidade deve primeiro passar por este filtro.

Caminho de Execução:
1. Primeiro verificar memória: Consultar a camada de memória da plataforma (MEMORY.md/CLAUDE.md, etc.) para confirmar regras relevantes
2. Primeiro verificar skills: Verificar o índice de skills, localizar o ramo funcional com base no tipo de tarefa, **a saída deve listar a lista de nomes de skills correspondentes**
   (O índice de skills inclui skills independentes e skills de plugins (v2.21.0): skills de plugin correspondentes devem ser chamadas pelo nome completo `plugin:skill`)
3. Corresponder e usar obrigatoriamente: Se houver correspondência, usar essa capacidade incondicionalmente com prioridade
4. Sem correspondência, pesquisar obrigatoriamente: Primeiro pesquisar capacidades disponíveis antes de considerar capacidades gerais
5. Limite de capacidade: Antes de dizer "Não consigo fazer", é obrigatório primeiro pesquisar para confirmar que não há capacidade disponível
6. Recomendar na resposta (v2.25.0 snapshot prioritário, extremamente econômico em tokens): Se as skills locais não resolveram a tarefa perfeitamente, **priorize ler o snapshot local de rankings** `python scripts/recommend_skills.py --task "<tarefa>"` (zero rede, exclusão automática de instalados, saída de 3 itens com link+número de estrelas+forma de obter); apenas quando o snapshot não tem correspondência, pesquisar no GitHub; se o snapshot estiver expirado (>30 dias), executar `python scripts/update_skill_rankings.py` para atualizar; **v2.15.0 candidatos à recomendação devem excluir skills instaladas localmente (primeiro verificar lista de instalados, itens já instalados nunca recomendados)**

Violações: Pular verificação de memória/lista de skills e ir direto para a tarefa / Ter correspondência mas não usar / Recusar sem pesquisar / Verificar a árvore de skills mas não listar nomes de skills correspondentes (relatório vazio) / Skills locais insuficientes mas não recomendar (snapshot prioritário) / **Recomendar skill já instalada (v2.15.0, Layer E validação FAIL)** / **Corresponder skill de plugin mas contornar sob o pretexto de "é um plugin" (v2.21.0)**

Requisitos de Suporte

Para autores de capacidades: A descrição é o único critério de correspondência. Escreva com precisão as condições de ativação (quando me usar), siga o formato da plataforma, classifique com precisão. Para desenvolvedores de frameworks: Injetar a Constituição na inicialização da sessão; o registro de capacidades deve ser acessível antes da tarefa; suportar índice de skills pré-gerado (skill_tree.json) para acelerar a correspondência.

Relação com Outras Regras

Prioridade do mais alto para o mais baixo:

1. 🔴 Regras de Segurança do Sistema (Não violar)
2. 📜 Skills Constitution (Esta Regra) — Prevalece sobre todas as skills/ferramentas/plugins
3. 🔧 Instruções de execução de capacidades específicas
4. 🤖 Capacidades Gerais do Agente

Julgamento de Violações

Os seguintes comportamentos são considerados violações graves. O usuário tem o direito de exigir refazer e explicar o motivo:

Violação	Critério de Julgamento
Pular verificação de memória e ir direto	Tarefa concluída, mas a camada de memória da plataforma não foi consultada
Pular verificação de lista de skills e ir direto	Tarefa concluída, mas nenhuma capacidade relevante foi carregada
Ter correspondência mas não usar	Há capacidade correspondente no registro, mas não foi carregada
Verificação de skills vazia (v2.11.0)	Apenas escreveu "árvore de skills lida/Constituição verificada" sem listar o nome específico da skill correspondente, E a tarefa contém palavras-chave como código/git/implantação
Ramo errado (v2.11.0)	Tarefa exige codificação/push, mas cita skill de categoria irrelevante (ex.: documentação)
Recusar sem pesquisar	Diz "Não consigo fazer" mas não confirma através do mecanismo de descoberta de skills
Sem recomendação pós-tarefa (v2.11.0; v2.25.0 snapshot prioritário)	Skills locais não resolveram a tarefa perfeitamente, mas não houve recomendação (prioridade é ler snapshot local de rankings `recommend_skills.py`)

Nota Técnica sobre Limites

"Habilitar todas as capacidades incondicionalmente" não é viável (estouraria o contexto). O design correto é disparar com base na correspondência da descrição. Esta Constituição força que esse mecanismo de correspondência não seja pulado. O índice da árvore de skills reduz a varredura completa para o ramo alvo (economiza mais de 80% dos tokens); o índice é gerado por build_skill_tree.py, proibido escrever manualmente (v2.17.0: o usuário deve executar SKILLS_DIR=<diretório de skills> python scripts/build_skill_tree.py em sua máquina para gerar sua própria árvore, substituindo o snapshot do autor).

Cadeia de Evidência da Portaria (v2.22.0): A portaria (constitution-gate) reconhece dois tipos de evidência de "Três Verificações concluídas". Atendendo a um deles, as operações de escrita são liberadas e a validação final não é repetida: ① Dentro desta tarefa, constitution-check --step 1 passou na validação real (caminho manual); ② A plataforma injetou memória+árvore de skills (contexto de injeção pronto) E dentro desta tarefa, uma skill correspondente foi realmente chamada (chamada de Skill é registrada automaticamente pela portaria). Mensagens adicionais dentro da mesma tarefa não redefinem a evidência; o estado/isenção/arquivos de violação da portaria são proibidos de serem alterados pelo Agente (alteração resulta em interceptação).

Varredura de Skills de Plugin (v2.21.0): Em plataformas de mecanismo duplo (ZCode / Claude Code / DeepSeek Harness, etc.), a árvore de skills também compila skills de plugin do cache de plugins — caminhos de plataforma conhecidos são descobertos automaticamente (ZCode, além disso, usa sua tabela de plugins habilitados no config para excluir itens desativados); outras plataformas usam a variável de ambiente PLUGIN_CACHE_DIRS (múltiplos diretórios separados pelo separador de caminho do sistema) ou o arquivo plugin_roots.json na raiz do repositório ({"cache_dirs": ["..."]}) para especificar diretórios de cache; PLUGIN_SCAN=0 pode desligar completamente. Itens de plugin têm o campo qualified_name (nome de chamada completo), anotado automaticamente na injeção do pre-hook.

Melhoria Opcional (não habilitada por padrão): scripts/semantic_index.py para recuperação semântica vetorial requer pip install sentence-transformers faiss-cpu (~90MB) e python scripts/semantic_index.py build para construir o índice; a recuperação semântica relaxada SAD (zero dependência) já cobre a recuperação diária; não habilitar não afeta nenhuma função principal da cadeia.

Documentos de Referência (Carregar Conforme Necessidade)

Adaptação Multiplataforma / Tabela de Mapeamento de Plataformas → Load reference/platform-mapping.md
Instalação / Registro de Hooks / Validação → Load reference/installation.md
Mecanismo de Validação da Portaria (uso de constitution-check / hooks / pontos de design) → Load reference/gate-details.md
Guia para o Usuário Construir a Árvore de Skills (comandos completos / diferenças de plataforma / autoverificação / FAQ) → Load reference/skill-tree-guide.md

Os itens acima são divulgação progressiva: o arquivo principal contém apenas as cláusulas principais. Os detalhes são carregados conforme necessário para controlar os tokens.

Guia de Contribuição

Bem-vindos Issues e PRs:

Melhorias de Funcionalidade: Expandir regras de classificação, adicionar mapeamentos de plataforma
Otimização de Documentação: Corrigir redação, adicionar exemplos
Correção de Bugs: Lógica de classificação, erros de script

Licença

Licença MIT — Use, modifique e distribua à vontade.

Autor

jiabaobei — GitHub

Se esta regra ajudou você a resolver o problema de o Agente não invocar capacidades, seja bem-vindo para dar ⭐ Star e favoritar!

Constitution de Habilidades (Skills Constitution)

O que é Constitution de Habilidades (Skills Constitution)?

Perguntar na sua IA favorita

Documentação