CaseYwY/skills

manage-project-skills — seleção e auditoria de habilidades do projeto

0. Hierarquia de regras (leia primeiro)

1. Autorização (mais alta, sem exceções): sem instalação/atualização/remoção, sem gravações em arquivos do projeto sem aprovação explícita do usuário; exceção: gravações aprovadas no ledger. aprovação = skill específica + fonte + escopo; "gerenciar minhas skills" não autoriza nada individualmente.
2. Processo: siga o modo selecionado (T0/T1/T2/auditoria); etapas "proibidas" nunca são puladas por eficiência.
3. Diretriz: local-first, contenção — desvios permitidos com justificativa explícita.

Principal: falta é melhor que instalação errada — reverter ≈ 1 minuto; instalação errada = contexto permanente + competição de gatilhos. contenção, justificativa obrigatória, local-first.

1. Modos

Requisitos incertos ⇒ necessidades completas não podem ser conhecidas ⇒ sem instalação em massa no início.

• T0 · inventário inicial (SOMENTE LEITURA): etapas 1-2 + relatório no chat ("coberto / não instalando"). zero instalações/gravações; inicialização do ledger = gravação aprovada separada. matriz de cobertura = necessidades inferíveis apenas pela pilha. caminho rápido: ledger existe && sem discussão de skills ⇒ leia apenas o ledger. reinventário se: diretórios de skills / AGENTS.md / lockfile / agente mudou ∨ ledger ≠ disco ∨ usuário solicitar.
• T1 · sob demanda (durante a tarefa): classifique primeiro. resposta pontual (detalhe de API, comando único) ⇒ consulte, não instale. reutilizável (fluxos de trabalho/padrões/cadeias de ferramentas que este repositório usará novamente) ⇒ instale uma skill ⇒ registre. a entrada depende das regras do AGENTS.md (veja MAINTENANCE.md), não da autoavaliação do modelo.
• T2 · plano definido: instalação em lote, cada candidato justificado pelo plano confirmado. etapas completas 1-7.
• Auditoria: usuário solicita revisão/limpeza/limpeza ⇒ veja o final.

Todos os modos compartilham o ledger do projeto .agents/skills-rationale.md (se aprovado); leia-o primeiro.

2. Fluxo

1. Perfil do projeto

Leia se presente (não adivinhe): manifestos (package.json / pyproject.toml / go.mod / Cargo.toml / *.csproj); layout + sinais de monorepo (workspaces, turbo.json); infraestrutura (.github/workflows, Dockerfile, vercel.json, wrangler.toml); cabeçalho do README, docs/agents/.

2. Inventário de cobertura (local-first; deduplicar antes de puxar)

Ordem: instalado no projeto → global → registro. Duas classes:

• habilidades pessoais: globais, entre projetos. não duplique no projeto; registre o agente alvo. presença global ≠ dependência declarada do projeto.
• críticas para o projeto: fluxo de trabalho/entrega depende delas. registre fonte + versão/commit + caminho de restauração — mesmo se instaladas globalmente; novas máquinas não herdam globais.

Varredura: diretórios do projeto (.agents/skills, .opencode/skills, .claude/skills = exemplos comuns, confirme por documentação do agente; inacessível ⇒ "não verificado", nunca "sem skills"); global via npx skills ls -g; manifesto fonte e skills-lock.json (sincronize se presente). Saída: matriz de cobertura (necessidade → satisfeita por / lacuna).

3. Preencher lacunas de fontes confiáveis

Níveis de confiança: oficial do fornecedor (anthropics/skills, openai/skills, supabase/agent-skills) > autor original (mattpocock/skills, cursor/plugins) > comunidade > não verificável (exija escrutínio). senão npx skills find <kw> — contagem de instalações = referência, não confiança. nada adequado ⇒ informe + proponha skill-creator; sem gambiarras de aproximação.

4. Orçamento: sem limite rígido, baseado em necessidade

• cada candidato precisa de um motivo concreto ("projeto tem X ⇒ Y"); sem motivo ⇒ descarte.

• ~10 candidatos = bug na análise ⇒ reaudite etapas 1-2.

• marginal ⇒ lista "adiado" (reverter é barato).
• dedup ≠ remoção automática: sobreposição de descrições ⇒ grupo de candidatos ⇒ compare gatilhos/E/S/efeitos colaterais/deps/versões ⇒ mescle/remova somente com evidência de substituição + aprovação do usuário; senão mantenha ambos, marque como para-comparar.

5. Portão de segurança: antes de instalar, aprovação do usuário

Revise o pacote inteiro, não apenas SKILL.md:

1. leia SKILL.md completamente + todos os arquivos/scripts/config/deps referenciados; por script verifique: execução / rede / gravações / credenciais.
2. registre evidência de varredura: scanner + veredito + versão correspondente + data. sem varredura = desconhecido, não seguro. discordância entre scanners ⇒ liste, não faça média.
3. fonte privada sem varreduras ⇒ revisão manual completa do arquivo substitui o portão, marcado "não varrido".
4. risco médio+ ou comportamento inexplicado ⇒ usuário decide; nada instala enquanto não estiver claro.

6. Instalar

# detecta o agente automaticamente (informe a detecção ao usuário); máquinas multi-agente: passe --agent
npx skills add <owner/repo>@<skill> --copy -y

• canal 2 — versão fixa / fallback para npm inacessível: gh skill install <owner/repo> <skill[@version]> --agent opencode (pré-visualização; copia arquivos, sem atualização do skills-lock ⇒ ledger registra fonte+versão; sempre passe --agent — o padrão não interativo é github-copilot). um canal por skill — não misture.
• --copy = isolamento de snapshot, NÃO fixação de versão: sem sincronização upstream, sem identidade de versão, reinstalar o altera. reprodutibilidade ⇒ ledger registra: fonte + caminho + versão/commit (+hash).
• skills de fluxo de trabalho críticas para o projeto: --copy, nunca link simbólico (link simbólico rastreia upstream).
• skills-lock.json produzido ⇒ faça commit (restaurar: npx skills experimental_install); garanta que .agents/ não esteja no .gitignore.
• eficácia varia: OpenCode recarrega a quente (verificado); outros agentes podem exigir reinicialização ⇒ peça ao usuário para reiniciar + reverificar.
• GitHub inacessível ⇒ informe + proponha cache local; nunca pule silenciosamente.

7. Verificar e registrar (quatro camadas; camada ausente = "não verificado")

• arquivo: existe, caminho correto, referências completas
• manifesto: npx skills ls corresponde ao lockfile e ao disco (visível ≠ carregável)
• carga: o agente alvo realmente carrega a skill
• comportamento: uma tarefa positiva representativa funciona
• escreva decisões (o quê/porquê/adiado/verificado até) → .agents/skills-rationale.md
• remover: prefira npx skills remove <nome> -y (parâmetros conforme npx skills --help); nunca apenas apague o diretório (dessincronização do lockfile); registre fonte+versão antes de deletar; faça backup se não for recuperável; verifique novamente as quatro camadas depois.

3. Modo de auditoria

Inclui esta skill. relatório → aprovação do usuário → executar. verificações:

1. duplicatas: agrupe descrições ⇒ grupos de candidatos ⇒ compare gatilhos/E/S/efeitos colaterais/deps/versões; evidência de substituição + aprovação ⇒ mescle/remova; senão mantenha ambos (para-comparar). nunca delete por similaridade.
2. conflitos: contradições no mesmo cenário ⇒ registre citações + escopo ⇒ usuário julga.
3. inchaço: sem telemetria de uso — "nunca acionado" = fonte do usuário. mensurável: inchaço da descrição vs. função, sobreposição com skills de maior frequência. rebaixar ⇒ caminho de restauração de estado.
4. referências mortas: entrada necessária (ausente = bloqueante) / dependência opcional (ausente = pule) / saída esperada (criada em tempo de execução; ausência ≠ erro). referência morta ⇔ entrada necessária ausente + sem recuperação. relatório: evidência → recomendação → impacto → autorização. antes de deletar: confirme recuperabilidade (npx skills find); não recuperável ⇒ faça backup + pergunte. descobertas → ledger.

4. Manutenção e aplicação

Modelos de regras AGENTS.md, loop de diagnóstico de falha de gatilho, conjunto de teste de 15 cenários, fluxo de liberação → MAINTENANCE.md — execute antes/depois de editar esta skill.