Skill It

/skill-it — your best skill is trapped in a folder; ship it like a product

A skill in your ~/.claude/skills/ helps you. A shipped skill helps everyone — but shipping means a repo strangers can install, a README that sells the why, manifests three crawlers can parse, and zero traces of your private world left inside. skill-it is that whole pipeline as one command: the recipe that shipped plan-it, build-it, review-it, prompt-it and conclude-it, made repeatable for any skill and any GitHub owner.

Throughout, OWNER is the GitHub user/org you ship under and NAME is the skill's public name.

Step 0 — Intent + the name workshop

1. What's being shipped? An existing local skill (path it), a bundle, or a new skill authored now. If new: write the personal version first, use it once, THEN ship — never publish an untested recipe.
2. Name it for marketing. A candidate must pass: (a) verb-able ("just NAME-it") or a two-word noun with an obvious job; (b) family fit if it joins a naming family (a verb chain sells as a slogan); (c) no collision — check the local skills tree, gh search repos NAME, and what npx skills add OWNER/NAME would look like; (d) the pain can headline without the name explaining itself. Propose 2–3 names with one-line rationales; the user picks. Keep their original working name as a trigger alias in the description.
3. Version: 1.0.0 for the first public release of a mature private skill (the CHANGELOG tells the lineage honestly); 0.x only if genuinely experimental.

Step 1 — Genericize (the two-pass sweep)

The private skill knows its author's world; the public one must not.

1. Replace hardcodes with runtime detection or per-repo config: personal vault paths → "if the user's CLAUDE.md declares one"; project skill names → "detect *deploy* in the project's .claude/skills/"; account/alias tables → derive from env or default; internal examples → generic examples. If the skill needs per-user facts, give it a first-run setup interview persisted in the target repo (a ## NAME — project setup block in CLAUDE.md/AGENTS.md), asked once per repo, never global unless requested.
2. Sweep pass 1 — grep every .md/.json/.py/.html/.svg for: the author's name/handle variants, employer/project names, vault names, account aliases, machine paths (/Users/, /home/), customer names, private registry hosts.
3. Sweep pass 2 — a second net with different vocabulary: internal tool names, IP addresses ([0-9]{1,3}(\.[0-9]{1,3}){3}), hostnames, private repo names, personal folder conventions. Exit criterion: zero hits minus false positives you can name (e.g. a hex color matching a pattern) — and check the LICENSE copyright line matches OWNER.
4. Secrets: grep -rEi "(api[_-]?key|secret|token|password|gho_|sk-)" — placeholders fine; anything real is a stop-ship.

Step 2 — Structure: progressive disclosure + bundling

• Thin core, heavy reference. The always-loaded SKILL.md carries what every invocation needs; large conditional legs go to references/<leg>.md, read on demand — a 19K core + 7K conditional leg beats a 39K monolith the common case pays for.
• Bundle the dependencies you'd otherwise assume. If the skill delegates to a helper the world won't have, ship it in the plugin (skills/<helper>/) — and write graceful degradation for every Claude-Code-only helper: run the phase inline, produce the markdown twin of any HTML artifact, and name what ran inline in the output. Degradation is honest, never silent.
• Deterministic machinery over model-authored output. Anything renderable (reports, pages) ships as script + template + a small JSON manifest the agent authors — token-cheap and un-hallucinatable.

Step 3 — The repo scaffold

NAME/
  SKILL.md                    # root crawler manifest — see below
  README.md                   # marketing (Step 4)
  CHANGELOG.md                # semver, honest narrative per release
  LICENSE                     # MIT, "Copyright (c) <year> OWNER (<owner url>)"
  .gitignore
  .claude-plugin/marketplace.json      # marketplace namespace, $schema, plugins:[…]
  plugins/NAME/
    .claude-plugin/plugin.json         # $schema, name, version, description, author, keywords
    skills/NAME/SKILL.md               # the plugin-installable skill (trigger-style frontmatter)
    skills/NAME/references/*.md        # progressive-disclosure legs
    skills/NAME/<machinery>            # scripts/templates the skill uses
    skills/<helper>/SKILL.md           # bundled dependencies
  assets/NAME-hero.svg        # hand-authored SVG flow diagram (dark bg)
  qa/dryrun-scenarios.md      # spec walkthroughs, LABELED as such — binary per-step checks

Root SKILL.md — what npx skills add installs, often the ONLY file that lands, so it must be self-contained: the full flow inline, conditional legs condensed in. Frontmatter per the crawler union: name, description (>- block, specific, triggers included), version, license, author, author_url, homepage, repository, metadata: {platforms, category}, keywords. Body ends with: Portability/graceful-degradation section → Install (plugin + npx skills add + gh skill install) → Security considerations → author footer.

Version consistency is a release gate: the same version string in root frontmatter, plugin.json, and marketplace.json, asserted mechanically.

Step 4 — The marketing README

The formula, proven across five sibling repos:

1. Centered header — <h1>/NAME</h1>; the <h3> is a pain-first catch phrase, never the family slogan (that lives in the family NOTE + footer). Formula: name the gap between what the user believes and what is true — «"Done" is a claim. Concluded is proven.» Then 2–3 consequence+promise lines, hero SVG linking to #how-it-works, badge row (Quick Start · MIT · Works with Claude Code · Portable 70+ agents · author), anchor nav, and a > [!NOTE] cross-linking sibling/family repos.
2. Narrative — the pain in the user's life, then what the skill does. Short.
3. "Why" table — without vs with, one row per failure mode.
4. The honest claim — say plainly what it does NOT do.
5. Installation — universal-installers > [!TIP] (npx skills add OWNER/NAME -a <agent> + gh skill install OWNER/NAME), then per-agent sections: Claude Code (native, full bundle) · Codex · OpenClaw · Cursor · VS Code + Copilot · Copilot CLI · Kiro (manual fallback) · Others; close with the graceful-degradation > [!NOTE].
6. How it works — ASCII flow diagram + the 2–3 hard-won details worth telling.
7. What's bundled table · Security considerations · Platform compatibility — the standard 18-row table (Claude Code ✅ Native; Cursor · VS Code+Copilot · Copilot CLI · Codex · OpenCode · OpenClaw · Antigravity · Gemini CLI · Pi · Vibe · Hermes · Cline · KIMI · Trae · Nanobot · Kiro · "Windsurf · Zed · Amp · Warp · …50+ more") with the Native-vs-Supported legend.
8. License + centered family footer.

Hero SVG: hand-author it — dark gradient background, the skill's flow left→right, slogan strip at the bottom. It must parse as XML.

Step 5 — Validate before shipping (all must pass)

• JSON manifests parse AND versions match across the three files.
• Root frontmatter parses as YAML (awk the block out, feed a YAML parser).
• The hero SVG parses as XML.
• Smoke-run every bundled script with a tiny fixture; non-zero exit = stop-ship.
• Re-run both genericization sweeps on the final tree.

Step 6 — Ship

git init && git add <explicit paths>     # read the staged list before committing
gh repo create OWNER/NAME --public --source=. --push --description "<pain-first one-liner>"
git branch -m master main && git push -u origin main
gh repo edit OWNER/NAME --default-branch main
gh repo edit OWNER/NAME --add-topic openclaw-skill --add-topic agent-skill \
  --add-topic skill --add-topic skills --add-topic mcp --add-topic claude --add-topic claude-code
git archive --format=zip --prefix=NAME-X.Y.Z/ -o /tmp/NAME-X.Y.Z.zip HEAD
gh release create vX.Y.Z /tmp/NAME-X.Y.Z.zip --title "NAME vX.Y.Z" --notes "…"

Crawlers read the default branch — confirm it is main before claiming done.

Step 7 — Verify + hand off

1. Installability probe — the only same-session VERIFIED you may claim: npx --yes skills@latest add OWNER/NAME --list must print the skill's name and description.
2. Marketplace listings are asynchronous crawls — never claim them in-session; hand off to a publisher flow (e.g. the DevOtts skill-publisher skill) that adapts the repo per registry and writes an honest per-marketplace status report.
3. If a personal variant stays in ~/.claude/skills/, record the relationship (personal = configured superset; public = generic) so future edits touch both.

What NOT to do

• Don't publish an untested recipe — use the personal version first.
• Don't leave personal/project references, or a mismatched LICENSE line: both sweeps are release gates.
• Don't ship a root SKILL.md that depends on files a single-file install won't have; don't let degradation happen silently.
• Don't let three manifests disagree on the version.
• Don't claim a marketplace listing without a positive probe.
• Don't headline the family slogan — the headline sells the pain.
• Don't strip existing authorship credit from any skill you package.

Portability — graceful degradation outside Claude Code

skill-it itself is procedure, not machinery: it runs anywhere a SKILL.md-reading agent runs. Where a step names a tool the host lacks (gh CLI, npx), do the equivalent by hand (create the repo in the web UI, attach the zip to a release) and name the substitution in the final report.

Security considerations

• The genericization sweep is a release gate: two grep passes for personal data plus a secrets pattern scan; any real credential is a stop-ship.
• Local gh keyring auth only — never a token pasted into chat.
• Nothing private is published: the repo ships only files staged by explicit path, and the staged list is read before every commit.

Authored by DevOtts.