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 ```bash 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. ## Install **Claude Code (plugin, recommended):** ``` /plugin marketplace add DevOtts/skill-it /plugin install skill-it@devotts ``` **Any SKILL.md-compatible agent:** ``` npx skills add DevOtts/skill-it -a <agent> # peek first: npx skills add DevOtts/skill-it --list gh skill install DevOtts/skill-it # GitHub CLI alternative ``` **Getting started:** point it at a skill — ``` /skill-it package ~/.claude/skills/my-standup-notes as a public repo under my GitHub ``` You get the name workshop, the genericization sweep with receipts, the full scaffold, mechanical validation, the shipped GitHub repo with a tagged release — and an installability probe as proof. ## 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](https://github.com/DevOtts)._