manage-skills: Instructions file for Claude Code

CLAUDE.md

Guidance for Claude Code working in this repository. Product documentation lives in README.md.

What This Is

manage-skills — one self-contained bash script that hardlinks skill files between projects so every copy shares a single inode. No build step, no dependencies.

• Command surface: ./manage-skills --help
• Tests: bash test/smoke-test.sh
• Syntax: bash -n manage-skills

Editing skills — keep the inode

.claude/skills/manage-skills/SKILL.md is the source of truth that other projects hardlink against. Edit and Write rewrite-and-replace: the path gets a fresh inode, and every other project silently keeps the old content.

Edit hardlinked files with a shell redirect, which truncates in place:

cat > .claude/skills/<skill>/SKILL.md <<'SKILL'
…
SKILL
stat -c '%i %h' .claude/skills/<skill>/SKILL.md   # inode and link count must match the pre-edit values

cp new old is equally safe. sed -i renames on GNU — treat it as unsafe here. Full rules and the repair recipe live in that skill file.

Shell constraints

set -euo pipefail is enforced. These traps follow from it and from the platform floor:

A pipeline inside an assignment aborts the script. x=$(echo "$list" | grep foo | cut -d: -f1) dies when grep matches nothing: pipefail propagates its exit 1 and set -e acts on it. This shipped as a bug — check died in every project that owned a skill of its own, leaving its originals branch unreachable. Match with a case inside a while read loop instead, as cmd_check now does.

pipefail makes a short-circuiting reader lie. read_sources | grep -qxF "$path" reads as a membership test, and is one only for the config's last line. grep -q exits at its first match, the producer dies of SIGPIPE writing the line after it, and pipefail hands the if that 141. self therefore called its own shipped skills unregistered whenever another source followed them, and self install appended a second copy of a line already there — an idempotence test caught neither, because self install appends and the tests never put anything behind it. source_path_registered is the same test written as a while read fed by a process substitution: no pipe, no status to propagate. Every early-stopping consumer has this shape — grep -q, grep -m, head.