Contribuindo com um Plugin

Este guia explica como criar um novo plugin e adicioná-lo ao marketplace f5-sales-demo.

Estrutura do Plugin

Cada plugin reside em seu próprio diretório dentro de plugins/ e segue esta estrutura:

• Directoryplugins/

  • Directoryexample-plugin/

    • Directory.claude-plugin/

      • plugin.json
    • Directoryskills/

      • Directoryexample-skill/

        • SKILL.md
        • Directoryreferences/

          • reference-data.md
    • Directorycommands/

      • example-command.md
    • Directoryagents/

      • example-agent.md
    • README.md

Criando um Plugin

1. Crie o diretório do plugin

   mkdir -p plugins/example-plugin/.claude-plugin
   mkdir -p plugins/example-plugin/skills
   mkdir -p plugins/example-plugin/commands

2. Escreva o plugin.json

   Crie plugins/example-plugin/.claude-plugin/plugin.json:

   {
     "name": "example-plugin",
     "description": "What this plugin does",
     "version": "1.0.0",
     "author": {
       "name": "f5-sales-demo"
     },
     "homepage": "https://github.com/f5-sales-demo/marketplace/tree/main/plugins/example-plugin",
     "keywords": ["relevant", "keywords"],
     "license": "Apache-2.0",
     "repository": "https://github.com/f5-sales-demo/marketplace"
   }

3. Adicione skills

   Crie plugins/example-plugin/skills/example-skill/SKILL.md com frontmatter:

   ---
   name: example-skill
   description: One-line description of what this skill does
   ---
   
   Detailed instructions for Claude when this skill activates.

   Coloque quaisquer dados de referência em um subdiretório references/ junto ao SKILL.md.

4. Adicione commands

   Crie plugins/example-plugin/commands/example-command.md:

   ---
   description: What this command does
   argument_hint: "[optional-args]"
   allowed_tools:
     - Read
     - Glob
     - Grep
   ---
   
   Instructions for Claude when the user invokes this command.

5. Adicione o plugin ao marketplace.json

   Adicione uma entrada ao array plugins em .claude-plugin/marketplace.json:

   {
     "name": "example-plugin",
     "description": "What this plugin does",
     "version": "1.0.0",
     "author": { "name": "f5-sales-demo" },
     "source": "./plugins/example-plugin",
     "category": "productivity",
     "homepage": "https://github.com/f5-sales-demo/marketplace/tree/main/plugins/example-plugin",
     "license": "Apache-2.0",
     "keywords": ["relevant", "keywords"],
     "tags": ["searchable", "tags"],
     "repository": "https://github.com/f5-sales-demo/marketplace"
   }

6. Teste localmente

   Teste seu plugin sem publicá-lo apontando o Claude Code para o diretório local:

   claude --plugin-dir ./plugins/example-plugin

   Verifique se as skills são ativadas no contexto correto e se os commands produzem a saída esperada.

Enviando Seu Plugin

Fluxo de trabalho do repositório

Este repositório adota um fluxo de trabalho de governança rigoroso. Consulte o CONTRIBUTING.md para conhecer o processo completo.

1. Crie uma issue no GitHub descrevendo o novo plugin
2. Crie uma branch de funcionalidade a partir de main
3. Adicione o diretório do seu plugin e atualize o marketplace.json
4. Adicione uma página de documentação em docs/plugins/example-plugin.mdx
5. Abra um PR vinculado à issue com Closes #N
6. Corrija quaisquer falhas de CI e faça o merge após a aprovação das verificações

Boas Práticas

• Mantenha as skills focadas — uma skill deve fazer uma coisa bem
• Use arquivos de referência — coloque grandes conjuntos de dados, schemas e tabelas de consulta em references/ em vez de incluí-los diretamente no SKILL.md
• Defina o escopo de forma inteligente — verifique se há alterações não confirmadas para restringir o conjunto de trabalho sempre que possível
• Agrupe a saída por severidade — utilize os níveis ERROR, WARNING e INFO para que os usuários possam priorizar as correções
• Escreva um README — inclua exemplos de uso e uma descrição do que cada skill e command faz