agent-skills

Personal, git-managed Agent Skills for Claude Code (and optionally Codex).

Each skill lives at skills/<name>/SKILL.md in this repo and is per-folder symlinked into every Claude skills dir, so editing a skill here takes effect immediately — no copy step. The same SKILL.md format works for Codex.

Skills

Skill	What it does
cross-repo-context	Work across sibling repos (../other-repo) as if they were a monorepo
desktop-organizer	Sort loose screenshots/PDFs into themed, dated folders
friction-log	Maintain a personal friction log in an Obsidian vault
illustrate-with-html	Explain/visualize anything as a single self-contained .html file
pr-review	Verification-based PR review: every finding backed by a concrete check, verdicts over candidates
pr-visual-review	PR review with sequence/class/flow diagrams (only when structurally warranted)
repo-deepwiki	Generate a DeepWiki-style, citation-heavy architecture wiki for a repo

Sources and targets

make install links from two sources into every Claude config dir:

• This repo's skills/ — all of them.
• A curated subset of anthropics/skills (default: mcp-builder, skill-creator), linked from a local clone of that repo rather than copied, so the clone stays the upstream-tracking source of truth. Set UPSTREAM_REPO to wherever your clone lives; if it isn't cloned, the step is silently skipped and make install still works.

Targets default to one skills dir per Claude Code identity (~/.claude/skills and ~/.claude-work/skills); install, uninstall, and status run against every dir in CLAUDE_SKILLS_DIRS.

Layout

skills/<name>/SKILL.md   # one folder per skill (+ any assets the skill needs)
templates/SKILL.md       # frontmatter scaffold used by `make new`
scripts/link.sh          # install | uninstall | status | unmanaged  (see script header)
scripts/new.sh           # scaffold a new skill folder
Makefile                 # the entrypoint (see below)
wiki.md                  # architecture wiki for this repo (generated by repo-deepwiki)

For a deeper architecture walkthrough — how the Makefile, link.sh, and the skills dirs fit together — see wiki.md, generated by this repo's own repo-deepwiki skill.

Usage

make install      # symlink all skills (repo + upstream subset) into every Claude skills dir
make status       # link state per skill (ok / missing / wrong / blocked) + unmanaged entries
make uninstall    # remove ONLY the symlinks that point back into the source repos
make new name=my-skill   # scaffold skills/my-skill/SKILL.md from the template

Codex is opt-in (this repo's own skills only, separate target):

make install-codex / status-codex / uninstall-codex   # ~/.codex/skills

Everything is overridable for testing or other setups:

CLAUDE_SKILLS_DIRS="/tmp/a /tmp/b" make install
UPSTREAM_REPO=/tmp/up UPSTREAM_SKILLS="foo bar" make install
CODEX_SKILLS_DIR=/tmp/t make install-codex

Safety guarantees (scripts/link.sh)

• Per-folder symlinks only — never a single top-level symlink.
• Never clobbers an existing non-symlink (or a foreign symlink) in the target dir — it warns and skips.
• Idempotent — re-running install is a no-op (ok) for correct links, and repoints (fixed) stale links that already point into the source repo.
• uninstall removes only symlinks pointing into the given source repo.
• A missing source repo (e.g. the upstream mirror) is a warn-and-skip no-op, so optional sources don't break make install on other machines.
• status also lists unmanaged entries: anything in a target dir that no configured source owns (tool-installed skills such as those in ~/.agents/skills, hand-made local skill dirs, foreign symlinks), and flags owned links as dangling when their skill no longer exists in the source. Report-only; nothing is modified.

Adding a skill

make new name=foo
$EDITOR skills/foo/SKILL.md     # fill in the description + body
make install                    # link it live
git add skills/foo && git commit -m "feat(foo): add foo skill"

To pull in another upstream skill, add its name to UPSTREAM_SKILLS in the Makefile and re-run make install.

License

MIT — use these skills in your projects, teams, and tools.