Publishing skills

Publishing Skills

Take a skill that works locally but lives in a cluttered development folder, and derive a separate, curated release repository that a stranger can trust and install in one step.

Core principle

A published skill must satisfy two readers at once:

1. The agent user who skims the README and thinks "I can see how that would be useful."
2. The skill-design expert who inspects the repo and thinks "this is well-structured and well-formed — I trust it because the implementation is clearly documented and tested."

Everything below serves those two judgments. Two rules are absolute:

• Never mutate the source. The messy dev folder stays intact and private. Always work on a copy. The release repo is derived, not moved.
• The release is a curated subset, not a mirror. Ship what a stranger needs to understand, trust, install, and use — nothing of the private development history.

The output is a standalone single-skill plugin repo, provider-agnostic: a plain SKILL.md any agent can read, with Claude Code plugin install as additive sugar.

When to use this (and when not)

This skill is the release/distribution last mile. It assumes the skill already works and is good, and turns it into a clean public repo — it does not author or improve the skill itself.

• Publishing an existing, working skill → use this skill.
• Authoring a new skill from scratch (scaffold, structure, initial packaging) → use a skill-authoring skill (e.g. skill-creator).
• Improving a skill's content, tests, or rules → use a skill-quality skill (e.g. writing-skills).

The packaging here is specifically the GitHub-repo-as-product path — leak-scrubbing, a demo-forward README, discoverability (topics/naming), and provider-agnostic install — not generic bundle/zip packaging.

Workflow

Copy this checklist into your working notes and check items off:

Publish Progress:
- [ ] 1. Understand the source skill (what it is, what it needs at runtime)
- [ ] 2. Classify every file: keep / quality-signal / trim / decide
- [ ] 3. Stage a COPY into the release area (never touch the source)
- [ ] 4. Delocalize + leak-check  <- GATE: must be clean before continuing
- [ ] 5. Add publish dressing (README, LICENSE, .gitignore, CHANGELOG, manifests)
- [ ] 6. Confirm provider-agnostic install paths
- [ ] 7. Produce a visual demo + hero screenshot (UI / artifact skills)
- [ ] 8. Verify: JSON valid, leaks clean, demo renders, quality gate green  <- GATE
- [ ] 9. Wire forward-compat for the program marketplace (Phase 2)
- [ ] 10. git init locally — STOP before any public push (await explicit go-ahead)

All scripts/… and assets/… paths below are relative to this skill's own install directory, not the user's current working directory. Invoke them with that prefix (e.g. bash <skill-dir>/scripts/stage_release.sh …, python3 <skill-dir>/scripts/make_manifests.py …).

1. Understand the source

Read the source SKILL.md and identify the runtime essentials — the files the skill actually needs to do its job (template, renderer, styles, schemas, sub-skills, utility scripts). Distinguish them from development scaffolding. Ask: if a stranger cloned only the essentials, would the skill still work?

2. Classify keep / trim

Sort every file into four buckets. Full taxonomy with examples in references/keep-trim-taxonomy.md. Summary:

Bucket	Action	Examples
Core	Ship	SKILL.md, renderer/template/styles, schemas, referenced sub-skills, utility scripts the skill invokes
Quality signal	Ship	test suite + golden fixtures, accessibility/verification harness, focused examples — these earn the expert's trust
Dev-noise	Trim	iteration snapshots, scratch renders, node_modules, .code-review-graph/, .playwright-mcp/, internal handoffs/planning, raw roadmap with scores
Decide	Ask or judge	dev paper-trail / history.md (provenance vs. noise), internal .planning/ (keep archive/ only?), large media

When in doubt about a "decide" item, surface the choice to the user rather than guessing.

3. Stage a copy

Copy the core + quality-signal files into the release area, excluding dev-noise. Use scripts/stage_release.sh <source-dir> <release-dir> (rsync with sensible excludes). It never writes to the source. Verify the staged tree and total size are lean.

4. Delocalize + leak-check (GATE)

This is the step that most often blocks a safe publish. Run scripts/leak_scan.sh <release-dir> and resolve every hit before continuing. Detail and patterns in references/leak-check.md. Common leak classes:

• Machine-specific absolute paths — /Users/<name>/..., /home/<name>/..., ~/.claude/skills/.... Genericize to relative or install-relative references and document the rule in SKILL.md.
• Private references in prose and examples — employer name, internal tool/command/skill names, real personal data baked into example specs or golden files. Replace with neutral, relatable stand-ins. When you edit an example, update its golden/expected file in the same edit so the shipped tests stay green.
• Placeholder hosts / fake domains in $id, URLs, configs (a *.local host) — point at the real intended repo or a neutral identifier.

Re-run the scan until it reports clean. Do not proceed with any leak outstanding.

5. Add publish dressing

Generate the files a public repo needs (fill-in templates in assets/: README.template.md, plugin.json.template, marketplace.json.template, gitignore.template):

• README.md — demo-forward. Hero image first, then why it exists -> who it's for -> what you get back -> quick start -> how it works -> quality -> license. Lead with the value a stranger sees, not the internals. Skeleton in references/readme-template.md.
• LICENSE — confirm the license (default MIT) and the copyright holder/year.
• .gitignore — OS files, node_modules, scratch/generated output, editor/agent local state.
• CHANGELOG.md — derive a clean 1.0.0 entry from the internal roadmap; drop iteration numbers and review scores, keep capabilities.
• .claude-plugin/plugin.json and .claude-plugin/marketplace.json — run scripts/make_manifests.py or copy the templates. Keep SKILL.md at the repo root (a single-skill plugin needs no skills/ dir). Schemas + install commands in references/plugin-packaging.md.

Identity rule — real in product, generic in teaching. Product files (README.md, LICENSE, both manifests) MUST carry the real owner/author, or install commands and attribution break. Reusable teaching/reference files and assets/*.template stay generic (<owner> / AUTHOR_NAME placeholders). Inject the real identity in one place — scripts/make_manifests.py --owner <handle> --author "<name>" writes both manifests — then mirror that same owner/name into the README install line and the LICENSE. Never hand-edit identity across files one by one.

6. Provider-agnostic install

The skill must be usable as a plain SKILL.md by any agent (Claude Code, Codex, others), not only as a Claude Code plugin. The README quick-start must show: (a) drop the folder into a skills directory for any agent, (b) the Claude Code plugin install, and (c) a no-agent manual path. Never make the plugin the only documented route.

7. Produce a visual demo (UI / artifact skills)

If the skill produces a visual artifact (HTML, a form, a page), the single highest-leverage README element is a self-contained demo + a screenshot of it. Reuse an existing demo artifact if one exists rather than regenerating. For HTML artifacts, scripts/build_standalone.mjs inlines external CSS/JS into one portable file (it auto-detects the <link>/<script src> references in the template, so it works for any HTML skill, not just one layout). Render it over http://localhost (browsers block file:// for many features), screenshot the hero view, and place it at docs/screenshot.png.

Non-visual skills still need a hero. A skill with no visual artifact must not leave the top of the README empty — that is the highest-leverage slot regardless. Lead with a hero substitute that shows value in five seconds:

• a fenced code block of real output (the actual export/artifact the skill produces), or
• a before → after diff (e.g. a messy dev file-tree beside the clean release tree), or
• a short terminal session of the workflow running.

Pick whichever most quickly conveys "this does something I want." This very skill is non-visual and models the before→after-tree substitute in its own README.

8. Verify (GATE)

Before declaring done: validate every JSON file parses, re-run the leak scan (clean), render the demo (no console errors beyond a benign favicon 404), and run the skill's own quality gate (its test/lint harness) — a green suite is the trust signal you advertise in the README. If running the suite is heavy, delegate it to a low-cost subagent and report the result.

9. Forward-compat for the program (Phase 2)

A single published skill is Phase 1. When a second skill is ready, a thin federating marketplace repo references each skill repo by source: github — giving a program-level story and one install surface with zero rework to the already-published repos. Build that marketplace only when skill #2 is actually publishable (not before). Pattern and rationale in references/plugin-packaging.md.

10. Publish gate — STOP before pushing

Publishing is outward-facing and effectively irreversible (a public repo can be forked, cached, indexed within minutes). Do local prep only: git init, stage, optionally an initial commit. Do not run gh repo create, push, or tag a public release without the user's explicit, in-the-moment go-ahead.

Run scripts/publish_preflight.sh <release-dir> [leak-pattern] first: it reports the active gh account (flagging an Enterprise Managed User), checks the release's commit email for a corporate domain, re-runs the leak scan, validates every JSON file, checks git status for stray files, and prints a filled-in push sequence (owner from gh, repo from the dir name) for the user to approve. It never pushes — it stops exactly at the gate.

The full push runbook is in references/publish-to-github.md — hand it to the user and execute on their word. It covers the two identity traps that bite most often (an Enterprise Managed User account that cannot create personal repos; commits stamped with a work email instead of the intended public identity), the pre-push gate recap, the gh repo create -> push -> v1.0.0 tag/release -> topics sequence, and what to do if a leak ships anyway.

Worked example

references/worked-example-intake-form.md walks the full intake-form release: what was core vs. quality-signal vs. trimmed, the exact leaks found (hardcoded ~/.claude/skills paths, an employer reference and internal command names in an example + its golden, a .local schema $id), and the dressing added. Use it as the concrete reference when this abstract workflow needs grounding.

Common mistakes

• Shipping a mirror. A repo full of dev cruft reads as good as its weakest file. Curate — never just copy.
• Leaving the test suite red after scrubbing examples. Editing an example without updating its golden breaks the quality claim. Fix both together.
• Plugin-only framing. Excludes Codex and every non-Claude-Code agent. Keep the plain-SKILL.md path first.
• Building the federating marketplace too early. One plugin in a marketplace is overhead. Wait for skill #2.
• Pushing before the user says go. Local prep only until explicit go-ahead.