Usar plugins / Criar plugins

Instale um pacote nos agentes que você usa ou crie um pacote portátil Agent Plugins 1.0 com instruções e configuração de ferramentas.

Usar plugins

Com Node.js 22 ou mais recente:

npx universal-agent-plugins add context7

A CLI pergunta quais agentes compatíveis você quer usar e informa as etapas de ativação pendentes. Para inspecionar e conferir o plano primeiro:

npx universal-agent-plugins info context7
npx universal-agent-plugins add context7 --target codex,cursor --dry-run

O guia de instalação nativa também fornece executáveis para macOS, Linux e Windows. O gerenciador nativo não precisa de Node.js, embora plugins individuais possam precisar de seus próprios ambientes de execução. Confira npx universal-agent-plugins version ao usar npm: um canal de gerenciador de pacotes ainda pode fornecer uma CLI mais antiga. A seleção automática abaixo exige 0.1.94; o instalador nativo fornece a versão verificada. Os comandos explícitos de projeto deste guia também funcionam com a 0.1.93.

A CLI 0.1.95 mantém o escopo de projeto explícito e a seleção automática de install, introduzida na 0.1.94. Ela também adiciona uma API local de gerenciamento e extensões nativas do Pi. Para conferir o plano de adição de um pacote a um projeto:

npx universal-agent-plugins add context7 --target cursor --scope project \
  --project-root /path/to/project --dry-run

Escolha um diretório de projeto existente. Os comandos de adição e manutenção usam o escopo de usuário por padrão, então selecione o escopo de projeto explicitamente. Na 0.1.94, install sem argumento de origem só seleciona o projeto se a pasta atual exata contiver um arquivo regular uap.toml; o escopo explícito prevalece e não há busca em pastas superiores. Revise o plano antes de omitir --dry-run. Descoberta nativa, confiança, autenticação e chamadas MCP bem-sucedidas continuam separadas da gravação dos arquivos do pacote.

Caminho completo de instalação · Compatibilidade dos clientes e limites dos testes

Restaure um conjunto de dependências salvo

Confira o que está registrado no ambiente de usuário selecionado:

npx universal-agent-plugins deps status

Para um par uap.toml/uap.lock salvo, exporte a partir de uma pasta de intercâmbio:

npx universal-agent-plugins deps export

Copie a pasta para outra máquina, instale seus clientes de destino e execute lá:

npx universal-agent-plugins deps import
npx universal-agent-plugins install --locked --scope user

Somente o acordo de dependências validado e o lock são transferidos. Perfis, configurações, credenciais, recibos e dados dos plugins ficam separados. A instalação ainda precisa das origens exatas ou de pacotes verificados em cache. Para um projeto, inclua o par no controle de versão e restaure com install --locked --scope project explícito. Consulte manutenção e restauração para detalhes de recuperação e transferência.

Criar plugins

Um pacote padrão começa com plugin.json na raiz e pode incluir skills/<name>/SKILL.md, mcp.json ou ambos. Você pode escrever esses arquivos manualmente e validar o pacote com o instalador lançado:

npx universal-agent-plugins validate ./my-plugin
npx universal-agent-plugins add ./my-plugin --target codex --dry-run

Esses exemplos pressupõem que ./my-plugin já contém um pacote completo. O guia de criação apresenta um pequeno pacote Skill manual e as ferramentas de geração de estruturas iniciais compiladas do código-fonte.

Disponibilidade das ferramentas de criação: a versão atual do instalador npm e nativo não inclui agentplugins author. O código-fonte atual implementa geração de estruturas iniciais, verificações estáticas, testes explícitos de execução MCP, ciclos de desenvolvimento, bootstrap de dependências e manutenção de JSON. Use a configuração de compilação do código-fonte para esses comandos. As evidências de versões anteriores das ferramentas de criação permanecem vinculadas às respectivas versões; elas não prometem esses recursos no instalador atualmente disponível para download.

A validação estática não comprova execução, OAuth nem ativação. O suporte a transportes MCP também varia por cliente; por exemplo, Codex não aceita MCP SSE declarado. Mantenha os requisitos do pacote e as verificações pendentes visíveis no README.

Especificação Agent Plugins 1.0