agent-engineering-skills 1.0.0 → 1.0.1

package/README.md

@@ -1,13 +1,168 @@
+<p align="center">
+  <img src="https://img.shields.io/npm/v/agent-engineering-skills?style=flat-square" alt="npm version" />
+  <img src="https://img.shields.io/npm/dm/agent-engineering-skills?style=flat-square" alt="npm downloads" />
+  <img src="https://img.shields.io/badge/dependencies-0-brightgreen?style=flat-square" alt="zero dependencies" />
+  <img src="https://img.shields.io/github/license/1arley/1arley-agent-skills?style=flat-square" alt="MIT license" />
+</p>
+
 # Agent Engineering Skills
 
 > **Don't just review the code. Attack the assumptions behind the system.**
 
-Um repositório de skills modulares que ensinam agentes de IA a **entender → pesquisar
-→ questionar → testar → verificar → implementar → revisar**.
+Um repositório de skills modulares que ensinam agentes de IA a **entender → pesquisar → questionar → testar → verificar → implementar → revisar**.
+
+O objetivo não é criar um agente que sabe mais. É criar um agente que **sabe como descobrir mais, onde procurar, quais perguntas fazer e como verificar se está certo**.
+
+- 🛠️ **24 skills** prontas para instalar no Claude Code (auditoria, segurança, reliability, produto, frontend, pesquisa)
+- 🧠 Skills ensinam **como pensar** — modelo mental, perguntas, padrões de ataque, evidência — não listas de comandos
+- 📚 Referências centralizadas em `references/*.yaml` ensinam **onde olhar**, com nível de autoridade
+- 🧭 Dois routers (`skill-router`, `research-router`) que despacham a tarefa para as skills e fontes certas
+- ✅ Validador embutido que garante que o repositório nunca vire uma pasta de prompts desconexos
+- 📦 Zero dependências, instalável com um comando `npx`
+
+---
+
+## Índice
+
+- [Instalação](#instalação)
+- [Como usar](#como-usar)
+- [O que isto é](#o-que-isto-é)
+- [Estrutura](#estrutura)
+- [As 24 skills](#as-24-skills)
+- [Workflow completo](#workflow-completo)
+- [Validação](#validação)
+- [Documentação](#documentação)
+- [Licença](#licença)
+
+---
+
+## Instalação
+
+### Opção 1 — npx (recomendado)
+
+```bash
+# Instala as 24 skills no diretório padrão (~/.claude/skills/)
+npx agent-engineering-skills install
+```
+
+O que acontece:
+1. Detecta `~/.claude/skills/` (ou o `--target` que você informar)
+2. Cria uma pasta por skill, com `SKILL.md` no formato nativo do Claude Code (`user_invocable`)
+3. Não sobrescreve skills existentes (a menos que use `--force`)
+
+**Opções:**
+
+| Opção | Descrição |
+|---|---|
+| `--target <dir>` | Diretório de destino (default: `~/.claude/skills/`) |
+| `--link` | Cria symlinks para o repositório (útil em desenvolvimento) |
+| `--force` | Sobrescreve skills existentes com o mesmo nome |
+
+**Exemplos:**
+
+```bash
+# Instalar em um diretório custom
+npx agent-engineering-skills install --target ~/meus-skills
+
+# Instalar como symlinks (edita skills e o efeito é imediato no Claude Code)
+npx agent-engineering-skills install --link
+
+# Reinstalar tudo
+npx agent-engineering-skills install --force
+```
+
+**Outros comandos:**
 
-O objetivo não é criar um agente que sabe mais.
-É criar um agente que **sabe como descobrir mais, onde procurar, quais perguntas fazer
-e como verificar se está certo**.
+```bash
+npx agent-engineering-skills validate   # roda o validador
+npx agent-engineering-skills --help     # ajuda completa
+npx agent-engineering-skills --version  # versão instalada
+```
+
+### Opção 2 — clonando o repositório
+
+```bash
+git clone https://github.com/1arley/1arley-agent-skills.git
+cd 1arley-agent-skills
+python3 scripts/validate.py   # verifica que tudo está íntegro
+```
+
+As skills ficam em `skills/<categoria>/<nome>/SKILL.md` e você pode copiá-las ou
+referenciá-las manualmente no seu harness de agente.
+
+---
+
+## Como usar
+
+### Passo 1 — Leia as regras globais
+
+`AGENTS.md` define o comportamento base do agente: investigar antes de concluir,
+pensar em invariantes, testar repetição/reversão/concorrência, não confiar no frontend,
+classificar evidência (`CONFIRMED` → `SPECULATIVE`), e pesquisar antes de reinventar.
+
+### Passo 2 — Comece pelo router
+
+Para qualquer tarefa não-trivial, comece pelo **`skill-router`** — ele analisa a
+tarefa e seleciona quais skills ativar:
+
+```text
+"Adicionar reações que dão XP"
+        ↓
+gamification-audit → business-logic-audit → idempotency-audit
+→ race-condition-hunter → api-abuse-audit → user-flow-audit
+```
+
+```text
+"Melhorar a tela de criação de personagem"
+        ↓
+ux-review → visual-quality-review → interaction-design
+→ accessibility-review → reference-research → market-research
+```
+
+### Passo 3 — Leia o SKILL.md da skill selecionada
+
+Cada skill segue o mesmo formato de 9 seções:
+
+| Seção | O que contém |
+|---|---|
+| **Objective** | O que a skill ensina o agente a fazer |
+| **When to Use** | Quando ativá-la (e com quais outras skills compõe) |
+| **Mental Model** | A lente de raciocínio — como enxergar o sistema |
+| **Investigation Procedure** | A ordem da investigação |
+| **Questions to Ask** | Perguntas concretas que expõem defeitos |
+| **Attack Patterns** | Sequências de operações que atacam suposições |
+| **Evidence Requirements** | O que conta como confirmação |
+| **False Positives** | Quando o comportamento estranho é aceitável |
+| **Output Format** | Como reportar findings |
+
+### Passo 4 — Pesquise antes de reinventar
+
+Para tarefas não-triviais, o **`research-router`** decide onde pesquisar:
+
+```text
+Animation problem    → Animate UI, Impeccable, Interfaces, GitHub, real products
+UX problem           → Laws of UX, Interfaces, real products, design systems
+Architecture problem → GitHub, official docs, production implementations, technical literature
+Security problem     → OWASP, PortSwigger, CWE, GitHub
+```
+
+Toda pesquisa é sintetizada (Reference → Relevant Pattern → Why It Matters → Adaptation
+→ Trade-offs → Recommendation) — **nunca** apenas uma lista de links.
+
+### Passo 5 — Reporte com evidência
+
+Use `templates/audit-report.md` (ou os outros templates) e classifique cada finding:
+
+```text
+CONFIRMED         — reproduzido com evidência direta
+HIGH CONFIDENCE   — forte indício técnico, sem reprodução
+POSSIBLE          — plausível, exige investigação
+SPECULATIVE       — hipótese sem evidência → risco a verificar, não bug
+```
+
+**Quer ver um exemplo concreto?** Leia um dos 4 exemplos em `examples/` de ponta a
+ponta — cada um é uma auditoria completa (farming de XP, race condition, bypass de
+autorização, revisão de frontend) que demonstra o fluxo inteiro.
 
 ---
 
@@ -25,12 +180,15 @@ As skills ensinam raciocínio. As referências ensinam onde olhar. Nenhuma skill
 de conhecimento implícito que não esteja documentado ou disponível através das
 referências.
 
+---
+
 ## Estrutura
 
 ```text
 ├── AGENTS.md              # regras globais do agente
 ├── plan.md                # especificação completa (fases, formato, definição de pronto)
 ├── LICENSE                # MIT
+├── package.json           # npm (npx agent-engineering-skills install)
 │
 ├── skills/
 │   ├── audit/             # auditoria de sistemas e descoberta de bugs
@@ -41,40 +199,82 @@ referências.
 │   ├── research/          # descoberta de referências e implementações
 │   └── meta/              # routers que despacham para skills e fontes
 │
-├── references/            # catálogo YAML de fontes externas
-├── knowledge/             # material "o que considerar"
+├── references/            # catálogo YAML de fontes externas (6 catálogos)
+├── knowledge/             # material "o que considerar" (estrutura pronta)
 ├── templates/             # templates de relatório (audit, bug, design, research)
-├── examples/              # exemplos concretos de auditorias
+├── examples/              # exemplos concretos de auditorias completas
 ├── docs/                  # filosofia, authoring, integração
+├── bin/                   # CLI (node, zero deps)
 └── scripts/               # validação (lint de skills e referências)
 ```
 
-Cada skill é `skills/<categoria>/<nome>/SKILL.md` com frontmatter YAML e nove seções
-fixas. Ver `docs/skill-authoring.md`.
+---
+
+## As 24 skills
 
-## Skills (primeira versão — 24)
+### Core audit
 
-| Categoria | Skills |
+| Skill | Descrição |
 |---|---|
-| **Core audit** | `adversarial-review`, `user-flow-audit`, `business-logic-audit`, `edge-case-hunter`, `state-consistency-audit`, `error-flow-audit` |
-| **Security** | `authorization-audit`, `api-abuse-audit`, `input-trust-audit` |
-| **Reliability** | `race-condition-hunter`, `idempotency-audit`, `data-integrity-audit` |
-| **Product** | `gamification-audit` |
-| **Frontend** | `ux-review`, `visual-quality-review`, `interaction-design`, `animation-review`, `accessibility-review` |
-| **Research** | `reference-research`, `github-reference-research`, `market-research`, `implementation-research` |
-| **Meta** | `skill-router`, `research-router` |
+| `adversarial-review` | Ataca o sistema como usuário curioso, malicioso, power user, descuidado, concorrente e com estado antigo; opera repeat, reverse, reorder, skip, replay, concurrent, manipulate |
+| `user-flow-audit` | Mapeia entry → preconditions → action → state change → feedback → next state; acha dead ends, estados impossíveis, passos puláveis, refresh/back-button problems, operações duplicadas |
+| `business-logic-audit` | Identifica regras, invariants, limites, ownership, transições e rewards; para cada regra: where enforced? bypassable? repeatable? reversible? raced? |
+| `edge-case-hunter` | Gera casos de fronteira: null, empty, zero, negative, huge, duplicates, Unicode, stale, deleted, expired, repeated actions |
+| `state-consistency-audit` | Compara estado entre database, API, server state, cache, client state e URL state; procura divergências |
+| `error-flow-audit` | Investiga partial success, timeouts, lost responses, retries, crashes, rollback failures — estados deixados inconsistentes |
 
-A prioridade é **qualidade, composição e capacidade de raciocínio — não quantidade**.
+### Security
 
-## Como usar
+| Skill | Descrição |
+|---|---|
+| `authorization-audit` | Separa authenticated de authorized; verifica ownership, moderator, admin, participant — no servidor, sempre |
+| `api-abuse-audit` | Trata a API como diretamente acessível: repetição, replay, manipulação de IDs, campos extras, endpoints alternativos, rate limiting, bypass de UI |
+| `input-trust-audit` | Identifica valores que nunca devem ser confiados ao cliente: userId, role, price, XP, permissions, ownership, status, reward, timestamps |
+
+### Reliability
 
-1. Leia `AGENTS.md` para as regras globais.
-2. Para uma tarefa, comece pelo `skills/meta/skill-router/` — ele seleciona quais
-   skills ativar com base no tipo de tarefa.
-3. Para pesquisa, use `skills/meta/research-router/` — ele aponta quais fontes em
-   `references/` consultar.
-4. Ao reportar findings, siga `templates/audit-report.md` e classifique cada um por
-   nível de evidência (`CONFIRMED` / `HIGH CONFIDENCE` / `POSSIBLE` / `SPECULATIVE`).
+| Skill | Descrição |
+|---|---|
+| `race-condition-hunter` | Procura READ → DECISION → WRITE e pergunta: o que acontece se outro request modificar o estado entre as operações? |
+| `idempotency-audit` | Testa request ×N e response-lost + retry; especialmente em pagamentos, rewards, criação, webhooks, notificações, contadores |
+| `data-integrity-audit` | Verifica unique constraints, foreign keys, transactions, cascading, soft delete, enums — o banco deve impedir estados impossíveis |
+
+### Product
+
+| Skill | Descrição |
+|---|---|
+| `gamification-audit` | Detecta abuso de XP, pontos, moedas, reputação, achievements, streaks, likes, reactions, referrals; modelo TRIGGER → CONDITION → REWARD → REVERSAL |
+
+### Frontend
+
+| Skill | Descrição |
+|---|---|
+| `ux-review` | Avalia clareza, hierarquia, carga cognitiva, feedback, affordances, consistência, navegação, estados vazios, erros, loading |
+| `visual-quality-review` | Avalia tipografia, spacing, hierarchy, density, contrast, composition, consistency, visual noise — e detecta **AI slop** |
+| `interaction-design` | Avalia hover, focus, pressed, disabled, loading, transitions, feedback, micro-interactions |
+| `animation-review` | Avalia propósito, timing, easing, hierarchy, continuity, interruption, accessibility, reduced motion |
+| `accessibility-review` | Avalia keyboard, screen readers, focus, semantic HTML, contrast, touch targets, reduced motion, forms, errors (WCAG) |
+
+### Research
+
+| Skill | Descrição |
+|---|---|
+| `reference-research` | Descobre quais fontes externas do catálogo são relevantes e sintetiza em padrões acionáveis |
+| `github-reference-research` | Pesquisa implementações reais no GitHub (implementation, architecture, database, API, framework) e avalia atividade, qualidade, testes, docs, adoção, licença |
+| `market-research` | Pesquisa produtos reais em escala — "como produtos que resolveram esse problema em escala fazem isso?" |
+| `implementation-research` | Resolve problemas técnicos específicos priorizando: official docs → GitHub → maintainer discussions → production code → articles |
+
+### Meta (routers)
+
+| Skill | Descrição |
+|---|---|
+| `skill-router` | Analisa a tarefa e seleciona quais skills ativar (com tabelas de composição) |
+| `research-router` | Decide onde pesquisar com base no tipo de problema (animation, UX, architecture, security, implementation...) |
+
+> A prioridade é **qualidade, composição e capacidade de raciocínio — não quantidade**.
+> Cada skill segue o mesmo formato padrão de 9 seções — ver `docs/skill-authoring.md`.
+
+---
 
 ## Workflow completo
 
@@ -86,19 +286,33 @@ RESEARCH → ANALYZE → IMPLEMENT → ADVERSARIAL TEST → VERIFY → REPORT
 Pesquisa é proporcional à complexidade: um botão simples não precisa de pesquisa;
 uma arquitetura nova provavelmente precisa; concorrência em pagamentos certamente.
 
-## Status
+---
+
+## Validação
 
-**Primeira versão completa.** 24 skills implementadas, 6 catálogos de referências,
-4 templates de relatório, 4 exemplos concretos, 2 meta routers, validador.
+O repositório inclui um validador que garante que as skills seguem o formato padrão,
+que as referências seguem o schema, e que o router referencia skills que existem:
 
 ```bash
+# Pelo npx
+npx agent-engineering-skills validate
+
+# Ou direto no repositório
 python3 scripts/validate.py
 ```
 
-Verifica que toda `skills/**/SKILL.md` tem o frontmatter e as nove seções exigidas,
-que toda `references/*.yaml` segue o schema de catálogo, e que as referências do
-`skill-router` são consistentes. Ver `docs/skill-authoring.md` e
-`docs/reference-authoring.md`.
+**Saída esperada (íntegra):**
+
+```
+Skills found:      24
+Reference catalogs: 6
+Errors:             0
+Warnings:           0
+
+✓ All contracts satisfied.
+```
+
+---
 
 ## Documentação
 
@@ -108,6 +322,14 @@ que toda `references/*.yaml` segue o schema de catálogo, e que as referências
 * `docs/agent-integration.md` — como o agente integra skills, routers e workflows.
 * `plan.md` — especificação completa e Definition of Done.
 
+---
+
 ## Licença
 
 MIT — ver `LICENSE`.
+
+---
+
+<p align="center">
+  <sub>Feito com o propósito de ensinar agentes a descobrir mais, procurar melhor, fazer as perguntas certas e verificar se estão certos.</sub>
+</p>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-engineering-skills",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Modular skills that teach AI agents to audit systems, find bugs, review UX/frontend, and research before reinventing. npx agent-engineering-skills install",
   "license": "MIT",
   "type": "module",