grahama1970/plugin-creator

Plugin Creator

Início Rápido

1. Execute o script de scaffold:

# Os nomes de plugin são normalizados para letras minúsculas com hífen e devem ter no máximo 64 caracteres.
# O nome da pasta gerada e do plugin.json são sempre os mesmos.
# Execute a partir da raiz da 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 scaffold começa com valores padrão válidos e não deve conter espaços reservados [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, por padrão, ficam em `~/.agents/plugins/marketplace.json`.
python3 scripts/create_basic_plugin.py meu-plugin --with-marketplace

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

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

Use um marketplace de repositório/time apenas quando o usuário solicitar explicitamente 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 está realmente instalado antes de informar o usuário para reinstalá-lo. O arquivo de marketplace pessoal padrão em ~/.agents/plugins/marketplace.json é descoberto implicitamente, mas outros caminhos de marketplace não sã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-json-marketplace> \
  --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 finalizar 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 scaffold 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 solicite explicitamente uma substituição específica. Veja references/installing-and-updating.md para o fluxo esperado de cachebuster e reinstalação ao iterar em um plugin local existente.

O que esta skill cria

• Scaffolds com marketplace padrão 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 schema validada que o caminho de ingestão aceita.
• Cria ou atualiza ~/.agents/plugins/marketplace.json quando --with-marketplace é definido.
  • Se o arquivo do marketplace ainda não existir, cria uma raiz de marketplace pessoal antes de adicionar a primeira entrada de plugin.
• <nome-do-plugin> é normalizado usando as regras de nomenclatura da skill-creator:
  • Meu Plugin → meu-plugin
  • Meu--Plugin → meu-plugin
  • underscores, espaços e pontuação são convertidos em -
  • o resultado é em letras minúsculas separadas por hífen, 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 usa 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/time é opt-in 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 de marketplace padrão personal já estiver ocupado 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 precisando de instalação explícita via codex plugin marketplace add.
• Prefira scripts/read_marketplace_name.py quando precisar do nome do marketplace a partir de qualquer arquivo marketplace.json. Sem argumentos, ele lê o marketplace pessoal padrão; com um caminho explícito, também funciona para marketplaces de repositório/time.
• Em qualquer localização, o caminho de origem gerado permanece ./plugins/<nome-do-plugin>.
• Os metadados raiz do marketplace suportam name de nível superior mais interface.displayName opcional.
• Trate a ordem dos plugins em plugins[] como ordem de renderização no Codex. Anexe novas entradas, a menos que um usuário solicite explicitamente 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:
  • 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 o bloqueio por 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 ao substituir intencionalmente 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, em seguida, adicione a nova entrada.

• Para um arquivo de marketplace totalmente novo, o objeto raiz deve se parecer com:

{
  "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" do 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 espaços reservados [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 do 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 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á ocupado ou instalado em outro lugar.
• Se o Codex precisar de aprovação para escrever o arquivo de marketplace, solicite essa aprovação antes de prosseguir. Se o usuário preferir executar a escrita ele mesmo, forneça o comando de scaffold exato e depois continue com a 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 de marketplace pessoal padrão. 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 está instalado antes de fornecer instruções de reinstalação. Use codex plugin marketplace add <caminho-para-raiz-do-marketplace> quando esse marketplace explícito ainda não foi configurado.
• Quando o fluxo de trabalho criou ou atualizou um plugin com suporte a marketplace, termine a resposta final voltada para o usuário com uma breve transferência para o aplicativo Codex. Diga Para visualizar no aplicativo Codex: e escreva Ver <nome-do-plugin-normalizado> e Compartilhar <nome-do-plugin-normalizado> como links Markdown, não URLs brutas ou spans de código.
• O deep link "Ver" usa codex://plugins/<nome-do-plugin-normalizado>?marketplacePath=<caminho-absoluto-do-marketplace.json>. O deep link "Compartilhar" usa a mesma URL com &mode=share.
• Substitua os espaços reservados pelo nome real do plugin normalizado e pelo caminho absoluto do marketplace.json do plugin estruturado. Codifique o segmento do 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 Ver <nome-do-plugin-normalizado> ou Compartilhar <nome-do-plugin-normalizado> quando nenhuma entrada de marketplace foi criada ou atualizada.

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

Para o JSON canônico exato de amostra para 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 em nova thread após reinstalação

Validação

Após editar SKILL.md, execute:

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

Antes de finalizar um plugin gerado, execute:

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