agent-skills

🗒️ For cursor rules see usrrname/cursorrules

Local registry of agent skills, sub-agents, rules, and hooks. Works across Claude Code, opencode, and Cursor.

Each skill is a directory with a SKILL.md (YAML frontmatter: name, description, optional model, allowed-tools, etc.). Agents are single .md files under agents/ in Claude sub-agent format.

Layout

agent-skills/                    # bun workspace root (@usrrname/agent-skills)
├── package.json                 # workspaces: [skills]
├── bun.lock
├── README.md                    # this file
├── AGENTS.md                    # guidance for agents editing this repo
├── skills.sh.json               # skills.sh registry manifest (skills only)
├── skills/                      # cross-loader skills (each dir has SKILL.md) — the publishable surface
│   ├── package.json
│   ├── index.md
│   └── <skill>/SKILL.md
├── agents/                      # Claude sub-agent definitions
│   ├── index.md
│   └── <agent>.md
├── rules/                       # repo-wide rule documents (TypeScript, React, Vue3, etc.)
│   ├── index.md
│   └── <rule>/<rule>.md
├── hooks/                       # publishable Claude Code hooks + bats tests
│   ├── index.md
│   ├── *.sh
│   └── tests/*.bats
├── scripts/
│   ├── add.sh                   # fetch one skill/agent (auto-detects loader)
│   ├── generate-index.ts        # regenerates category index.md files
│   └── tests/*.bats
└── .claude/                     # project-internal Claude Code config
    ├── settings.json
    ├── hooks/                   # validation hooks + bats tests
    ├── rules/                   # rule docs for editors
    └── skills/                  # project-internal skills (run-*, etc.)

Only skills/ is published. Everything else (agents/, rules/, hooks/, scripts/) ships with the repo but is not part of the publication surface.

Commands

bun install            # install workspace deps (markdownlint-cli, yaml)

bun run lint           # markdownlint on all .md (config: .markdownlint.json)
bun run lint:fix       # markdownlint --fix
bun run lint:sh        # shellcheck on all .sh files
bun run test           # bats on all test dirs

bun run index:gen      # regenerate every category index.md from frontmatter
bun run index:check    # verify index.md presence per category
bun run readme:check   # verify README.md links every SKILL.md

bun run validate       # all of the above, in order

Installing into projects

Two scripts move skills and agents to where loaders look for them.

scripts/add.sh — per-project install

Fetch one skill or agent into the current project. Auto-detects the loader (Claude Code, opencode, Cursor) based on project structure:

# From any project directory (no local clone needed):
curl -fsSL https://raw.githubusercontent.com/usrrname/agent-skills/main/scripts/add.sh | bash -s -- tmux-processes

# With a local clone:
~/agent-skills/scripts/add.sh --link tmux-processes

# Add an agent:
~/agent-skills/scripts/add.sh --link --type agent adr-author

# Explicit loader:
~/agent-skills/scripts/add.sh --loader opencode --link web-perf

Destination directories by loader:

• claude: .claude/skills/<name>/ or .claude/agents/<name>.md
• cursor: .cursor/skills/<name>/ (skills only)

skills/symlink-skills/link.sh — global install

Bulk-install all skills via symlinks into ~/.claude/skills/, ~/.agents/skills/, and ~/.cursor/skills/:

./skills/symlink-skills/link.sh          # install all
./skills/symlink-skills/link.sh --unlink # remove all
./skills/symlink-skills/link.sh --dry-run

Index

Skills

Skill	Description
clean-caches	Reclaim disk space by cleaning macOS dev caches (Docker/OrbStack, package managers, Xcode, Homebrew, kilter, browser caches). Tiered by risk — safe ops run by default, destructive ops require confirmation.
changelog	Generate a changelog by analyzing git history and tags.
depcheck	Check projects and packages for CVEs using Socket.dev CLI and native audit commands.
gcm	Generate a conventional commit message from staged or unstaged changes.
handoff	Compact the current conversation into a handoff document for another agent to pick up.
intent	Draft and clarify intent and scope of a change before implementation.
issue-plan-commit	Reads from an existing issue, interprets expected outcomes, plans before making changes.
prune-memory	Audit the project's ~/.claude/projects/<encoded-cwd>/memory/ store and prune memories that no longer match the current project state — dead references, past-dated entries, orphaned index pointers, duplicates. Suggest-only with per-item confirmation.
refactor	Refactor existing code by identifying language and applying best practices.
refactor-skills	Tighten markdown / template / skill files touched in the current session for agent performance, without changing behaviour.
symlink-skills	Symlink every skill in this repo into ~/.claude/skills/, ~/.agents/skills/, ~/.cursor/skills/, and ~/.opencode/skills/ so they become globally discoverable.
tmux	Run long-running processes in named tmux sessions so they survive across Claude sessions.
web-perf	Web performance audits via Chrome DevTools MCP.

Agents

Agent	Description
adr-author	Creates and manages Architecture Decision Records (ADRs) with a decision framework for when to create one.
gherkin-spec-writer	Writes Gherkin-style behavioral specifications from refined issues, plans, or bug reports.
pr-review	Review PRs from URLs with structured issue and code analysis.
structured-extractor	Parses unstructured text into a typed JSON or YAML schema.
teaching-assistant	Teaching aid and thinking partner — explanation, guidance, and feedback rather than solutions.

Rules

Repo-wide rule documents — language/framework standards loaded by Cursor (via paths:) and referenced by agents.

Rule	Description
react-typescript	React 18+ with TypeScript — functional components, typed props/state, hooks rules, Suspense, Error Boundaries, state-management choices.
typescript-standards	TypeScript type-safety conventions — strict mode, explicit types, avoid any, utility types, naming, JSDoc, typed errors.
vue3-typescript	Vue 3 + TypeScript — <script setup lang="ts">, typed props/emits/slots/models, composables, watchers, provide/inject, performance patterns.

Hooks

Publishable Claude Code hooks (project-internal validation hooks live under .claude/hooks/ instead).

Hook	Trigger	Description
session-log-reminder	PostToolUse on Bash	Reminds the agent to update docs/session-logs/<YYYY-MM-DD>*.md after each git commit.

opencode skills

Per-project skill set under .opencode/skills/ — loaded by opencode when running in this repo.

Skill	Description
agent-communication	Concise, technically-precise response style with kawaii flourishes.

Project-internal Claude skills

Loaded automatically by Claude Code when working inside this repo. Not packaged for other loaders.

Skill	Description
run-agent-skills	Build, validate, and exercise the agent-skills registry — bun install, bun run validate, exercise hooks via stdin JSON, symlink skills out via link.sh.