github-forge

name	github-forge
description	Use when the user wants to create a new open-source Claude Code skill plugin. Guides through naming, content design, file scaffolding, git init, GitHub repo creation, and marketplace publishing.
version	0.1.0

Skill: Forge a New Open-Source Claude Code Skill on GitHub

You are helping the user forge, publish, and register a complete open-source Claude Code skill project on GitHub. Follow this workflow exactly.

Phase 1 — Understand the Use Case

Ask the user (or extract from their message) the following if not already provided:

1. What problem does this skill solve? (1–2 sentences)
2. When should Claude auto-activate it? (trigger condition)
3. What should Claude do when the skill activates? (behavior/workflow)
4. Any reference material? (conventions, rules, examples to embed)

Do NOT proceed to scaffolding until you understand the use case clearly.

Phase 2 — Propose Names

Propose a project name and skill name following these conventions:

Item	Convention	Example
GitHub repo / project dir	claude-skill-<topic>	claude-skill-naming
Plugin name (in plugin.json)	claude-skill-<topic>	claude-skill-naming
Skill directory	skills/<topic>/	skills/naming/
Skill name (in SKILL.md frontmatter)	<topic>	naming

Confirm the name with the user before proceeding.

Phase 3 — Write the SKILL.md

Write skills/<topic>/SKILL.md content based on the use case.

SKILL.md frontmatter template:

---
name: <topic>
description: <One sentence: "Use when..." describing the trigger condition>
version: 0.1.0
---

The description field is critical — Claude Code uses it to decide when to auto-activate the skill. Make it specific and trigger-focused.

SKILL.md body:

• Start with a one-sentence role statement
• Define a step-by-step workflow (numbered phases)
• Include concrete examples, output formats, or decision rules
• Reference any files in references/ using relative paths

If the user provides reference material (naming conventions, style guides, etc.), save it to skills/<topic>/references/<filename>.md and link from SKILL.md.

Phase 4 — Scaffold the Project

Create the following structure in ~/Projects/atompilot/claude-skill-<topic>/:

claude-skill-<topic>/
├── .claude-plugin/
│   ├── plugin.json        ← plugin manifest
│   └── marketplace.json   ← required for /plugin marketplace add
├── skills/
│   └── <topic>/
│       ├── SKILL.md
│       └── references/    ← optional: reference docs
└── README.md

plugin.json (CRITICAL — common mistakes):

{
  "name": "claude-skill-<topic>",
  "version": "0.1.0",
  "description": "<description>",
  "author": {
    "name": "atompilot",
    "url": "https://github.com/atompilot"
  }
}

IMPORTANT:

• author MUST be an object {"name": "...", "url": "..."} — NOT a string. A string causes a validation error.
• Do NOT include a "skills" field. Skills are auto-discovered from the skills/ directory.

marketplace.json:

{
  "name": "claude-skill-<topic>",
  "owner": {
    "name": "atompilot",
    "url": "https://github.com/atompilot"
  },
  "plugins": [
    {
      "name": "claude-skill-<topic>",
      "source": "./",
      "description": "<description>",
      "version": "0.1.0"
    }
  ]
}

This file is REQUIRED for /plugin marketplace add to work. Without it, you get: Error: Marketplace file not found at .../.claude-plugin/marketplace.json

Phase 5 — Write README.md

Include:

1. One-line description
2. Installation section with the correct commands:

   /plugin marketplace add atompilot/claude-skill-<topic>
   /plugin install claude-skill-<topic>@claude-skill-<topic>
   

   The install command format is <plugin-name>@<marketplace-name>. Both are the same string from plugin.json name field.
3. Usage — 3–5 example prompts that trigger the skill
4. What's inside — directory tree with short annotations

Phase 6 — Git Init and GitHub Publish

cd ~/Projects/atompilot/claude-skill-<topic>
git init
git add .
git commit -m "feat: 初始化 claude-skill-<topic>"
gh repo create atompilot/claude-skill-<topic> --public --push --source=.

Verify the repo is live before proceeding.

Phase 7 — Local Install and Test

# Add marketplace
/plugin marketplace add atompilot/claude-skill-<topic>

# Install plugin
/plugin install claude-skill-<topic>@claude-skill-<topic>

If install fails:

• author: Invalid input: expected object, received string → fix plugin.json, update the marketplace cache at ~/.claude/plugins/marketplaces/claude-skill-<topic>/.claude-plugin/plugin.json
• skills: Invalid input → remove the skills field from plugin.json
• Marketplace file not found → create .claude-plugin/marketplace.json
• After fixing, the marketplace cache also needs updating: edit ~/.claude/plugins/marketplaces/claude-skill-<topic>/.claude-plugin/plugin.json directly, since the cache is a local clone that doesn't auto-update.

Completion Checklist

• SKILL.md written with clear trigger description
• plugin.json — author is object, no skills field
• marketplace.json — exists in .claude-plugin/
• README with correct install commands
• GitHub repo created and pushed
• /plugin marketplace add succeeds
• /plugin install succeeds
• Skill appears in skills list