claude-code-setup CLAUDE.md

This repo is my version-controlled configuration for Claude Code and Codex: skills, hook scripts, settings, and the symlink setup that wires them into ~/.claude and ~/.codex. It is bash and markdown only — no application code, build step, or test suite.

• Shell scripts live in scripts/ and setup.sh. Keep scripts with a #!/bin/sh shebang POSIX-compatible (no bashisms).
• After changing skills or scripts, run ./scripts/validate.sh (frontmatter checks) and ./setup.sh --verify (symlink health).
• ~/.claude/settings.json must remain a symlink to this repo's settings.json. Editing it in place can silently replace the symlink with a regular file — after any settings change, confirm the symlink is intact and restore it if not.
• Entries in skills/ are a mix of real directories and symlinks out to ~/.agents/skills and other repos. Edit symlinked skills at their source; never dereference a symlink into a copy.
• Symlinked skills are not committed — their targets are absolute paths on one machine, so committing them hands anyone else a dangling link. They are recorded in SKILLS.md and ignored via skills/.gitignore, both generated. After adding or removing a skill, run ./scripts/gen-skills-manifest.sh; --check verifies they are current without rewriting.
• scripts/skill-doctor.sh runs on every SessionStart (--quiet) and is the safety net for skill wiring. It auto-fixes what cannot be got wrong — relative symlinks rewritten absolute, a stale SKILLS.md regenerated, dangling store links that point at deleted repo skills pruned — and only reports things needing judgment: dangling links in skills/, a repo skill shadowed by an enabled plugin, and ~/.claude/settings.json having stopped being a symlink. Run it with no arguments for the full report. It never repairs the settings symlink; that needs a diff first.
• scripts/skill-manager.sh is the on-demand counterpart to skill-doctor: doctor answers "is the wiring intact," this answers "is the skill set still worth carrying." Subcommands: report (full audit, runs all the checks below), usage [--top N], dupes, check (availability across Claude/Codex/agent dirs), sync, update (pending npx skills updates), prune (removal candidates). It reads ~/.claude/skill-usage.jsonl, which is written by skill-usage-tracker.sh (wired to PostToolUse and UserPromptSubmit in settings.json) — not by this script. Its own log <name> subcommand has no callers and is vestigial. Note that the usage log misses Codex and cloud sessions, so a zero there is not proof a skill is unused.
• Removing a skill installed by npx skills means clearing four things, not one: the skills/ entry, the ~/.agents/skills content copy, the ~/.agents/.skill-lock.json key, and any links in other agent directories (~/.codex, ~/.config/goose, …). The lockfile key matters most — skills update -g iterates keys rather than scanning disk, so a leftover key reinstalls the skill everywhere on the next update. skills remove <name> cannot clear a key whose files are already gone; use jq for those. sync-codex-skills.sh cleans up its own links; the other agent directories need a manual sweep.
• Hook scripts referenced by settings.json run on every session. Test changes to them before committing (they fail silently in the harness).