marketplace-publishing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Marketplace Publishing Workflow

市场发布工作流

This skill documents how to publish skills and agents to the dotnet-skills Claude Code marketplace.

本技能文档说明了如何将技能与Agent发布至dotnet-skills Claude Code市场。

Repository Structure

仓库结构

dotnet-skills/
├── .claude-plugin/
│   ├── marketplace.json      # Marketplace catalog
│   └── plugin.json           # Plugin metadata + skill/agent registry
├── .github/workflows/
│   └── release.yml           # Release automation
├── skills/
│   ├── akka/                 # Akka.NET skills
│   │   ├── best-practices/SKILL.md
│   │   ├── testing-patterns/SKILL.md
│   │   └── ...
│   ├── aspire/               # .NET Aspire skills
│   ├── csharp/               # C# language skills
│   ├── testing/              # Testing framework skills
│   └── meta/                 # Meta skills
├── agents/
│   └── *.md                  # Agent definitions
└── scripts/
    └── validate-marketplace.sh

dotnet-skills/
├── .claude-plugin/
│   ├── marketplace.json      # 市场目录
│   └── plugin.json           # 插件元数据 + 技能/Agent注册表
├── .github/workflows/
│   └── release.yml           # 发布自动化脚本
├── skills/
│   ├── akka/                 # Akka.NET技能
│   │   ├── best-practices/SKILL.md
│   │   ├── testing-patterns/SKILL.md
│   │   └── ...
│   ├── aspire/               # .NET Aspire技能
│   ├── csharp/               # C#语言技能
│   ├── testing/              # 测试框架技能
│   └── meta/                 # 元技能
├── agents/
│   └── *.md                  # Agent定义文件
└── scripts/
    └── validate-marketplace.sh

Adding a New Skill

新增技能

Step 1: Choose a Category

步骤1：选择分类

Skills are organized by domain:

Category	Purpose
`akka/`	Akka.NET actor patterns, testing, clustering
`aspire/`	.NET Aspire orchestration, testing, configuration
`csharp/`	C# language features, coding standards
`testing/`	Testing frameworks (xUnit, Playwright, Testcontainers)
`meta/`	Meta skills about this marketplace

Create a new category folder if none fits.

技能按领域划分：

分类	用途
`akka/`	Akka.NET actor模式、测试、集群相关
`aspire/`	.NET Aspire编排、测试、配置相关
`csharp/`	C#语言特性、编码规范相关
`testing/`	测试框架（xUnit、Playwright、Testcontainers）相关
`meta/`	关于本市场的元技能

如果现有分类都不匹配，可创建新分类文件夹。

Step 2: Create the Skill Folder

步骤2：创建技能文件夹

Create a folder with

SKILL.md

inside:

skills/<category>/<skill-name>/SKILL.md

Example:

skills/akka/cluster-sharding/SKILL.md

创建包含

SKILL.md

的文件夹：

skills/<category>/<skill-name>/SKILL.md

示例：

skills/akka/cluster-sharding/SKILL.md

Step 3: Write the SKILL.md

步骤3：编写SKILL.md

markdown

---
name: my-new-skill
description: Brief description of what this skill does and when to use it.
---

markdown

---
name: my-new-skill
description: 简要说明该技能的功能及适用场景。
---

My New Skill

我的新技能

When to Use This Skill

适用场景

Use this skill when:

[List specific scenarios]

在以下场景使用本技能：

[列出具体场景]

Content

内容

[Comprehensive guide with examples, patterns, and anti-patterns]


**Requirements:**
- `name` must be lowercase with hyphens (e.g., `cluster-sharding`)
- `description` should be 1-2 sentences explaining when Claude should use this skill
- Content should be 10-40KB covering the topic comprehensively
- Include concrete code examples with modern C# patterns

[包含示例、模式与反模式的全面指南]


**要求：**
- `name`必须为小写并使用连字符（例如：`cluster-sharding`）
- `description`需用1-2句话说明Claude应何时使用该技能
- 内容需全面覆盖主题，大小在10-40KB之间
- 包含采用现代C#模式的具体代码示例

Step 4: Register in plugin.json

步骤4：在plugin.json中注册

Add the skill path to

.claude-plugin/plugin.json

in the

skills

array:

json

{
  "skills": [
    "./skills/akka/best-practices",
    "./skills/akka/cluster-sharding"  // Add new skill here
  ]
}

将技能路径添加到

.claude-plugin/plugin.json

的

skills

数组中：

json

{
  "skills": [
    "./skills/akka/best-practices",
    "./skills/akka/cluster-sharding"  // 在此添加新技能
  ]
}

Step 5: Validate

步骤5：验证

Run the validation script:

bash

./scripts/validate-marketplace.sh

运行验证脚本：

bash

./scripts/validate-marketplace.sh

Step 6: Commit Together

步骤6：提交代码

bash

git add skills/akka/cluster-sharding/ .claude-plugin/plugin.json
git commit -m "Add cluster-sharding skill for Akka.NET Cluster Sharding patterns"

bash

git add skills/akka/cluster-sharding/ .claude-plugin/plugin.json
git commit -m "Add cluster-sharding skill for Akka.NET Cluster Sharding patterns"

Adding a New Agent

新增Agent

Step 1: Create the Agent File

步骤1：创建Agent文件

Create a markdown file in

/agents/

markdown

---
name: my-agent-name
description: Expert in [domain]. Specializes in [specific areas]. Use for [scenarios].
model: sonnet
color: blue
---

You are a [domain] specialist with deep expertise in [areas].

**Reference Materials:**
- [Official docs and resources]

**Core Expertise Areas:**
[List expertise areas]

**Diagnostic Approach:**
[How the agent analyzes problems]

Requirements:

```
name
```
must be lowercase with hyphens
```
model
```
must be one of:
```
haiku
```
,
```
sonnet
```
,
```
opus
```
```
color
```
is optional (used for UI display)

在

/agents/

目录下创建markdown文件：

markdown

---
name: my-agent-name
description: [领域]专家，擅长[具体领域]，适用于[场景]。
model: sonnet
color: blue
---

你是一名[领域]专家，在[领域]拥有深厚经验。

**参考资料：**
- [官方文档与资源]

**核心专长领域：**
[列出专长领域]

**诊断方法：**
[Agent分析问题的方式]

要求：

```
name
```
必须为小写并使用连字符
```
model
```
必须是以下选项之一：
```
haiku
```
,
```
sonnet
```
,
```
opus
```
```
color
```
为可选参数（用于UI显示）

Step 2: Register in plugin.json

步骤2：在plugin.json中注册

Add to the

agents

array:

json

{
  "agents": [
    "./agents/akka-net-specialist",
    "./agents/my-agent-name"  // Add new agent here
  ]
}

添加到

agents

数组中：

json

{
  "agents": [
    "./agents/akka-net-specialist",
    "./agents/my-agent-name"  // 在此添加新Agent
  ]
}

Step 3: Commit Together

步骤3：提交代码

bash

git add agents/my-agent-name.md .claude-plugin/plugin.json
git commit -m "Add my-agent-name agent for [domain] expertise"

bash

git add agents/my-agent-name.md .claude-plugin/plugin.json
git commit -m "Add my-agent-name agent for [domain] expertise"

Publishing a Release

发布版本

Versioning

版本控制

Update the version in

.claude-plugin/plugin.json

json

{
  "version": "1.1.0"
}

Use semantic versioning (

MAJOR.MINOR.PATCH

MAJOR: Breaking changes (renamed/removed skills)
MINOR: New skills or agents added
PATCH: Fixes or improvements to existing content

更新

.claude-plugin/plugin.json

中的版本号：

json

{
  "version": "1.1.0"
}

使用语义化版本号（

MAJOR.MINOR.PATCH

）：

MAJOR：破坏性变更（重命名/移除技能）
MINOR：新增技能或Agent
PATCH：修复或改进现有内容

Release Process

发布流程

Update version in plugin.json
Validate
bash
```
./scripts/validate-marketplace.sh
```

Commit version bump

bash

git add .claude-plugin/plugin.json
git commit -m "Bump version to 1.1.0"

Create and push tag

bash

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

GitHub Actions will automatically:
- Validate the marketplace structure
- Create a GitHub release with auto-generated notes

更新plugin.json中的版本号
验证
bash
```
./scripts/validate-marketplace.sh
```

提交版本更新

bash

git add .claude-plugin/plugin.json
git commit -m "Bump version to 1.1.0"

创建并推送标签

bash

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

GitHub Actions将自动执行：
- 验证市场结构
- 创建带有自动生成说明的GitHub版本

User Installation

用户安装

Users install the complete plugin (all skills and agents):

bash

undefined

用户可安装完整插件（包含所有技能与Agent）：

bash

undefined

Add the marketplace (one-time)

添加市场（仅需执行一次）

/plugin marketplace add Aaronontheweb/dotnet-skills

Install the plugin (gets everything)

安装插件（获取所有内容）

/plugin install dotnet-skills

Update to latest version

更新至最新版本

/plugin marketplace update

---

/plugin marketplace update

---

Validation Checklist

验证检查清单

Before committing:

SKILL.md has valid YAML frontmatter with
```
name
```
and
```
description
```
Skill folder is under appropriate category
Path added to
```
plugin.json
```
skills array
For agents:
```
model
```
is specified (haiku/sonnet/opus)
```
./scripts/validate-marketplace.sh
```
passes

提交前请确认：

SKILL.md包含有效的YAML前置元数据，带有
```
name
```
和
```
description
```
技能文件夹位于对应分类下
路径已添加至
```
plugin.json
```
的skills数组
对于Agent：已指定
```
model
```
（haiku/sonnet/opus）
```
./scripts/validate-marketplace.sh
```
执行通过

Troubleshooting

故障排除

Skill not appearing after install

安装后技能未显示

Verify the path in plugin.json matches the folder structure
Check that SKILL.md exists in the folder

Try reinstalling:

/plugin uninstall dotnet-skills && /plugin install dotnet-skills

验证plugin.json中的路径与文件夹结构匹配
检查文件夹中是否存在SKILL.md

尝试重新安装：

/plugin uninstall dotnet-skills && /plugin install dotnet-skills

Validation errors

验证错误

Ensure JSON is valid:
```
jq . .claude-plugin/plugin.json
```
Check for trailing commas in arrays
Verify all referenced folders contain SKILL.md

确保JSON格式有效：
```
jq . .claude-plugin/plugin.json
```
检查数组中是否存在尾随逗号
验证所有引用的文件夹均包含SKILL.md

Release not created

未创建版本

Ensure tag follows semver format (
```
v1.0.0
```
)
Check GitHub Actions logs for errors
Verify plugin.json version matches the tag

确保标签符合语义化版本格式（
```
v1.0.0
```
）
查看GitHub Actions日志排查错误
验证plugin.json版本与标签匹配