plugin-creator

Plugin Creator

Início Rápido

1. Execute o script de scaffolding:

# Os nomes dos plugins são normalizados para minúsculas com hífens e devem ter no máximo 64 caracteres.
# O nome da pasta gerada e o nome em plugin.json são sempre os mesmos.
# Execute a partir da raiz do skill (o diretório que contém este SKILL.md).
# Por padrão, cria em ~/plugins/<nome-do-plugin>.
python3 scripts/create_basic_plugin.py <nome-do-plugin>

2. Edite <caminho-do-plugin>/.codex-plugin/plugin.json quando a solicitação fornecer metadados específicos. O scaffolding começa com padrões válidos e não deve conter marcadores [TODO: ...].

3. Gere ou atualize a entrada do marketplace pessoal quando o plugin deve aparecer na ordenação da interface do Codex:

# As entradas do marketplace pessoal têm como padrão ~/.agents/plugins/marketplace.json.
python3 scripts/create_basic_plugin.py meu-plugin --with-marketplace

Use --marketplace-name <nome> apenas quando o nome padrão personal já estiver em uso ou instalado e você precisar criar um novo arquivo de marketplace diferente:

python3 scripts/create_basic_plugin.py meu-plugin \
  --with-marketplace \
  --marketplace-name team-local

Use um marketplace de repositório/equipe apenas quando o usuário solicitar especificamente esse destino:

python3 scripts/create_basic_plugin.py meu-plugin \
  --path <raiz-do-repositorio>/plugins \
  --marketplace-path <raiz-do-repositorio>/.agents/plugins/marketplace.json \
  --with-marketplace

Quando o usuário especificar um caminho de marketplace, certifique-se de que esse marketplace esteja realmente instalado antes de informar o usuário para reinstalar a partir dele. O arquivo de marketplace pessoal padrão em ~/.agents/plugins/marketplace.json é descoberto implicitamente, mas outros caminhos de marketplace não. No Windows, use o caminho equivalente sob o perfil do usuário.

4. Gere/ajuste pastas complementares opcionais conforme necessário:

python3 scripts/create_basic_plugin.py meu-plugin \
  --path <diretorio-pai-do-plugin> \
  --marketplace-path <caminho-do-arquivo-marketplace-json> \
  --with-skills --with-hooks --with-scripts --with-assets --with-mcp --with-apps --with-marketplace

<diretorio-pai-do-plugin> é o diretório onde a pasta do plugin <nome-do-plugin> será criada (por exemplo, ~/plugins).

5. Antes de devolver um plugin gerado, execute:

python3 scripts/validate_plugin.py <caminho-do-plugin>

Para atualizações em um plugin local existente durante o desenvolvimento, mantenha o fluxo de scaffolding como está e use a referência em vez de editar manualmente os arquivos do marketplace:

python3 scripts/update_plugin_cachebuster.py <caminho-do-plugin>

Prefira o cachebuster padrão auxiliar, a menos que o usuário peça explicitamente uma substituição específica. Consulte references/installing-and-updating.md para obter o fluxo esperado de cachebuster e reinstalação ao iterar em um plugin local existente.

O que este skill cria

• Scaffolds baseados em marketplace usam o arquivo de marketplace pessoal em ~/.agents/plugins/marketplace.json, com os plugins geralmente armazenados em ~/plugins/<nome-do-plugin>/.
• Cria a raiz do plugin em /<diretorio-pai-do-plugin>/<nome-do-plugin>/.
• Sempre cria /<diretorio-pai-do-plugin>/<nome-do-plugin>/.codex-plugin/plugin.json.
• Preenche o manifesto com a forma de esquema validada que o caminho de ingestão aceita.
• Cria ou atualiza ~/.agents/plugins/marketplace.json quando --with-marketplace é definido.
  • Se o arquivo de marketplace ainda não existir, crie uma raiz de marketplace pessoal antes de adicionar a primeira entrada de plugin.
• <nome-do-plugin> é normalizado usando as regras de nomenclatura do skill-creator:
  • Meu Plugin → meu-plugin
  • Meu--Plugin → meu-plugin
  • underscores, espaços e pontuação são convertidos para -
  • o resultado é em minúsculas, delimitado por hífens, com hífens consecutivos colapsados
• Suporta a criação opcional de:
  • skills/
  • hooks/
  • scripts/
  • assets/
  • .mcp.json
  • .app.json

Fluxo de trabalho do marketplace

• A criação do marketplace pessoal tem como padrão ~/.agents/plugins/marketplace.json. Aqui, "marketplace pessoal" significa o marketplace cujo arquivo está nesse caminho.
• A criação de marketplace de repositório/equipe é opcional através de --path e --marketplace-path, apenas quando o usuário solicita especificamente.
• --marketplace-name é um caminho de exceção. Use-o apenas quando o nome padrão personal já estiver em uso e você precisar criar um novo arquivo de marketplace diferente.
• Não use --marketplace-name para renomear um arquivo de marketplace existente. Se o arquivo já existir, seu name de nível superior já deve corresponder.
• Se o usuário especificar um caminho de marketplace diferente, trate esse marketplace como necessitando instalação explícita via codex plugin marketplace add.
• Prefira scripts/read_marketplace_name.py quando precisar do nome do marketplace de qualquer arquivo marketplace.json. Sem argumentos, ele lê o marketplace pessoal padrão; com um caminho explícito, funciona também para marketplaces de repositório/equipe.
• Em ambos os locais, o caminho de origem gerado permanece ./plugins/<nome-do-plugin>.
• Os metadados raiz do marketplace suportam o name de nível superior mais o opcional interface.displayName.
• Trate a ordem do plugin em plugins[] como ordem de renderização no Codex. Anexe novas entradas, a menos que um usuário peça explicitamente para reordenar a lista.
• displayName pertence ao objeto interface do marketplace, não a entradas individuais de plugins[].
• Cada entrada de marketplace gerada deve incluir todos os itens a seguir:
  • policy.installation
  • policy.authentication
  • category
• Padrão para novas entradas:
  • policy.installation: "AVAILABLE"
  • policy.authentication: "ON_INSTALL"
• Substitua os padrões apenas quando o usuário especificar explicitamente outro valor permitido.
• Valores permitidos para policy.installation:
  • NOT_AVAILABLE
  • AVAILABLE
  • INSTALLED_BY_DEFAULT
• Valores permitidos para policy.authentication:
  • ON_INSTALL
  • ON_USE
• Trate policy.products como uma substituição. Omita-o, a menos que o usuário solicite explicitamente a restrição de produto.
• A forma da entrada de plugin gerada é:

{
  "name": "nome-do-plugin",
  "source": {
    "source": "local",
    "path": "./plugins/nome-do-plugin"
  },
  "policy": {
    "installation": "AVAILABLE",
    "authentication": "ON_INSTALL"
  },
  "category": "Productivity"
}

• Use --force apenas quando for intencionalmente substituir uma entrada de marketplace existente para o mesmo nome de plugin.

• Se o arquivo de marketplace de destino ainda não existir, crie-o com "name" de nível superior, um objeto "interface" contendo "displayName" e um array plugins, e então adicione a nova entrada.

• Para um arquivo de marketplace totalmente novo, o objeto raiz deve ser semelhante a:

{
  "name": "personal",
  "interface": {
    "displayName": "Personal"
  },
  "plugins": [
    {
      "name": "nome-do-plugin",
      "source": {
        "source": "local",
        "path": "./plugins/nome-do-plugin"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}

Comportamento obrigatório

• O nome da pasta externa e o "name" em plugin.json são sempre o mesmo nome de plugin normalizado.
• Não remova a estrutura obrigatória; mantenha .codex-plugin/plugin.json presente.
• Não deixe marcadores [TODO: ...] nos manifestos do plugin.
• Mantenha apps e mcpServers fora de plugin.json a menos que seus arquivos complementares sejam realmente criados.
• Omita campos de manifesto de plugin não suportados que a validação rejeita, incluindo hooks.
• Se estiver criando arquivos dentro de um caminho de plugin existente, use --force apenas quando a substituição for intencional.
• Preserve qualquer interface.displayName existente no marketplace.
• Ao gerar entradas de marketplace, sempre escreva policy.installation, policy.authentication e category, mesmo que seus valores sejam os padrões.
• Adicione policy.products apenas quando o usuário solicitar explicitamente essa substituição.
• Mantenha o source.path do marketplace relativo à raiz do marketplace selecionado como ./plugins/<nome-do-plugin>.
• Use --marketplace-name apenas ao criar um novo arquivo de marketplace cujo nome não deve ser personal porque esse nome já está em uso ou instalado em outro lugar.
• Se o Codex precisar de aprovação para gravar o arquivo de marketplace, peça essa aprovação antes de prosseguir. Se o usuário preferir executar a gravação por conta própria, forneça o comando de scaffolding exato e continue a partir da validação ou edições subsequentes do plugin, em vez de deixar o fluxo de trabalho vago.
• Para atualizações em um plugin local existente durante o desenvolvimento, não edite manualmente a configuração do marketplace ou marketplace.json. Use o fluxo de atualização documentado em references/installing-and-updating.md e scripts/update_plugin_cachebuster.py.
• Não diga ao usuário para executar codex plugin marketplace add para o fluxo padrão do marketplace pessoal. Esse comando é para configuração explícita de marketplace não padrão, não para o caminho padrão ~/.agents/plugins/marketplace.json.
• Se o usuário forneceu um --marketplace-path não padrão, certifique-se de que esse marketplace esteja instalado antes de dar instruções de reinstalação. Use codex plugin marketplace add <caminho-para-raiz-do-marketplace> quando esse marketplace explícito ainda não tiver sido configurado.
• Quando o fluxo de trabalho criou ou atualizou um plugin baseado em marketplace, termine a resposta final voltada ao usuário com uma breve transferência do aplicativo Codex. Diga Para visualizar no aplicativo Codex: e escreva View <nome-do-plugin normalizado> e Share <nome-do-plugin normalizado> como links Markdown, não URLs brutas ou spans de código.
• O deep link de View usa codex://plugins/<nome-do-plugin normalizado>?marketplacePath=<caminho absoluto para marketplace.json>. O deep link de Share usa a mesma URL com &mode=share.
• Substitua os placeholders pelo nome real do plugin normalizado e pelo caminho absoluto de marketplace.json do plugin criado. Codifique o segmento de caminho e o valor da consulta na URL quando necessário.
• Não adicione parâmetros de consulta pluginName ou hostId a esses deep links. O Codex deriva ambos após o usuário clicar no link.
• Não emita os links View <nome-do-plugin normalizado> ou Share <nome-do-plugin normalizado> quando nenhuma entrada de marketplace foi criada ou atualizada.

Referência para a amostra exata da especificação

Para a amostra JSON canônica exata de manifestos de plugin e entradas de marketplace, use:

• references/plugin-json-spec.md
• references/installing-and-updating.md para orientação sobre atualização/reinstalação ao iterar em um plugin local existente, além do comportamento de retomada de nova thread após a reinstalação

Validação

Após editar SKILL.md, execute:

python3 ../skill-creator/scripts/quick_validate.py .

Antes de devolver um plugin gerado, execute:

python3 scripts/validate_plugin.py <caminho-do-plugin>