Dotnet Marketplace Publishing

Marketplace Publishing Workflow

A step-by-step guide for publishing skills and agents to the dotnet-skills Claude Code marketplace. Covers folder structure, SKILL.md authoring, plugin.json registration, validation, and semantic versioning releases.

Acronyms: YAML (YAML Ain't Markup Language), JSON (JavaScript Object Notation), CLI (Command-Line Interface), CI (Continuous Integration), DI (Dependency Injection).

When to Use This Skill

• Adding a new skill folder and SKILL.md to the dotnet-skills marketplace repository
• Registering a new agent definition in the agents directory and plugin.json registry
• Updating plugin.json to include newly created skill or agent path entries
• Validating marketplace structure before committing changes with the validation script
• Bumping the semantic version in plugin.json and tagging a release for distribution
• Troubleshooting missing skills or validation errors after a marketplace installation
• Choosing the correct category folder for a new skill based on its technology domain
• Reviewing an existing skill submission for completeness and frontmatter correctness

Related Skills

Core Principles

1. Single Source of Truth — Register every skill and agent in plugin.json. Why: the marketplace catalog reads this file to discover available content. Duplicates or orphan entries cause installation failures.
2. Convention Over Configuration — Follow the skills/<category>/<name>/SKILL.md path convention. Why: consistent structure enables automated validation and reduces onboarding friction for contributors.
3. Atomic Commits — Commit the skill folder and plugin.json update together. Why: separate commits leave the registry in an inconsistent state where paths reference missing files.
4. Semantic Versioning — Apply MAJOR.MINOR.PATCH versioning to every release tag. Why: consumers rely on version numbers to decide when to update and whether breaking changes exist.

Values: 基礎と型の追求（規約に従った構造が、自動バリデーションと再利用性を最大化する）, 継続は力（小さなスキルをコツコツ追加し、マーケットプレイスの価値を複利で積み上げる）

Workflow: Publish to Marketplace

Step 1: Choose the Category Folder

Select the appropriate category folder under skills/. Create a new folder if none fits the domain.

# Verify the category exists
ls skills/

# Create a new category if needed
mkdir -p skills/newcategory/

Values: 余白の設計（カテゴリ構造に余白を残し、将来のドメイン拡張を容易にする）

Step 2: Create the Skill Folder and SKILL.md

Create a kebab-case folder containing a single SKILL.md file. Why: the validation script expects exactly this structure.

# Create skill folder
mkdir -p skills/akka/cluster-sharding/

Write the SKILL.md with valid YAML frontmatter:

---
name: cluster-sharding
description: >
  Implement Akka.NET Cluster Sharding for distributed
  entity management. Use when designing sharded actors.
---

Requirements checklist:

Values: 基礎と型の追求（フロントマターの型を守ることで、自動検出と品質検証が機能する）

Step 3: Register the Skill in plugin.json

Add the skill path to the skills array in .claude-plugin/plugin.json. Why: unregistered skills are invisible to the marketplace installer.

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

• ✅ Use relative paths starting with ./skills/
• ✅ Point to the folder, not the SKILL.md file
• ❌ Avoid trailing commas — JSON does not allow them
• ❌ Avoid duplicate entries — each path must be unique

Values: ニュートラルな視点（plugin.json は機械可読な唯一の登録簿であり、曖昧さを排除する）

Step 4: Add an Agent (Optional)

Create an agent markdown file in /agents/ with model and description metadata. Why: agents extend the marketplace with specialized domain expertise.

---
name: akka-net-specialist
description: >
  Expert in Akka.NET actor model patterns.
  Use for actor design and cluster configuration.
model: sonnet
color: blue
---

You are an Akka.NET specialist with deep expertise in actor systems.

Register the agent in plugin.json:

{
  "agents": [
    "./agents/akka-net-specialist"
  ]
}

Values: 成長の複利（エージェントを追加するほど、チーム全体が利用できる専門知識が増幅する）

Step 5: Validate the Marketplace

Run the validation script before committing. Why: CI will reject invalid structure, so catching errors locally saves time.

# Run marketplace validation
./scripts/validate-marketplace.sh

# Check JSON syntax separately
jq . .claude-plugin/plugin.json

Validation checks:

• SKILL.md has valid YAML frontmatter with name and description
• Skill folder is under an appropriate category
• Path in plugin.json matches the actual folder structure
• Agent files specify a valid model value
• No orphan entries (paths pointing to missing folders)

Values: 温故知新（バリデーションスクリプトという「型」を守ることで、過去の失敗パターンを繰り返さない）

Step 6: Commit and Release

Commit the skill and registry update atomically. Why: separate commits risk leaving the marketplace in an inconsistent state.

# Atomic commit — skill + registry together
git add skills/akka/cluster-sharding/ .claude-plugin/plugin.json
git commit -m "feat: add cluster-sharding skill for Akka.NET Cluster Sharding"

# Version bump for release
# Update version in plugin.json first, then:
git add .claude-plugin/plugin.json
git commit -m "chore: bump version to 1.1.0"

# Tag and push
git tag v1.1.0
git push origin master --tags

Semantic versioning rules:

GitHub Actions automatically validates the structure and creates a release with notes.

Values: 継続は力（小さなリリースをコツコツ積み上げることで、マーケットプレイスの信頼性が向上する）

Good Practices

• ✅ Use name in frontmatter that exactly matches the folder name in kebab-case
• ✅ Include "use when" trigger phrase in the skill description for discoverability
• ✅ Commit skill folder and plugin.json changes in a single atomic commit
• ✅ Apply semantic versioning consistently — MINOR for new content, PATCH for fixes
• ✅ Run validate-marketplace.sh locally before pushing to avoid CI failures
• ✅ Use concrete code examples with modern C# patterns in skill content
• ✅ Provide 10–40 KB of comprehensive coverage per skill topic
• ✅ Expand acronyms on first use in skill content (e.g., DI, DTO, CI)

Common Pitfalls

1. Forgetting plugin.json update — Adding a skill folder without registering it. The skill is invisible to installers. Fix: always commit both together.
2. Trailing commas in JSON — JSON does not allow trailing commas in arrays. Fix: use jq . to validate syntax before committing.
3. Name mismatch — Frontmatter name differs from the folder name. Fix: ensure exact kebab-case match between both.
4. Missing SKILL.md — Creating the folder but not the SKILL.md file inside it. Fix: validate with the marketplace script.
5. Split commits — Committing the skill folder and plugin.json separately. Fix: use git add for both, then a single git commit.
6. Wrong model value — Using an unsupported model name in agent metadata. Fix: use only haiku, sonnet, or opus.

Anti-Patterns

❌ Orphan Registry Entry → ✅ Validated Path

// ❌ BAD — path points to non-existent folder
{ "skills": ["./skills/akka/nonexistent-skill"] }
// ✅ GOOD — path matches actual folder structure
{ "skills": ["./skills/akka/cluster-sharding"] }

Why: orphan entries cause silent installation failures. The validation script catches this.

❌ Split Commits → ✅ Atomic Commit

# ❌ BAD — two separate commits leave registry inconsistent
git add skills/akka/cluster-sharding/
git commit -m "Add skill"
git add .claude-plugin/plugin.json
git commit -m "Register skill"

# ✅ GOOD — single atomic commit
git add skills/akka/cluster-sharding/ .claude-plugin/plugin.json
git commit -m "feat: add cluster-sharding skill"

Why: if the first commit is deployed without the second, the registry is broken.

❌ Unversioned Release → ✅ Semantic Version Tag

# ❌ BAD — tag without version bump in plugin.json
git tag latest
# ✅ GOOD — version bump + semver tag
# (after updating version in plugin.json to 1.1.0)
git tag v1.1.0

Why: consumers use semver to decide whether updates contain breaking changes.

Quick Reference

Publishing Decision Table

User Installation Commands

# Add the marketplace (one-time)
/plugin marketplace add Aaronontheweb/dotnet-skills

# Install the plugin (gets all skills and agents)
/plugin install dotnet-skills

# Update to latest version
/plugin marketplace update

Troubleshooting Quick Reference

Resources

• Claude Code Plugin System — Official plugin documentation
• Semantic Versioning 2.0.0 — Versioning specification
• Conventional Commits — Commit message format used in releases
• JSON Specification — JSON syntax reference for plugin.json editing