Run agent skills

This repo is a Bun workspace of Markdown-defined skills/agents/rules plus a handful of Bash hooks and one TypeScript helper. There is no app to "launch" — driving it means running the validation pipeline (bun run validate) and exercising the Claude Code hooks by piping JSON to their stdin. All paths below are relative to the repo root.

Prerequisites

brew install bats-core shellcheck jq
curl -fsSL https://bun.sh/install | bash    # or: brew install oven-sh/bun/bun

Versions confirmed working: bun 1.3.13, bats 1.13.0, shellcheck 0.11.0, jq 1.7.1.

Setup

bun install

Installs markdownlint-cli and yaml into root node_modules/. The workspace members (skills/, agents/, rules/) have empty deps — bun install finishes in ~50ms when already populated.

Run (agent path)

The full validation pipeline — lint markdown, lint shell, run bats, check indexes, check README links:

bun run validate

Each step is also addressable individually (and is what you want when iterating):

command	what it does	exit code
bun run lint	markdownlint on all **/*.md	1 on findings
bun run lint:fix	markdownlint --fix on all **/*.md	1 on un-fixable findings
bun run lint:sh	shellcheck on .claude/hooks/*.sh hooks/*.sh scripts/*.sh skills/symlink-skills/link.sh	1 on findings
bun run test	bats over .claude/hooks/tests/ hooks/tests/ scripts/tests/ skills/symlink-skills/tests/	non-zero on test failure
bun run index:gen	regenerate index.md in each category folder from frontmatter	0
bun run index:check	verify index.md presence for skills/ agents/ rules/ commands/ hooks/ anywhere in the tree	non-zero on missing index
bun run readme:check	verify root README.md links every SKILL.md and lists every agent	non-zero on drift

Current test count: 72 bats tests across the four directories.

Direct invocation — exercising a hook

The hooks read Claude Code's PostToolUse payload from stdin. Drive them with jq-compatible JSON:

# validate-skill-frontmatter: succeeds (exit 0, no output) on a valid SKILL.md
echo '{"tool_input":{"file_path":"'$PWD'/skills/gcm/SKILL.md"}}' \
  | .claude/hooks/validate-skill-frontmatter.sh

# validate-skill-frontmatter: fails (exit 2, blocking) when name/description missing
TMP=$(mktemp -d); printf '%s\n' '---' 'description: x' '---' > "$TMP/SKILL.md"
echo "{\"tool_input\":{\"file_path\":\"$TMP/SKILL.md\"}}" \
  | .claude/hooks/validate-skill-frontmatter.sh; rm -rf "$TMP"

# session-log-reminder: prints reminder on git-commit, silent on anything else
echo '{"tool_input":{"command":"git commit -m test"}}' | hooks/session-log-reminder.sh
echo '{"tool_input":{"command":"ls -la"}}'             | hooks/session-log-reminder.sh

check-index-md.sh and check-readme-sync.sh are also stdin hooks, but the bun scripts wrap them with the right env: prefer bun run index:check and bun run readme:check over invoking them directly.

Install — symlink skills out to loaders

./skills/symlink-skills/link.sh --help            # see all options
./skills/symlink-skills/link.sh --dry-run         # preview into all default targets
./skills/symlink-skills/link.sh --target /tmp/x --dry-run   # preview into one explicit target
./skills/symlink-skills/link.sh                   # write into the 4 defaults
./skills/symlink-skills/link.sh --unlink          # remove only the symlinks this script made

Per-project install of a single skill or agent:

scripts/add.sh --help
scripts/add.sh --link tmux-processes              # from a local clone
scripts/add.sh --link --type agent adr-author

Gotchas

• ~/.claude/skills/ may be read-only on a nix-darwin host. If $HOME/.claude/skills is a symlink into /nix/store/…home-manager-files/.claude/skills (owned root:nixbld, mode dr-xr-xr-x), link.sh cannot write into it. It will print ! <name> (ln failed — target dir not writable?) per skill and exit non-zero (errored=N). Workaround: either remove ~/.claude/skills from your home-manager config, or pass --target to a writable directory and skip the read-only default.
• bun run lint currently fails (MD040) on skills/web-perf/SKILL.md (7 unfenced code blocks). bun run validate therefore stops at the lint step on a fresh clone. bun run lint:fix does not fix MD040 — you need to add a language to each ``` fence by hand.
• bun run index:gen is not idempotent across all files. .opencode/agents/index.md rewrites on every run (the other five indexes are stable). Re-run after edits.
• Indexes are required. bun run index:check enforces index.md in every folder named skills/ agents/ rules/ commands/ hooks/ anywhere in the tree (the repo root is exempt — README.md covers it). Drop a new folder there → must include an index.md.

Troubleshooting

• error: script "lint" exited with code 1 listing MD040 in web-perf: pre-existing repo state, not your change. Either fix skills/web-perf/SKILL.md (add languages to its code fences) or skip past with bun run lint:sh && bun run test && bun run index:check && bun run readme:check.
• link.sh says linked: … but ~/.claude/skills/<name> doesn't exist: read the script's stderr — ln: …: Permission denied means the target is read-only (see nix-darwin gotcha above). The exit code is unreliable here.
• bun install warns about a missing hooks workspace: hooks/ is a publishable directory but not a workspace. If you see this, the root package.json workspaces array was edited — it should be exactly ["skills", "agents", "rules"].
• bats: command not found: brew install bats-core (not bats, which is a different package).

---

Conforms to the Agent Skills specification: https://agentskills.io/specification