Skillbase/spm

npm para habilidades de IA. Crie, compartilhe e descubra instruções de IA reutilizáveis para qualquer modelo via MCP.

Documentação

Skillbase / spm

Gerenciador de Pacotes de Skills — instale, compartilhe e gerencie skills de IA reutilizáveis em qualquer cliente compatível com MCP.

O que é spm?

spm é um gerenciador de pacotes para skills de IA. Skills são instruções estruturadas — não código — que ensinam modelos de IA a executar tarefas específicas: revisão de código, auditorias de segurança, design de API, engenharia de prompt, análise DeFi e muito mais.

npm install -g @skillbase/spm

spm conecta-se ao seu cliente de IA via MCP (Model Context Protocol), dando à sua IA acesso a um registro de skills contribuídas pela comunidade que carregam sob demanda.

Diferente de abordagens baseadas em npm que se aproveitam de node_modules, spm tem seu próprio registro, seu próprio formato e funciona com qualquer cliente de IA — não apenas editores de código.

Já usa Vercel Skills? spm é totalmente compatível — spm add owner/repo/skill-name e pronto. Conversão automática, sem etapas extras. Veja os detalhes abaixo.

Início rápido

# Install
npm install -g @skillbase/spm

# Initialize in your project
spm init

# Connect to your AI client
spm connect claude       # Claude Desktop / Claude Code
spm connect cursor       # Cursor
spm connect vscode       # VS Code (Copilot)
spm connect windsurf     # Windsurf
spm connect jetbrains    # Any JetBrains IDE

# Install a skill
spm add skillbase/arch-code-review

# Install a persona (a bundle of skills with a defined role)
spm persona add skillbase/sec

Uma vez conectado, sua IA descobre e carrega skills automaticamente ao encontrar uma tarefa correspondente. Nenhuma invocação manual é necessária.

Como funciona

spm se registra como um servidor MCP. Seu cliente de IA recebe cinco ferramentas:

Ferramenta	Finalidade
`skill_list`	Navegar pelas skills instaladas (índice compacto, não conteúdo completo)
`skill_load`	Carregar as instruções completas de uma skill no contexto
`skill_search`	Encontrar skills por palavra-chave, tag ou padrão de arquivo
`skill_install`	Instalar novas skills do registro
`skill_feedback`	Avaliar a qualidade da skill (alimenta pontuações de confiança)

Carregamento sob demanda (lazy loading) é a chave do design. A IA vê um índice leve de todas as skills instaladas. Quando encontra uma tarefa que corresponde ao gatilho de uma skill, ela carrega apenas as instruções completas daquela skill. Isso mantém as janelas de contexto limpas e permite instalar dezenas de skills sem sobrecarga.

User: "Review this pull request for architecture issues"
  ↓
AI sees skill_list → finds arch-code-review (trigger matches)
  ↓
AI calls skill_load("arch-code-review")
  ↓
Full review methodology loads into context
  ↓
AI performs structured code review

O que há dentro de uma skill?

Uma skill é um diretório. Em seu núcleo está um arquivo SKILL.md — Markdown estruturado com frontmatter YAML:

---
name: arch-code-review
version: 1.0.3
description: "Architecture-aware code review"
tags: [code-review, architecture, solid, complexity]
triggers:
  - "code review"
  - "architecture review"
  - "pull request review"
---

# Code Review Methodology

## Evaluation criteria
- Coupling/cohesion at module and class level
- SOLID principle adherence
- Cyclomatic complexity hotspots
...

Mas uma skill não se limita a instruções. O diretório também pode conter scripts auxiliares, templates, arquivos de exemplo e quaisquer outros recursos que a IA precise durante a execução. Pense em SKILL.md como package.json — é o ponto de entrada, mas o diretório inteiro é o pacote.

Recursos das skills

Versionamento Semver — skillbase/arch-code-review@1.0.3
Dependências — skills podem depender de outras skills
Arquivos auxiliares — scripts, templates, dados de referência agrupados junto com as instruções
Gatilhos — descrições e padrões de arquivo que ajudam a IA a decidir quando carregar
Tags — para busca e descoberta
Pontuações de confiança — calculadas a partir de feedback real de usuários via skill_feedback

Personas

Uma persona agrupa múltiplas skills em uma identidade completa de IA com papel, tom e área de especialização definidos.

spm persona add skillbase/sec

Isso instala a persona Security Auditor com suas dependências: smart-contract-audit, appsec e web3-threat-modeling. Quando ativada, a IA assume o papel da persona e tem acesso a todas as skills agrupadas.

Personas disponíveis:

Persona	Papel	Skills
`arch`	Arquiteto de software	design de sistemas, contratos de API, revisão de código
`py`	Engenheiro backend Python	FastAPI, async, testes, MongoDB/PostgreSQL
`ts`	Desenvolvedor fullstack TypeScript	React/Next/Nuxt, Node, Tailwind, wagmi
`sol`	Desenvolvedor Solidity/EVM	Foundry, OpenZeppelin, otimização de gas
`sec`	Auditor de segurança	auditoria de smart contracts, AppSec, modelagem de ameaças
`trader`	Trader DeFi/cripto	análise on-chain, estratégias de yield, MEV
`growth`	Marketeiro de crescimento	funis, métricas, go-to-market Web3
`prompt-engineer`	Engenheiro de prompt	autoria de SKILL.md, melhores práticas de prompt
`prompt-manager`	Gerente de prompt	pesquisa de demanda de skills, revisão de qualidade

Sincronização de equipe

Skillbase Sync adiciona configuração em nível de equipe e compartilhamento de conhecimento sobre o spm. Defina um conjunto padrão de skills para o seu projeto — todos instalam com um único comando.

# Link your repo to a Sync project
spm sync init

# Install everything the project requires
spm sync

# Check what's missing without installing
spm sync --status

Quando o Sync está conectado, seu agente de IA também tem acesso ao conhecimento compartilhado da equipe — decisões, restrições e contexto capturados pelos colegas. Chega de começar do zero quando outra pessoa assume uma tarefa.

Saiba mais: documentação do Sync

Registro

O registro hospeda skills em vários domínios:

Desenvolvimento — python-backend, python-testing, db-mongodb, arch-code-review, arch-api-design, arch-system-design

Segurança — appsec, smart-contract-audit, web3-threat-modeling, prompt-injection-detector, jailbreak-scanner, prompt-safety-validator

DeFi & Trading — yield-analysis, leverage-calc, onchain-signals, mev-awareness, trade-journal

Crescimento & Estratégia — defi-growth-strategy, growth-airdrop-design, web3-grant-writing

Meta — prompt-engineering-craft (aprenda a escrever melhores prompts e skills)

Explore o registro completo: skillbase.space/explore

Compatibilidade com Vercel Skills

spm é totalmente compatível com Vercel Skills e qualquer skill hospedada no GitHub que siga o mesmo formato SKILL.md. Você não precisa escolher — se uma skill existe no GitHub, você pode usá-la no spm.

Instale diretamente — um comando, converte e instala automaticamente:

spm add vercel-labs/agent-skills/web-design-guidelines

É isso. spm busca a skill do GitHub, detecta o formato, converte para SPM em tempo real e instala localmente. Pronta para uso imediato — sem flags, sem etapas extras.

Ou converta primeiro, depois publique — se quiser revisar, editar e compartilhar com a comunidade:

# 1. Fetch and convert to a local directory
spm convert vercel-labs/agent-skills/web-design-guidelines -o ./

# 2. Review and edit SKILL.md if needed
# 3. Publish to the spm registry
spm publish ./web-design-guidelines

O autor padrão é o dono do repositório GitHub. Substitua com --author <name> se necessário. A flag --skill <name> também é suportada como alternativa: spm add vercel-labs/agent-skills --skill web-design-guidelines.

O que spm adiciona além da skill original:

Recurso	Vercel Skills	Com spm
Versionamento	nenhum	semver (`1.0.0`)
Dependências	não suportado	dependências skill-para-skill com resolução
Carregamento sob demanda	nenhum	sob demanda via MCP
Descoberta	manual	acionamento automático por tarefa, tags, padrões de arquivo
Feedback e pontuação	nenhum	pontuações de confiança de uso real
Suporte a clientes	editores selecionados	qualquer cliente MCP (15+)
Personas	nenhuma	agrupa skills em papéis

Você também pode listar todas as skills disponíveis em um repositório antes de instalar:

spm convert vercel-labs/agent-skills
# → lists all skills in the repo's skills/ directory

Funciona com qualquer repositório GitHub que contenha arquivos SKILL.md — não limitado aos repositórios da Vercel.

Publique sua própria skill

Pela CLI:

# Scaffold a new skill from scratch
spm create my-skill

# Or convert an existing prompt file
spm convert my-prompt.md --author myname

# Or import from GitHub (auto-converts Vercel Skills)
spm convert owner/repo/skill-name -o ./

# Edit SKILL.md, then publish
spm publish

Pelo Skillbase Studio:

Skillbase Studio oferece um editor visual para criar, testar, publicar e instalar skills — tudo no navegador. O Studio se comunica com seu daemon spm local para publicar e instalar diretamente pela interface.

Crie ou importe uma skill no Studio
Edite e teste com o sandbox integrado
Clique em Publish — o Studio envia o SKILL.md compilado para o seu spm local, que lida com a autenticação e o upload no registro
Clique em Install — instala a versão publicada localmente via spm

O Studio requer que o spm esteja rodando localmente (spm status-server start ou clique em "Connect spm" na interface). Toda publicação usa suas credenciais spm login existentes.

Skills são gratuitas para publicar e gratuitas para usar. O registro é aberto.

Clientes suportados

spm funciona com qualquer cliente que suporte MCP:

Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, Cline, Roo Code, IDEs JetBrains (todas), Zed, OpenAI Codex, Emacs, Neovim e outros.

# See all supported clients
spm connect --list

Por que não usar apenas npm?

Alguns projetos agrupam skills de IA dentro de pacotes npm. spm adota uma abordagem diferente:

Registro próprio — skills são cidadãs de primeira classe, não um efeito colateral do npm install. Descoberta, busca, versionamento e pontuações de confiança são integrados.
Não vinculado ao Node.js — skills do spm funcionam com qualquer cliente de IA em qualquer plataforma. Você não precisa de uma pasta node_modules.
Carregamento sob demanda via MCP — skills carregam no contexto da IA sob demanda, não todas de uma vez. Isso é crítico quando você tem dezenas de skills.
Ciclo de feedback — skill_feedback permite que usuários avaliem skills. Pontuações de confiança destacam as skills mais eficazes.
Personas — agrupa skills em papéis. npm não tem esse conceito.
Formato extensível — uma skill pode crescer de instruções puras para incluir scripts, templates e dados sem mudar como é instalada ou carregada.
Compatível, sem aprisionamento — importe skills do Vercel Skills, GitHub ou arquivos de prompt locais. spm convert lida com a conversão de formato automaticamente.

Segurança

Todas as skills e personas no registro público passam por uma revisão de segurança antes da publicação. Arquivos auxiliares agrupados com skills são escaneados com antivírus e ferramentas adicionais de segurança automatizada. spm usa autorização com escopo de token para publicação — apenas autores verificados podem atualizar seus pacotes.

O formato SKILL.md é Markdown simples com metadados estruturados — não há execução de script postinstall ou efeitos colaterais ocultos.

Contribuindo

Aceitamos skills, relatórios de bugs, solicitações de recursos e melhorias na documentação.

Licença

MIT — veja LICENSE.