Referência

Esquema marketplace.json

O manifesto do marketplace fica em .claude-plugin/marketplace.json na raiz do repositório.

Campos de nível superior

Campo	Obrigatório	Descrição
$schema	Não	URL do JSON Schema para validação
name	Sim	Identificador único do marketplace
version	Não	Versão do esquema do marketplace (semver)
metadata.description	Sim	Descrição legível do marketplace
owner.name	Sim	Organização ou usuário proprietário do marketplace
owner.url	Não	URL do perfil ou site do proprietário
owner.email	Não	E-mail de contato
plugins	Sim	Array de entradas de plugins

Campos de entrada de plugin

Campo	Obrigatório	Descrição
name	Sim	Identificador do plugin (deve corresponder ao plugin.json)
description	Sim	Descrição resumida do plugin
version	Sim	String de versão semântica
author.name	Sim	Autor do plugin
source	Sim	Caminho ou URL para o plugin (consulte Tipos de Fonte)
category	Sim	Categoria do plugin (ex.: productivity)
homepage	Não	URL para a documentação ou página inicial do plugin
license	Não	Identificador de licença SPDX
keywords	Não	Array de palavras-chave para busca
tags	Não	Array de tags para filtragem
repository	Não	URL do repositório

Tipos de Fonte de Plugin

O campo source no marketplace.json suporta múltiplos formatos:

Tipo	Exemplo	Descrição
Caminho relativo	./plugins/example-plugin	Plugin no mesmo repositório
Atalho GitHub	owner/repo	Plugin na raiz do repositório
GitHub com caminho	owner/repo/path/to/plugin	Plugin em subdiretório
URL Git	https://github.com/owner/repo.git	Repositório Git
Pacote npm	npm:@scope/package	Pacote npm publicado

Esquema plugin.json

Cada plugin possui um manifesto em .claude-plugin/plugin.json dentro do seu diretório.

Campo	Obrigatório	Descrição
name	Sim	Identificador do plugin
description	Sim	O que o plugin faz
version	Sim	Versão semântica
author.name	Sim	Autor do plugin
author.url	Não	URL do perfil ou site do autor
homepage	Não	URL da documentação
keywords	Não	Palavras-chave para busca
license	Não	Identificador de licença SPDX
repository	Não	URL do repositório

Estrutura de Diretório do Plugin

plugins/example-plugin/
  .claude-plugin/
    plugin.json          # Manifesto do plugin (obrigatório)
  skills/
    skill-name/
      SKILL.md           # Definição da skill (obrigatório por skill)
      references/        # Arquivos de dados de referência (opcional)
  commands/
    command-name.md      # Definição de comando (um por comando)
  agents/
    agent-name.md        # Definição de agente (um por agente)
  README.md              # Documentação do plugin (recomendado)

Variáveis de Ambiente

Os plugins podem usar estas variáveis em seus arquivos de skill e comando:

Variável	Descrição
$\{CLAUDE_PLUGIN_ROOT\}	Caminho absoluto para o diretório raiz do plugin

Validação

Valide seus manifestos de marketplace e plugin localmente:

claude plugin validate .

Isso verifica:

• Conformidade do esquema marketplace.json
• Existência de todos os diretórios de plugin referenciados
• Que cada plugin possui um plugin.json válido
• Que as skills possuem frontmatter SKILL.md corretamente formatado
• Que os comandos possuem os campos de frontmatter obrigatórios

Configuração de Equipe

Pré-configurando marketplaces

Adicione ao .claude/settings.json em qualquer repositório:

{
  "extraKnownMarketplaces": [
    "f5-sales-demo/marketplace"
  ]
}

Pré-ativando plugins

{
  "enabledPlugins": [
    "f5xc-docs-tools@f5-sales-demo-marketplace"
  ]
}

Dica

Fazer commit dessas configurações no repositório garante que todos os membros da equipe obtenham a mesma configuração de marketplace e plugin automaticamente.

Solução de Problemas

Marketplace não encontrado

Verifique se o marketplace foi adicionado:

/plugin marketplace list

Se estiver ausente, adicione-o novamente:

/plugin marketplace add f5-sales-demo/marketplace

Plugin não está ativando

• Confirme que o plugin está instalado: /plugin list
• Verifique se a versão do seu Claude Code suporta plugins (v1.0.33+)
• Verifique se as condições de acionamento da skill correspondem ao contexto atual

Skills não acionando automaticamente

As skills são ativadas com base no campo description no frontmatter do SKILL.md. Se uma skill não estiver ativando quando esperado:

• Verifique se a descrição descreve com precisão o contexto de acionamento
• Use o comando diretamente (ex.: /f5xc-docs-tools:review-mdx) como alternativa

Erros de build após revisão

O plugin reporta problemas, mas não os corrige automaticamente. Aplique as correções sugeridas manualmente e, em seguida, execute a revisão novamente para confirmar a resolução.