claude-code-clip — dev notes

One capability with two front doors: /clip <path> in Claude Code and clip <path> in a terminal. Both run the same scripts/clip.

Layout

• SKILL.md — the skill definition (frontmatter + how Claude should drive the script). Installed at ~/.claude/skills/clip/; the directory name clip is what registers the bare /clip, independent of this repo's name.
• scripts/clip — bash front end. Parses modes, absolutises paths, reports what landed on the clipboard.
• scripts/pbwrite.applescript — AppleScript-ObjC back end. Writes file URLs via NSPasteboard. Called only in the default (file) mode; -t / -p go through pbcopy.
• install.sh — local dev install: symlinks this repo → ~/.claude/skills/clip and scripts/clip → ~/.local/bin/clip. Edit the source, it takes effect immediately.
• docs/ — GitHub Pages source (repo Settings → Pages → source /docs). install.sh is the curl … | bash installer (copies files from raw main, no symlinks); .nojekyll so the installer is served byte-for-byte.

Two traps, both already hit

Symlink self-location. scripts/clip is normally invoked through ~/.local/bin/clip, a symlink. dirname "${BASH_SOURCE[0]}" then resolves to the bin directory, so the script can't find pbwrite.applescript sitting next to its real self. The script walks the symlink chain before computing HERE. Don't replace that loop with a bare dirname.

die inside command substitution. abspath calls die, which exit 1s — but inside $( ) that only kills the subshell. The caller must catch the status (p="$(abspath "$a")" || exit 1); otherwise an empty string joins the path array and osascript dies with object cannot be nil. Any new helper that validates input needs the same treatment.

Why NSPasteboard, not Finder

tell app "Finder" to set the clipboard to (POSIX file "…") writes something to the clipboard, but several apps don't recognise it and ⌘V does nothing. NSPasteboard + NSURL fileURLWithPath writes a standard file URL, which pastes reliably. Verify with osascript -e 'clipboard info' — «class furl» means a file reference is on the clipboard, «class utf8» means text.

Standalone skill, not a plugin

No .claude-plugin/ manifest, on purpose. A plugin's command is always namespaced (/clip:clip) and nothing removes the prefix, so the bare /clip only exists for a standalone skill under ~/.claude/skills/. The evidence for that claim was gathered in claude-code-queue — see its CLAUDE.md. Don't add a manifest back.

Conventions

• One concern per commit; the message says why (which failure mode it fixes).
• Touching scripts/clip means re-running the smoke set by hand: all three modes, multi-file, stdin, -s, and a nonexistent path (must exit 1 with one error line, not two).