Skills

Manual oficial de skills e ferramentas de IA da AEX. Catálogo completo, instalação (máquina + 1º clone), kits por área e regras de segurança.

Documentação oficial externa: skills.sh, Spec Kit, guia find-skills (Notion @franklim.gui). Aqui está como usamos na AEX.

O que são skills na AEX

Skills não substituem standards/. Em conflito, prevalece o standard.

Política commit vs global

• Kit de máquina (find-skills + caveman + Spec Kit): user-level / CLI — não viaja no Git do produto.
• Skills AEX + kits curados da área: viajam no Git do projeto (clone e já começa).
• Atualização das cópias commitadas: npx skills update -y no projeto + PR de sync.
• Fora do catálogo curado: use find-skills sob demanda; não instale em massa.

Kit obrigatório

Máquina (uma vez — onboarding / 1º clone)

Projeto (viajam no Git)

Comandos (máquina)

Windows PowerShell — use sempre -y / --yes para não travar prompts:

# find-skills (Cursor + Claude Code)
npx -y skills add https://github.com/vercel-labs/skills --skill find-skills -g -a cursor -a claude-code -y

# caveman — respostas mais curtas / menos tokens (Cursor + Claude Code)
npx -y skills add JuliusBrussee/caveman@caveman -g -a cursor -a claude-code -y

# Spec Kit — pin oficial atual da AEX
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@v0.12.14

Verificar

npx skills list -g
specify --version
specify self check

Esperado: find-skills e caveman na lista global; specify 0.12.14 (ou a tag pinada neste manual).

Catálogo completo

Versionar no repo apenas o kit curado (tabelas abaixo). Demais skills: find-skills sob demanda — não instalar em massa fora deste catálogo.

Kits por área (ClickUp)

Organizados pelas cinco listas técnicas: Back-end, Front-end, Auto, Infra (+ Docs). Todo projeto leva o kit transversal + skills AEX; o kit da área segue a stack do squad.

Legenda da coluna Status: Obrigatória (commit), Condicional (commit só se a stack usar), Experimental (global/-g — não versionar).

Transversal (todos os repos de produto)

Back-end

Front-end

Automações (lista Auto — n8n + Python)

Infra / DevOps

Comandos de instalação (project-local — commitável)

Rodar no repositório do produto, sem -g. Depois: revisar Snyk + SKILL.md → git add .cursor/skills/ → PR.

# Transversal (todos)
npx -y skills add mattpocock/skills@tdd obra/superpowers@systematic-debugging mattpocock/skills@code-review mattpocock/skills@git-guardrails-claude-code anthropics/skills@webapp-testing -a cursor -a claude-code -y

# Back-end
npx -y skills add supabase/agent-skills@supabase-postgres-best-practices supabase/agent-skills@supabase wshobson/agents@nodejs-backend-patterns wshobson/agents@api-design-principles wshobson/agents@typescript-advanced-types redis/agent-skills@redis-development -a cursor -a claude-code -y
# NestJS (condicional):
# npx -y skills add kadajett/agent-nestjs-skills@nestjs-best-practices -a cursor -a claude-code -y

# Front-end
npx -y skills add vercel-labs/agent-skills@vercel-react-best-practices wshobson/agents@nextjs-app-router-patterns anthropics/skills@frontend-design wshobson/agents@tailwind-design-system -a cursor -a claude-code -y

# Automações (sem experimentais)
npx -y skills add czlonkowski/n8n-skills@n8n-workflow-patterns czlonkowski/n8n-skills@n8n-mcp-tools-expert czlonkowski/n8n-skills@n8n-node-configuration wshobson/agents@python-testing-patterns wshobson/agents@python-performance-optimization wshobson/agents@prompt-engineering-patterns pydantic/skills@building-pydantic-ai-agents -a cursor -a claude-code -y
# RAG (condicional):
# npx -y skills add langchain-ai/langchain-skills@langchain-rag -a cursor -a claude-code -y

# Infra/DevOps
npx -y skills add github/awesome-copilot@multi-stage-dockerfile github/awesome-copilot@git-commit addyosmani/agent-skills@ci-cd-and-automation -a cursor -a claude-code -y

Experimentais (global — não versionar no repo)

# Só se necessário e com confirmação humana — NÃO commitar
npx -y skills add agno-agi/agno-skills@agno -g -a cursor -a claude-code -y

Coolify: preferir o MCP Coolify. Skills de comunidade (ex.: ajmcclary/coolify-manager, oakoss/agent-skills@coolify) ficam experimentais — não versionar.

Primeiro clone (checklist)

Depois de clonar o repositório do projeto:

1. Abra este manual (canônico em aex-engineering): tools/skills.md.
2. Instale o kit de máquina (find-skills + caveman + specify) com os comandos acima.
3. Confirme skills AEX: .cursor/skills/engenharia-doc-aex/ e .cursor/skills/gestao-clickup-aex/ (e AGENTS.md na raiz).
4. Confirme o kit transversal e o kit da sua área/squad em .cursor/skills/ (tabelas acima). Se faltarem no repo novo, o Tech Lead versiona via PR com os comandos project-local.
5. Se faltarem skills AEX: copie as pastas de aex-engineering/.cursor/skills/ para o projeto (e o AGENTS.md se útil).
6. Smoke: no chat, peça “procure uma skill para …” (ativa find-skills).
7. Em projeto novo ou ainda sem Spec Kit: specify init . --integration cursor (ou a integração do agente que você usa) — ver SDD_STANDARD.

Pré-requisito ClickUp: MCP autenticado (https://mcp.clickup.com/mcp).

find-skills

Meta-skill: o agente busca no registry skills.sh via CLI npx skills.

• Não se invoca como /find-skills em todos os agentes. Peça: “procure skills para X”, “tem skill de code review?”.
• Guia detalhado: Como usar find-skills — @franklim.gui.

Sob demanda (exemplos aprovados)

npx -y skills find "grill"
# Depois de escolher, com confirmação humana:
# Kit curado do projeto → sem -g + PR
# Experimental / pessoal → -g
npx -y skills add <owner/repo@skill> -g -y

Spec Kit

CLI oficial do SDD AEX. Processo normativo: SDD_STANDARD.

# Upgrade para outra release pinada (atualizar também este manual)
uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git@vX.Y.Z
specify self check

Init em projeto (exemplo Cursor):

specify init . --integration cursor

Gestão continua no ClickUp. Os 11 documentos em docs/ / raiz permanecem. Spec Kit não substitui PRD/ARCHITECTURE.

Skills AEX no repositório

Cada uma tem SKILL.md + reference/ + templates/. Fonte normativa: standards/.

Copiar para outro repo:

aex-engineering/.cursor/skills/<nome-da-skill>/  →  <projeto>/.cursor/skills/<nome-da-skill>/

Opcional: copie também AGENTS.md.

Segurança (antes de instalar qualquer skill)

1. Fonte oficial (org/autor conhecido) + licença MIT (ou equivalente clara).
2. Método AEX: npx skills add … -y (projeto) ou -g -y (máquina/experimental) ou CLI pinada — nunca curl | bash / irm | iex como método oficial.
3. Ler SKILL.md e scripts; respeitar o security scan do CLI (Snyk). Se High Risk → não versionar; remover e manter só como link no catálogo se útil.
4. Preferir ≥1k installs e orgs conhecidas (vercel-labs, anthropics, github, supabase, etc.).
5. Oficial + MIT + ≥1k + auditado → commit no repo via PR; resto → global/experimental (não versionar).
6. Skills externas não sobrescrevem standards/ AEX nem o fluxo ClickUp.
7. Spec Kit: sempre pin em tag de release, nunca main solto.

Atualizar

Relação com outras guias

• Cursor → cursor.md (aponta para este manual).
• Claude → claude.md.
• SDD normativo → SDD_STANDARD.
• Onboarding → handbook/ONBOARDING.md.
• Novo projeto → checklists/NEW_PROJECT.md.