@acropole/skills

Skills, subagentes revisores e fluxos de trabalho para o Claude Code, cobrindo a stack da plataforma: apps Angular com o design system Trismegisto, gateways GraphQL (Apollo) e servidores Express em Node, serviços FastAPI em Python, autorização/auditoria com o SDK Orfeu, Dockerfiles e deploy pelo Hefesto.

Cada skill cobre uma parte da stack e elas se complementam (a orquestracao encadeia todas numa mudança grande): numa tela Angular entram angular, trismegisto e orfeu; num resolver GraphQL, apollo, express e orfeu; no deploy, docker e hefesto; ao mexer numa tela, documentacao mantém o manual dela em dia. A skill acropole é a porta de entrada: descobre a stack e encadeia as outras.

Skills

| Skill | Assunto | Exemplo de pedido que a dispara | | --- | --- | --- | | acropole | Porta de entrada e padrão arquitetural dos apps (pastas, ambientes, saúde, segurança, dependências, scripts, testes); fluxos app-novo, tela-nova, endpoint-novo, revisar, doctor, atualizar-libs | /acropole, "cria a estrutura do app novo", "esse app segue o padrão?" | | angular | Estrutura dos apps Angular, bootstrap com o spine, telas por router_id, serviços GraphQL, signals, testes, build | "cria a tela de pedidos no app de vendas" | | trismegisto | Interface com o design system (@trismegisto/*, componentes hm-*, tokens --hm-*, tema, ícones, a11y) e o shell spine | "troca essa tabela por um data grid", "o botão some no tema escuro" | | orfeu | SDK Orfeu: login/sessão no front, operações e níveis no backend, auditoria, traceparent, propagação entre serviços | "protege essa rota", "o usuário toma 403", "audita a exclusão" | | apollo | Servidores GraphQL (Apollo Server): schema, resolvers, envelope { status, message, data }, subscriptions | "expõe uma mutation para cancelar pedido" | | express | Servidores Node com Express: middlewares, rotas REST, erros, Knex, shutdown | "cria a rota REST de upload no servidor Node" | | fastapi | Serviços Python com FastAPI: domínios, settings, SQLAlchemy, envelope, pytest | "adiciona o domínio de faturas no serviço Python" | | docker | Dockerfile e .dockerignore (Angular estático, Node, Python): multi-stage, CMD exec, não-root, healthcheck | "escreve o Dockerfile desse serviço", "o container demora a parar" | | hefesto | Deploy pela plataforma Hefesto: aplicação, ambientes, variáveis, deploy/redeploy, rollback, diagnóstico, e o MCP de deploy (hefesto-mcp) para um agente de IA | "prepara esse app para subir no Hefesto", "o deploy falhou", "faz o redeploy do pedidos-api em homol pelo MCP" | | orquestracao | Mudança grande do pedido à entrega (spec → plano em itens Txx → execução por vários agentes/sessões com reserva atômica via coord.sh → provas → Argos → fechamento) e como paralelizar com subagentes | "faz a spec e o plano", "paraleliza entre agentes", "distribui esses itens" | | auto-servico | MCP do auto-serviço do Argos (argos-mcp): configurar um agente de IA (uma conexão por aplicação, x-app-token, escopos), roteiros das tools (tela, acesso, permissões) e diagnóstico | "configura o agente para usar o MCP do Argos", "publica a tela pelo MCP" | | documentacao | Manual das telas Angular: README.md/ESPECIFICACAO.md ligados no document da rota, loader .md, revisão da doc a cada mudança da tela (registro de revisão em .documentacao.json) | "documenta a tela de pedidos", "a doc dessa tela ainda vale?" |

Subagentes revisores

Instalados em .claude/agents/. Só leem e relatam (caminho:linha, problema, correção, em ordem de gravidade); nunca editam. Antes de opinar, rodam os verificadores das skills e confirmam cada achado lendo o arquivo.

| Agente | Revisa | | --- | --- | | revisor-trismegisto | Interface Angular: hm-* em vez de HTML/CSS próprio, tokens --hm-*, ícones do catálogo, acessibilidade, tema/densidade, estado de erro com "Tentar novamente", confirmação de ação destrutiva, formulários | | revisor-documentacao | Documentação das telas: README/ESPECIFICACAO ainda descrevem ações, rótulos, estados, colunas, filtros e permissões da tela; diz o que mudar e o comando que registra a revisão (nunca registra) | | revisor-orfeu | Segurança/integração: rota/resolver com operação, PUBLIC justificado, nada de JWT à mão, orfeuHeaders só entre serviços próprios, details sem dado sensível, headers propagados, contexto do WebSocket sem connectionParams espalhado, posse do recurso em rota escopada (IDOR) | | revisor-deploy | Entrega: CMD em forma exec, usuário não-root, sem credencial/.npmrc na imagem, segredo sem valor padrão nem no argv, healthcheck, porta, variáveis em runtime |

O Claude Code chama o revisor quando a tarefa bate com a descrição dele; você também pode pedir ("usa o revisor-orfeu nesse resolver") ou passar pelo fluxo /acropole revisar.

Fluxos (/acropole)

| Comando | O que faz | | --- | --- | | /acropole | Lê package.json/pyproject.toml/requirements.txt, identifica a stack e sugere 2–3 fluxos. Não executa nada sozinho | | /acropole app-novo | Estrutura inicial no padrão: angular/, graphql/, server/, database/ copiados de um app de referência, sem domínio, com specs fixos, /health, ambientes e README; tudo testado | | /acropole tela-nova | Argos (router_id) → features.routes → .graphql + codegen → service → componente hm-* → operação no backend → testes | | /acropole endpoint-novo | Rota/resolver (fastapi, express ou apollo) + operação do Orfeu + propagação de headers + auditoria + teste | | /acropole revisar [caminho] | Roda os verificadores sobre o diff/arquivos e chama os revisores. Relata; não corrige sem pedido | | /acropole doctor [pasta] | Diagnostica versões @trismegisto/*, cópias de @orfeu/angular, ordem de styles, provideHttpClient(withInterceptorsFromDi()), Dockerfile, orfeu Python. Achados em corrige (aplicados com --fix, só se você pedir), avisa e pergunta | | /acropole atualizar-libs [pasta] | Guia para levar um app às libs de 2026-10 (@trismegisto/* 2.1.2, @orfeu/* e orfeu 1.4.0): o que muda em cada camada, configuração no Argos, variáveis novas, verificação, armadilhas e checklist |

Verificadores

Algumas skills trazem scripts/checar.mjs (Node, sem dependências), que aponta violações das regras da skill em arquivos ou pastas:

node ~/.claude/skills/trismegisto/scripts/checar.mjs src/app          # texto: arquivo:linha regra mensagem → correção
node ~/.claude/skills/orfeu/scripts/checar.mjs --json src             # JSON para máquina

O código de saída é 1 quando há achado (dá para usar em CI ou hook). O da skill documentacao recebe a pasta do app e tem ainda --registrar-revisao <pasta-da-feature|todas>, que registra a revisão da doc de uma tela (escreve só src/app/features/.documentacao.json). Uma exceção consciente se marca na linha anterior, sempre com motivo: // acropole-ignore-next-line <regra> -- <motivo>. Os revisores e o fluxo revisar usam esses verificadores como ponto de partida e confirmam cada achado lendo o código.

O diagnóstico do projeto fica na skill acropole:

node ~/.claude/skills/acropole/scripts/doctor.mjs [pasta] [--json] [--fix]

Instalação

npx @acropole/skills                     # skills em ~/.claude/skills/ e agentes em ~/.claude/agents/
npx @acropole/skills --project           # só neste projeto (./.claude/skills/ e ./.claude/agents/)
npx @acropole/skills --only angular,trismegisto,revisor-trismegisto
npx @acropole/skills --no-agents         # só as skills

Skills e agentes valem a partir da próxima sessão do Claude Code. Requer Node 18 ou superior.

Atualização, status e remoção

npx @acropole/skills@latest              # atualiza (substitui as pastas/arquivos do pacote)
npx @acropole/skills --status            # o que está instalado, versão e se está defasado
npx @acropole/skills --list              # skills e agentes do pacote
npx @acropole/skills --uninstall         # remove skills e agentes do pacote
npx @acropole/skills --uninstall --project

| Opção | Efeito | | --- | --- | | --project | usa ./.claude/ em vez de ~/.claude/ | | --only a,b | só as skills/agentes indicados | | --no-agents | não instala (nem remove, com --uninstall) os agentes | | --uninstall | remove o que é do pacote (combina com --project, --only, --no-agents) | | --force | substitui/remove pasta ou arquivo de mesmo nome que não veio deste pacote | | --status | compara a versão instalada (VERSION das skills, marca dos agentes) com a do pacote em execução | | --list / --help | lista / ajuda |

O --status não consulta a rede: compara com a versão do pacote que está rodando. Para comparar com a última publicada, rode npx @acropole/skills@latest --status.

Para quem mantém o pacote

Os catálogos de API do Trismegisto (skills/trismegisto/references/*-api.md, angular-exports.md e catalogo/{tokens,seletores,icones}.json, que o verificador da skill usa) são gerados do código-fonte das libs e ficam commitados; regenere só quando a API delas mudar. Os geradores (scripts/gerar/) não supõem onde as libs estão:

npm run sync -- --trismegisto <raiz do monorepo do Trismegisto>   # ou --angular <dir> --spine <dir>, ou TRISMEGISTO_SRC
npm run sync -- --check --trismegisto <raiz>                      # não grava; falha se o commitado estiver velho
npm test                                                          # instalador + integridade (links, fixtures dos verificadores...)

O núcleo dos verificadores tem uma fonte só, scripts/checar-nucleo.mjs; o npm run sync (mesmo sem fonte do Trismegisto) copia para skills/<skill>/scripts/nucleo.mjs. Fixtures de cada verificador ficam em test/fixtures/<skill>/{ruim,bom}/ (fora do pacote publicado).

Build e release

No disco, este repo fica em astra/packages/acropole (github.com/konvndor/acropole, branch master).

scripts/build-publish.sh build      # npm test + npm pack -> tarballs/acropole-skills-<versão>.tgz (fora do git)

A publicação oficial é feita pelo GitHub Actions (workflow Release, .github/workflows/release.yml) com Trusted Publishing (OIDC, sem NPM_TOKEN no repositório), e ninguém cria tag à mão:

1. Suba a versão: npm run bump -- <patch|minor|major|X.Y.Z> (só troca o version; recusa versão menor que a atual ou já publicada; não faz commit nem tag).
2. Push/merge na master. O Release detecta a versão nova e roda o npm test (job Verificar). Push sem versão nova só detecta "Nada a publicar" — nada de build. O push nunca publica. O CI completo não roda no push: só em PR ou à mão (Actions → CI → Run workflow).
3. Confira o resumo da execução (Actions → Release): "✅ pronto para publicar", "❌ testes falharam, não publique" ou "Nada a publicar".
4. Clique em Run workflow (Actions → Release → Run workflow, branch master). O clique é a aprovação: o workflow confere de novo, roda o npm test, roda npm publish --access public (npm ≥ 11.5.1) e cria e empurra a tag v<versão>. Versão ou tag que já existem são puladas com aviso. Fora da master, falha de propósito.

Environment release. O job de publicação usa o environment release, criado no GitHub sem regras de proteção (repo privado em conta Free, sem Required reviewers). Ele existe porque é o nome cadastrado no Trusted Publisher do npm (dono konvndor, repositório acropole, workflow release.yml, environment release): o npm só aceita o token OIDC vindo dele. A aprovação é o clique em Run workflow. O repositório é privado: o npm não gera proveniência e o package.json publicado não leva repository (não acrescente).

Primeira publicação (1.0.0). O Trusted Publisher só pode ser usado depois que o pacote existe no npm, então a 1.0.0 sai pelo script local, com token:

cp scripts/.env.example scripts/.env       # preencha NPM_TOKEN; scripts/.env é ignorado pelo git
scripts/build-publish.sh publish

O publish vai sempre para o npm público. Antes de publicar, o script confere se a versão já existe no npm e, se existir, sobe o patch sozinho. Nunca copie secrets de outro lugar por cima de um scripts/.env existente.

Ainda não coberto

React (@trismegisto/react), Strawberry (GraphQL em Python), Fastify, Django e Flask. O Orfeu tem adapters para alguns deles, mas não há skill de padrões; o Claude é instruído a dizer isso em vez de aplicar por analogia o padrão de outra stack.

Privacidade e o que o instalador faz

• Nenhuma requisição de rede e nenhuma telemetria — nem o instalador, nem os verificadores, nem o doctor. (Quem baixa o pacote é o npx.)
• O instalador só escreve em .claude/skills/<skill>/ e .claude/agents/<agente>.md dos itens do pacote, mais o manifesto .claude/agents/.acropole-manifest.json.
• Cada pasta de skill instalada leva um arquivo .acropole e cada agente uma linha <!-- acropole: instalado por @acropole/skills <versão> --> logo após o frontmatter. Pasta ou arquivo de mesmo nome sem essa marca (de outra origem) não é substituído nem removido, a menos que você use --force. A verificação acontece antes de qualquer escrita: não há instalação parcial.
• Os verificadores e o doctor só leem arquivos do projeto; o doctor nunca lê .env ou .npmrc (só verifica se entram na imagem) e só altera arquivos com --fix, e apenas nas correções mecânicas.