Skip to content

CLAUDE.md

Latest commit

 

History

History
88 lines (67 loc) · 4.31 KB

CLAUDE.md

File metadata and controls

88 lines (67 loc) · 4.31 KB
Raw

skill-retro

Source repository for the retro Claude Code skill. It is also a plugin marketplace, so other people can install the skill from GitHub — see README.md for the user-facing install instructions, and CONTRIBUTING.md for the development workflow and how a release is cut.

Where the skill lives

Home Who reads it How it updates
plugins/retro/skills/retro/SKILL.md (this repo) everything below, ultimately you edit it — source of truth
~/.claude/skills/retro Claude Code on this Mac symlink to a worktree — flipped by dogfood/restore
GitHub (default branch) anyone who installed the plugin ship pushes it

Unlike skill-tldr, there is no copy uploaded to Daniel's Claude account, so this repo has none of tldr's account-sync machinery — no package, no pre-push hook, no drift check. /retro needs a git repo and a LEARNINGS.md to be useful, which the chat app and mobile don't have. If that ever changes, tldr's scripts/tldr.sh has the pattern to copy.

Two worktrees: prod and dev

/Users/daniel/Dev/skill-retro        main   ← prod, known-good, what's deployed by default
/Users/daniel/Dev/skill-retro-dev    dev    ← the sandbox

~/.claude/skills/retro symlinks to one of them. Never repoint it by hand — use ./scripts/retro.sh {dogfood|restore|status}. Both worktrees are discovered from git worktree list, so no path is hardcoded.

Only new Claude sessions pick up a flip; skills load at session start.

Edit in the dev worktree. Editing prod changes what /retro does immediately, with no commit or confirmation step — a half-finished edit is live the moment it hits disk. That is exactly what the dev worktree exists to prevent.

The two worktrees are two separate Claude Code projects (project state is keyed to the directory path), so nothing carries between them except what is committed.

The commands

./scripts/retro.sh status        which worktree is deployed
./scripts/retro.sh dogfood       deploy the dev worktree
./scripts/retro.sh restore       deploy the prod worktree (known-good)
./scripts/retro.sh ship 0.2.0    release: gate, merge, tag, push, restore

Changing the skill (definition of done)

Do this in the dev worktree:

  1. Edit plugins/retro/skills/retro/SKILL.md.
  2. ./scripts/retro.sh dogfood, open a new session, run /retro on a real session.
  3. Commit on dev.
  4. ./scripts/retro.sh ship 0.2.0 — merges to main, tags, pushes, restores the symlink.

Step 2 is the one worth not skipping. /retro is judgment-heavy — whether it gates hard enough, whether the proposals are worth approving — and that only shows up in a real run on a real session, never in a read-through.

Versioning

Neither manifest sets a version. Claude Code therefore falls back to the git commit SHA, so every commit you push is a new version for installed users — no bump to remember, and no way to silently strand anyone. The X.Y.Z passed to ship becomes a git tag only.

claude plugin validate . warns about the missing version — that warning is expected and intentional. Don't add --strict, which turns it into a failure.

Layout

  • plugins/retro/skills/retro/SKILL.md — the skill: YAML frontmatter + body. Explicit-only (disable-model-invocation: true), so it runs only when invoked as /retro, never auto-triggered. This is the symlink target.
  • plugins/retro/.claude-plugin/plugin.json — plugin manifest (metadata only; the skill is auto-discovered from skills/). Don't point the symlink at plugins/retro/ itself — that directory contains a plugin manifest and would register a second, duplicate retro@skills-dir plugin. Link the inner skills/retro directory.
  • .claude-plugin/marketplace.json — marketplace catalog, named skill-retro after the repo. Note that skill-tldr's marketplace is named deejaymorgan-skills instead; a second marketplace by that name would collide for anyone who installed both, so this one is named after the repo instead.
  • scripts/retro.sh — the control script (see above).
  • README.md — public-facing description and install instructions.
  • CONTRIBUTING.md — the dev/dogfood/release workflow in full.