Skill Ship

Release changed skills in one ordered pass: scan → index → sync → commit. Each phase is a gate. A red gate stops the run and reports; it is never skipped, bypassed, or worked around.

Contract

• Order is fixed. Scan before index, index before sync, sync before commit. A skill that fails the scan must never reach the installed directory or the remote.
• Scripts do the mechanical work. Never hand-edit the README index tables or counts. scripts/gen-readme.py owns them; editing by hand is how the index drifted.
• Sync is one-way and additive. Copy repo → installed. Never delete from the installed directory: it holds archived and third-party skills that are not in this repo.
• Push only when asked. Committing is part of the pass; pushing is a separate, explicit request.

Phase 0 — Preflight

git status --short
git diff --stat

Establish what changed under skills/. If nothing under skills/ or README.md changed, say so and stop — there is nothing to ship.

Resolve the installed skills directory. Default is ~/.claude/skills; on Windows Git Bash that is $HOME/.claude/skills (/c/Users/<name>/.claude/skills). Confirm it exists before Phase 3.

SKILLS_HOME="${SKILLS_HOME:-$HOME/.claude/skills}"
test -d "$SKILLS_HOME" && echo "installed: $SKILLS_HOME" || echo "missing: $SKILLS_HOME"

Phase 1 — Scan

bash scripts/scan-skills.sh skills

On exit 1, read the flagged lines before judging them. Security-aware skill content often trips the scanner; that is a finding to investigate and report, not a reason to lower the threshold or exclude the skill.

skillspector-reports/ is a build artifact. Do not commit it.

Phase 2 — Index

python scripts/gen-readme.py
git diff --stat README.md

The generator keeps each skill in the README section it already lives in and keeps its curated display name and description. It only:

• fills rows whose description is empty or ---,
• removes rows whose skill folder no longer exists (removed:),
• appends new skills under ### Uncategorized (uncategorized:),
• updates the active and archived counts.

Report every removed: and uncategorized: line. An uncategorized skill means a human decision is pending: move its row into the right section by hand (the generator preserves placement on the next run), then run the generator again.

Confirm the result is stable:

python scripts/gen-readme.py --check

Exit 0 is required to continue. The Featured Skills table is hand-written and is never touched by the generator; update it manually only when a featured skill changed behavior.

Phase 3 — Sync

Copy only skills that exist in the repo and differ from their installed copy.

SKILLS_HOME="${SKILLS_HOME:-$HOME/.claude/skills}"
before=$(find "$SKILLS_HOME" -mindepth 1 -maxdepth 1 -type d | wc -l)
for dir in skills/*/; do
  name=$(basename "$dir")
  [ -f "$dir/SKILL.md" ] || continue
  if ! diff -rq --strip-trailing-cr "$dir" "$SKILLS_HOME/$name" >/dev/null 2>&1; then
    mkdir -p "$SKILLS_HOME/$name"
    cp -R "$dir." "$SKILLS_HOME/$name/"
    echo "synced: $name"
  fi
done
after=$(find "$SKILLS_HOME" -mindepth 1 -maxdepth 1 -type d | wc -l)
echo "installed skills: $before -> $after"

Verify, do not assume:

for dir in skills/*/; do
  name=$(basename "$dir")
  diff -rq --strip-trailing-cr "$dir" "$SKILLS_HOME/$name" >/dev/null 2>&1 || echo "MISMATCH: $name"
done

No MISMATCH lines, and after >= before. A drop in the installed count means something deleted a skill — stop and report.

cp -R overwrites changed files but leaves files that were removed from the repo in the installed copy. If a skill's file was deliberately deleted, name the stale installed file and ask before removing it.

Phase 4 — Commit

Hand off to /conventional-commit, which splits the working tree into one commit per concern. Typical concerns in a ship:

The repository's own commit rules and the user's instructions override these examples. Do not push unless the user asked.

Report

Skill ship
  scan     gate: clean (91 skills)
  index    filled 2, removed 0, uncategorized 0 — --check clean
  sync     3 synced, 0 mismatches, installed 146 -> 147
  commit   2 commits (not pushed)

On a stop, the report names the phase that failed, the exact error, and what the user must decide. Phases after the failure are listed as not run, never as passed.

Common Mistakes