skillpack-cli

📦 NPM: npmjs.com/package/skillpack-cli
🐙 GitHub: github.com/silvakwan1/skillpack-cli

CLI que cria/atualiza a pasta .agents do seu projeto (com AGENTS.md, agents/ e skills/ por framework), pra padronizar como agentes de IA (Claude, Cursor, Copilot, Antigravity etc.) trabalham no repositório.

Uso sem Instalar (On-Demand)

Você pode rodar diretamente sem instalar nada no seu projeto usando npx skillpack-cli:

# cria .agents do zero e adiciona a skill de JavaScript
npx skillpack-cli --js

# cria .agents e adiciona Next.js e Laravel
npx skillpack-cli --next --laravel

# adiciona todas as skills disponíveis
npx skillpack-cli --all

# ver frameworks suportados
npx skillpack-cli --list

Uso Instalado no Projeto

Se preferir manter a lib nas dependências do projeto:

npm i -D skillpack-cli

Após instalar, você pode usar qualquer um dos atalhos disponíveis:

npx skills --js
# ou
npx skillpack-cli --next

Comportamento

• Se .agents não existir: cria a estrutura base, instala as skills e definições centrais e gera os adaptadores oficiais do planner para Antigravity, Claude Code, OpenCode e Codex.
• Se .agents já existir: adiciona o que estiver ausente. Adaptadores gerados e ainda intactos podem ser atualizados; arquivos alterados manualmente são preservados com base nos hashes de .agents/.manifest.json.
• planner.yml é a fonte central reutilizável do comportamento. O CLI renderiza o mesmo prompt em todas as plataformas; somente frontmatter, permissões e caminhos variam.

Skills Universais (Base)

Ao rodar qualquer comando, as seguintes skills universais são instaladas automaticamente (se ainda não existirem):

| Skill | Descrição | |-------|-----------| | security-audit | Auditoria de segurança: OWASP Top 10, secrets, dependências, XSS/CSRF/SQLi | | code-review | Revisão de código multi-eixo: corretude, legibilidade, arquitetura, performance | | git-workflow | Padrões de Git: commits semânticos, branching, PR descriptions, changelog | | performance | Otimização de performance: profiling, bundle size, queries, caching | | documentation | Geração de docs: README, ADRs, API docs, JSDoc/TSDoc, CHANGELOG | | testing | Estratégia de testes: unitários, integração, E2E, coverage, mocking | | backend | Padrões universais de Backend: APIs REST/GraphQL, Prisma, SQL, JWT, Zod | | frontend | Padrões universais de Frontend: Componentes visuais, WCAG, Mobile-first, React Hook Form |

Definições centrais de agentes

Os arquivos .agents/agents/<nome>/<nome>.yml são o esquema interno do Skillpack. A combinação SKILL.md + .yml não é um formato universal de agentes: cada ferramenta possui seu próprio local de descoberta e seu próprio schema. O renderer em src/utils/agent-adapters.ts faz essa tradução sem duplicar prompts.

O planner é o primeiro agente com adaptadores multiplataforma. A transformação é genérica e pode ser habilitada depois para manager, backend-dev, frontend-dev, qa-engineer e outros agentes que declarem suas capacidades no YAML central.

| Agente | Diretório | Skills Atribuídas | |--------|-----------|-------------------| | Arquiteto de Software | .agents/agents/architect/ | security-audit, performance, code-review | | Revisor de Código | .agents/agents/code-reviewer/ | code-review, security-audit, testing | | DevOps Engineer | .agents/agents/devops/ | git-workflow, security-audit, performance | | Documentador | .agents/agents/documentador/ | documentation, code-review | | QA Lead | .agents/agents/qa-lead/ | testing, security-audit, code-review, performance | | Backend Dev Sênior | .agents/agents/backend-dev/ | backend, security-audit, code-review | | Frontend Dev Sênior | .agents/agents/frontend-dev/ | frontend, code-review, performance |

Descoberta e execução do planner

| Plataforma | Arquivo oficial | Onde aparece | Como executar | |------------|-----------------|--------------|---------------| | Google Antigravity | .agents/agents/planner/agent.md | painel /agents, como agente principal e subagente | selecione planner em /agents ou peça ao agente principal para invocá-lo | | Claude Code | .claude/agents/planner.md | /agents e autocomplete de agentes | digite @planner e selecione o agente (ou use a forma explícita @agent-planner); para a sessão inteira, claude --agent planner | | OpenCode | .opencode/agents/planner.md | seleção de agentes primários e autocomplete @ | selecione com Tab/switch_agent ou use @planner | | Codex | .codex/agents/planner.toml | catálogo de agentes personalizados para delegação | peça ao Codex para delegar o planejamento ao agente planner; use /agent no CLI para inspecionar a thread |

Referências oficiais: Antigravity custom agents, Claude Code subagents, OpenCode agents e Codex subagents.

A skill portátil correspondente permanece em .agents/skills/planner/SKILL.md. OpenCode e Antigravity descobrem as skills em .agents/skills/. Para o preload oficial do Claude Code, o CLI também espelha somente as skills aplicáveis em .claude/skills/.

Estrutura Gerada

.
├── .agents/
│   ├── AGENTS.md
│   ├── .manifest.json
│   ├── agents/planner/
│   │   ├── planner.yml   # fonte central
│   │   ├── agent.md      # Google Antigravity
│   │   └── SKILL.md      # compatibilidade legada, quando presente no template
│   └── skills/planner/SKILL.md
├── .claude/
│   ├── agents/planner.md
│   └── skills/<skill-aplicável>/SKILL.md
├── .opencode/agents/planner.md
└── .codex/agents/planner.toml

Adicionar um novo framework

1. Crie templates/<nome>/.agents/skills/<nome>/SKILL.md com as regras.
2. Registre em src/utils/frameworks.ts:

js: {
  flag: 'js',
  label: 'JavaScript (Generic)',
  templateDir: 'js',
},

Pronto — npx skills --js já funciona.

Proteção contra sobrescrita

O CLI não sobrescreve adaptadores que você editou manualmente:

• Skills universais e agentes são rastreados no .manifest.json.
• Cada adaptador gerado recebe um hash no manifest.
• Se o hash atual ainda for o hash gerado anteriormente, o arquivo pode ser atualizado com segurança.
• Se o conteúdo divergir do hash conhecido ou o arquivo não tiver histórico, ele é preservado.