Publicação no Marketplace

Fluxo de Trabalho de Publicação no Marketplace

Esta skill documenta como publicar habilidades e agentes no marketplace dotnet-skills do Claude Code.

Estrutura do Repositório

dotnet-skills/
├── .claude-plugin/
│   ├── marketplace.json      # Catálogo do marketplace
│   └── plugin.json           # Metadados do plugin + registro de habilidades/agentes
├── .github/workflows/
│   └── release.yml           # Automação de release
├── skills/
│   ├── akka/                 # Habilidades Akka.NET
│   │   ├── best-practices/SKILL.md
│   │   ├── testing-patterns/SKILL.md
│   │   └── ...
│   ├── aspire/               # Habilidades .NET Aspire
│   ├── csharp/               # Habilidades da linguagem C#
│   ├── testing/              # Habilidades de frameworks de teste
│   └── meta/                 # Meta-habilidades
├── agents/
│   └── *.md                  # Definições de agentes
└── scripts/
    └── validate-marketplace.sh

Adicionando uma Nova Habilidade

Passo 1: Escolher uma Categoria

As habilidades são organizadas por domínio:

Categoria	Finalidade
akka/	Padrões de ator Akka.NET, testes, clusterização
aspire/	Orquestração .NET Aspire, testes, configuração
csharp/	Recursos da linguagem C#, padrões de codificação
testing/	Frameworks de teste (xUnit, Playwright, Testcontainers)
meta/	Meta-habilidades sobre este marketplace

Crie uma nova pasta de categoria se nenhuma se adequar.

Passo 2: Criar a Pasta da Habilidade

Crie uma pasta com SKILL.md dentro:

skills/<categoria>/<nome-da-habilidade>/SKILL.md

Exemplo: skills/akka/cluster-sharding/SKILL.md

Passo 3: Escrever o SKILL.md

---
name: my-new-skill
description: Breve descrição do que esta habilidade faz e quando usá-la.
---

# Minha Nova Habilidade

## Quando Usar Esta Habilidade

Use esta habilidade quando:
- [Listar cenários específicos]

---

## Conteúdo

[Guia abrangente com exemplos, padrões e antipadrões]

Requisitos:

• name deve estar em minúsculas com hifens (ex.: cluster-sharding)
• description deve ter 1-2 frases explicando quando Claude deve usar esta habilidade
• O conteúdo deve ter entre 10 e 40 KB, cobrindo o tópico de forma abrangente
• Incluir exemplos de código concretos com padrões modernos de C#

Passo 4: Registrar no plugin.json

Adicione o caminho da habilidade em .claude-plugin/plugin.json no array skills:

{
  "skills": [
    "./skills/akka/best-practices",
    "./skills/akka/cluster-sharding"  // Adicionar nova habilidade aqui
  ]
}

Passo 5: Validar

Execute o script de validação:

./scripts/validate-marketplace.sh

Passo 6: Commitar Junto

git add skills/akka/cluster-sharding/ .claude-plugin/plugin.json
git commit -m "Adicionar habilidade cluster-sharding para padrões de Cluster Sharding do Akka.NET"

---

Adicionando um Novo Agente

Passo 1: Criar o Arquivo do Agente

Crie um arquivo markdown em /agents/:

---
name: my-agent-name
description: Especialista em [domínio]. Especializado em [áreas específicas]. Use para [cenários].
model: sonnet
color: blue
---

Você é um especialista em [domínio] com profundo conhecimento em [áreas].

**Materiais de Referência:**
- [Documentação e recursos oficiais]

**Áreas Principais de Especialização:**
[Listar áreas de especialização]

**Abordagem de Diagnóstico:**
[Como o agente analisa problemas]

Requisitos:

• name deve estar em minúsculas com hifens
• model deve ser um de: haiku, sonnet, opus
• color é opcional (usado para exibição na interface)

Passo 2: Registrar no plugin.json

Adicione ao array agents:

{
  "agents": [
    "./agents/akka-net-specialist",
    "./agents/my-agent-name"  // Adicionar novo agente aqui
  ]
}

Passo 3: Commitar Junto

git add agents/my-agent-name.md .claude-plugin/plugin.json
git commit -m "Adicionar agente my-agent-name para especialização em [domínio]"

---

Publicando uma Release

Versionamento

Atualize a versão em .claude-plugin/plugin.json:

{
  "version": "1.1.0"
}

Use versionamento semântico (MAJOR.MINOR.PATCH):

• MAJOR: Mudanças que quebram compatibilidade (habilidades renomeadas/removidas)
• MINOR: Novas habilidades ou agentes adicionados
• PATCH: Correções ou melhorias em conteúdo existente

Processo de Release

1. Atualizar versão no plugin.json

2. Validar

   ./scripts/validate-marketplace.sh
   

3. Commistar o incremento de versão

   git add .claude-plugin/plugin.json
   git commit -m "Incrementar versão para 1.1.0"
   

4. Criar e enviar a tag

   git tag v1.1.0
   git push origin master --tags
   

5. GitHub Actions automaticamente:

   • Valida a estrutura do marketplace
   • Cria uma release no GitHub com notas geradas automaticamente

---

Instalação pelo Usuário

Os usuários instalam o plugin completo (todas as habilidades e agentes):

# Adicionar o marketplace (uma vez)
/plugin marketplace add Aaronontheweb/dotnet-skills

# Instalar o plugin (obtém tudo)
/plugin install dotnet-skills

# Atualizar para a versão mais recente
/plugin marketplace update

---

Checklist de Validação

Antes de commitar:

• SKILL.md possui frontmatter YAML válido com name e description
• Pasta da habilidade está sob a categoria apropriada
• Caminho adicionado ao array skills do plugin.json
• Para agentes: model está especificado (haiku/sonnet/opus)
• ./scripts/validate-marketplace.sh passa sem erros

---

Solução de Problemas

Habilidade não aparece após a instalação

• Verifique se o caminho no plugin.json corresponde à estrutura da pasta
• Confirme que o arquivo SKILL.md existe na pasta
• Tente reinstalar: /plugin uninstall dotnet-skills && /plugin install dotnet-skills

Erros de validação

• Garanta que o JSON é válido: jq . .claude-plugin/plugin.json
• Verifique se há vírgulas sobressalentes nos arrays
• Confirme que todas as pastas referenciadas contêm SKILL.md

Release não foi criada

• Certifique-se de que a tag segue o formato semver (v1.0.0)
• Verifique os logs do GitHub Actions em busca de erros
• Confirme que a versão no plugin.json corresponde à tag