Publish Skill - Claude Code Skill

Publishing a Claude Code skill involves a dozen error-prone steps — repo structure, README, screenshots, marketplace submission, and client data scanning. This skill handles the full workflow so you only have to do each mistake once.

How It Works

Step 0: Client Data Audit     → Scan for company names, amounts, field names in
                                SKILL.md, README, screenshots, git history

Step 1: Repo Structure         → .claude-plugin packaging, skills/ directory, LICENSE
                                (MIT — with independent rationale, not self-referential)

Step 2: Write README           → 16-section template: screenshots, installation, limitations,
                                version history. Pitfalls in strategic-then-implementation order

Step 3: Hook Bundling          → If the skill benefits from auto-triggering, include
                                hooks/ directory with ready-to-use scripts + settings.json snippet

Step 4: Demo Screenshots       → Puppeteer-generated. For rich output, capture 2–4 focused
                                sections (not one massive hero image)

Step 5: Verify Claims          → Parallel research agents check thresholds and citations

Step 6: Review Panel           → Multi-agent adversarial review of the README

Step 7: GitHub Setup           → Create repo, set topics (or suggest in PR if contributing
                                via fork — API requires owner access)

Step 8: Awesome Lists          → (Optional) Submit PRs with correct formatting per list

When to Use

A skill is ready to share publicly
You say "publish this skill", "put this on GitHub", or "share this skill"
You want to submit a skill to awesome-claude-skills marketplaces
You need to update an already-published skill's GitHub presence
"Submit to awesome-claude-skills" / "add my skill to the awesome list"
"How do I let others install my skill?" / "I finished my skill, now what?"
"Push my skill to a public repo" / "generate a README and publish"
"Bump the version and republish" / "turn my local skill into a polished repo"

Hard-Won Lessons Encoded

These rules were learned from real incidents during publishing:

Lesson	What Happened
No "Test plan" in PR body	3 of 4 awesome-list PRs had unnecessary test plan sections — inappropriate for doc-only PRs
Never multi-PR from same fork	Two PRs to the same upstream from one fork — second push auto-closed the first
Always add links in Origin	Bare paper references without URLs look incomplete — always add arxiv/DOI/GitHub links
Interactive skills need process examples	Example Output showing a static taxonomy dump contradicts the claim that the skill is an "interactive diagnostic"
Check list format before submitting	Each awesome-list has its own table/list format — match it exactly
GitHub can't delete PRs	Only repo admins can delete PRs — be careful with what you open
Fork contributors can't set topics	`gh repo edit --add-topic` requires admin access — suggest topics in PR description instead
Multi-section screenshots beat single hero	For rich output skills, 2–4 focused section screenshots show variety better than one long image
Don't cite your own skill as authority	"MIT because publish-skill says so" is circular — justify recommendations with independent reasoning
Update SKILL.md FIRST, metadata second	Updated eval-suite, README, plugin.json, and marketplace.json to v1.5 — but forgot to add a version field to SKILL.md itself. The skill content is the primary artifact; metadata files follow it, not the other way around

Example: What the Skill Produces

When you say "publish this skill", the skill walks through each phase:

Phase 1: Pre-Flight — checks skill readiness

I've read the skill. A few things before we publish:

Version: 2.0.0 (update, not new)

The skill has an interactive 4-phase process — good, this isn't a static doc

No sensitive content detected

The GitHub repo wan-huiyan/ai-trust-evaluation already exists with v1.0

Ready to update the repo with v2.0?

Phase 3: README — writes a structured README with links

publish-skill

Popularity

What's Inside

README

Publish Skill - Claude Code Skill

How It Works

When to Use

Hard-Won Lessons Encoded

Example: What the Skill Produces

Confidence

Similar Plugins

caveman

frontend-design

ui-design

claude-mem

More by wan-huiyan

roundtable

agent-traffic-control

skill-anonymizer

skill-portfolio-existence-review

skill-sync