Referência

Esquema marketplace.json

O manifesto do marketplace está localizado 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 para o 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 curta 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 de 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 de 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 para o perfil ou site do autor
homepage	Não	URL da documentação
keywords	Não	Palavras-chave de 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 com o esquema do marketplace.json
• Existência de todos os diretórios de plugins referenciados
• Validade do plugin.json em cada plugin
• Formatação correta do frontmatter do SKILL.md nas skills
• Campos obrigatórios de frontmatter nos comandos

Configuração de Equipe

Pré-configurando marketplaces

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

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

Pré-habilitando plugins

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

Dica

Fazer o 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 faltando, adicione-o novamente:

/plugin marketplace add f5-sales-demo/marketplace

Plugin não está sendo ativado

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

Skills não estão sendo acionadas automaticamente

As skills são ativadas com base no campo description no frontmatter do SKILL.md. Se uma skill não estiver sendo ativada 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 solução 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.