This repository contains global agent configuration — skills, agents, rules, and project instructions designed to be used across all projects when working with AI coding assistants.
It serves two targets:
- Claude Code — reads
.claude/(CLAUDE.md, agents, rules, and askillssymlink) - Generic Agent Skills (e.g. Swival) — reads
.agents/(skills, AGENTS.md)
Skills have a single source of truth: .agents/skills/. .claude/skills is
a symlink to .agents/skills, so each skill is edited once and both harnesses
see it. Skill content is harness-agnostic — generic language ("prompt the user",
"spawn a subagent"). Any Claude-only guidance (e.g. agent teams) lives in a
clearly-labeled optional "Agent teams (if your harness supports it)" section so
other harnesses can ignore it.
# Generic agents only (e.g. Swival): copies .agents/ to ~/.agents/
make install-agents
# Claude Code (also installs agents as a prerequisite): copies CLAUDE.md, rules,
# agents, and scripts to ~/.claude/, then symlinks ~/.claude/skills →
# ~/.agents/skills
make install-claude
# Everything (install-claude already pulls in install-agents)
make install.claude/ # Claude Code
├── CLAUDE.md # @-import pointer to ~/.agents/AGENTS.md
├── agents/
│ └── code-improvement-reviewer.md
├── rules/
│ ├── go.md # Go conventions (auto-loaded for *.go)
│ └── markdown.md # Markdown conventions (auto-loaded for *.md)
├── scripts/ # Statusline + session-cost helpers
└── skills -> ../.agents/skills # Symlink — single source of truth
.agents/ # Canonical skills + conventions
├── AGENTS.md # Shared conventions
└── skills/
├── agents-md/
├── caveman/
├── changelog/
├── cleanup/
├── code-review/
├── commit/
├── consensus/
├── critique/
├── decide/
├── delegate/
├── go-api/
├── go-conventions/ # rule → skill (generic harnesses)
├── go-testing/
├── grepai/
├── grill-me/
├── grill-with-docs/
├── handoff/
├── markdown-conventions/ # rule → skill (generic harnesses)
├── markdown-to-skill/
├── mysql-index-audit/
├── next-task/
├── redesign/
├── refactor/
├── research/
├── research-plan/
├── slack-search/
├── summarize-for-product/
├── systematic-debugging/
├── teach/
├── tech-docs/
├── test-feedback/
Skills are custom code capabilities
that extend an agent's ability to perform specific tasks, follow particular
patterns, or apply specialized knowledge. Skills act as reusable instructions
invoked with /skill-name.
Custom agents are specialized sub-agents that Claude can spawn via the Task tool. Each agent has a specific purpose and can be configured with different models and instructions.
Current agents:
- code-improvement-reviewer — Reviews code for readability, performance, and best practices with concrete before/after suggestions
Rules
are modular, topic-specific instruction files that Claude loads automatically.
Unlike skills (which are invoked explicitly), rules apply passively — scoped to
file patterns via YAML frontmatter paths globs.
In .agents/, rules are converted to skills (go-conventions,
markdown-conventions) since generic agents don't support path-scoped
auto-loading.
.agents/AGENTS.md— the canonical global conventions.claude/CLAUDE.md— a one-line@~/.agents/AGENTS.mdpointer so Claude Code loads the same conventions
| Skill | Description |
|---|---|
| agents-md | Make AGENTS.md canonical; stub CLAUDE.md/GEMINI.md as @-import pointers |
| caveman | Ultra-compressed caveman-speak mode; ~75% token reduction |
| changelog | Add a Keep a Changelog entry from the working diff or branch-vs-main |
| cleanup | Audit codebase for AI slop via background subagent |
| code-review | Multi-dimensional review via parallel subagents |
| commit | Git commits with intelligent file grouping |
| consensus | Cross-model second-opinion workflow with discussion rounds and user gates |
| critique | Critique a document for logical fallacies |
| decide | Decision memo with structurer, contrarian, and synthesizer passes |
| delegate | Spawn a subagent for a task |
| go-api | Generate a production-ready Go API service |
| go-conventions | Go coding conventions (mirrors .claude/rules/go.md) |
| go-testing | Write Go tests — table-driven, fuzz, benchmarks |
| grepai | Semantic code search by intent |
| grill-me | Interview the user relentlessly to stress-test a plan or design |
| grill-with-docs | Stress-test a plan against project domain model and update CONTEXT/ADRs |
| handoff | Compact the current conversation into a handoff document for another agent |
| markdown-conventions | Markdown formatting conventions (mirrors .claude/rules/markdown.md) |
| markdown-to-skill | Bulk-convert Markdown files into agent skills |
| mysql-index-audit | Statically audit a codebase for MySQL index misuse (leftmost-prefix, gaps, killers) |
| next-task | Continue working through a project plan |
| redesign | Codebase-wide aspirational audit; produces phased redesign plan with mandatory test pinning |
| refactor | Analyze a feature and produce a reimplementation plan |
| research | Research a topic or repo deeply; writes a reference doc to docs/research/ |
| research-plan | Research topics deeply, then create implementation plans (delegates Phase 1 to research) |
| slack-search | Drive Slack via Playwright MCP to run searches or Slackbot prompts |
| summarize-for-product | Translate a plan doc or branch diff into a non-engineer summary (PR/Slack/email) |
| systematic-debugging | Four-phase debugging with root cause analysis |
| teach | Stateful tutor workspace — missions, lessons, learning records, reference docs |
| tech-docs | Write or improve technical documentation via five documentation pillars |
| test-feedback | Parse test failures and fix them in a background subagent |
Skills are no longer duplicated. .agents/skills/ is the single source; the
.claude/skills symlink points at it. The only things unique to .claude/ are
Claude-specific assets that have no generic equivalent:
| Asset | Purpose |
|---|---|
CLAUDE.md |
One-line @~/.agents/AGENTS.md import — same conventions |
rules/ |
Path-glob auto-loaded conventions (generic harnesses use skills) |
agents/ |
Custom sub-agent definitions spawned via the Task tool |
scripts/ |
Statusline and session-cost helpers |
Inside skill bodies, harness-agnostic language is the default. Optional
Claude-only behavior (agent teams, allowed-tools/argument-hint frontmatter)
is additive — other harnesses ignore what they don't understand.
Skill bodies are harness-agnostic, but some YAML frontmatter keys are read only by Claude Code. They're safe to leave in shared skills — other harnesses ignore unknown keys.
| Field | Where | Purpose |
|---|---|---|
user-invocable |
SKILL.md |
Exposes the skill as a /skill-name slash command |
argument-hint |
SKILL.md |
Placeholder text shown after the slash command in the prompt |
allowed-tools |
SKILL.md |
Pre-approves specific tool calls (e.g. Bash(git diff:*)) |
disable-model-invocation |
SKILL.md |
Prevents the model from auto-invoking; user must call it explicitly |
arguments |
SKILL.md |
Structured argument definitions for a slash command |
paths |
rules/*.md |
Glob patterns that auto-load a rule when matching files are touched |
.claude/rules/go.md and .claude/rules/markdown.md are generated from
go-conventions and markdown-conventions skills — the skill SKILL.md is the
single source of truth, and the rule differs only by frontmatter (paths: globs
in place of name:/description:). Bodies stay byte-identical.
Regenerate with make rules (runs .claude/scripts/gen-rules.sh). make install runs it automatically. After editing a *-conventions skill, run make rules before committing, since the generated rules are committed.
- research-plan → critique → next-task → commit → code-review → cleanup → refactor → redesign
When adding to this repository:
- Ensure additions are truly global and applicable across multiple projects
- Write clear, concise descriptions to ensure accurate interpretation
- Include examples where helpful
- Avoid project-specific details or configurations
- Add new skills under
.agents/skills/<name>/only — the.claude/skillssymlink picks them up automatically. Keep content harness-agnostic; put any Claude-only guidance in an optional "Agent teams (if your harness supports it)" section - Test with Claude to ensure the desired behavior
This repository contains personal coding skills and preferences. Feel free to use and adapt these skills for your own projects.