Agent Skills Configuration

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/ (skills, agents, rules, CLAUDE.md)
• Generic Agent Skills (e.g. Swival) — reads .agents/ (skills, AGENTS.md)

Skills exist in both locations. The .claude/ versions use Claude-specific primitives (TeamCreate, SendMessage, allowed-tools). The .agents/ versions use platform-agnostic language (subagents, role descriptions) so any compatible CLI can use them.

Install

# Claude Code only
make install-claude

# Generic agents only (e.g. Swival)
make install-agents

# Both
make install

Structure

.claude/                            # Claude Code (primary)
├── CLAUDE.md                       # Global project instructions
├── agents/
│   └── code-improvement-reviewer.md
├── rules/
│   ├── go.md                       # Go conventions (auto-loaded for *.go)
│   └── markdown.md                 # Markdown conventions (auto-loaded for *.md)
└── skills/
    ├── agents-md/
    ├── brevity/
    ├── cleanup/
    ├── code-review/
    ├── commit/
    ├── critique/
    ├── decide/
    ├── delegate/
    ├── find-todo-doc/
    ├── go-api/
    ├── go-testing/
    ├── grepai/
    ├── grill-me/
    ├── grill-with-docs/
    ├── handoff/
    ├── markdown-to-skill/          # Claude-only (not in .agents/)
    ├── next-task/
    ├── refactor/
    ├── research-plan/
    ├── slack-to-todo/
    ├── systematic-debugging/
    ├── tech-docs/
    ├── test-feedback/
    └── today/

.agents/                            # Generic Agent Skills
├── AGENTS.md                       # Shared conventions
└── skills/
    ├── agents-md/
    ├── brevity/
    ├── cleanup/                    # Rewritten: teams → subagents
    ├── code-review/                # Rewritten: teams → subagents
    ├── commit/                     # Minor phrasing tweaks
    ├── critique/
    ├── decide/
    ├── delegate/                   # Rewritten: generic roles
    ├── find-todo-doc/
    ├── go-api/
    ├── go-conventions/             # New: rule → skill
    ├── go-testing/
    ├── grepai/
    ├── grill-me/
    ├── grill-with-docs/
    ├── handoff/
    ├── markdown-conventions/       # New: rule → skill
    ├── next-task/                  # Rewritten: teams → subagents
    ├── refactor/                   # Rewritten: teams → subagents
    ├── research-plan/              # Rewritten: teams → subagents
    ├── slack-to-todo/
    ├── systematic-debugging/
    ├── tech-docs/
    ├── test-feedback/              # Minor phrasing tweaks
    └── today/

Components

Skills

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.

Agents (.claude/agents/)

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 (.claude/rules/)

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.

Project Instructions

• .claude/CLAUDE.md — Claude Code global instructions
• .agents/AGENTS.md — Generic agent global conventions

Skill Reference

Skill	Description
agents-md	Make AGENTS.md canonical; stub CLAUDE.md/GEMINI.md as @-import pointers
brevity	Ultra-compressed communication with 3 intensity levels
cleanup	Audit codebase for AI slop via background subagent
code-review	Multi-dimensional review via parallel subagents
commit	Git commits with intelligent file grouping
critique	Critique a document for logical fallacies
decide	Decision memo with structurer, contrarian, and synthesizer passes
delegate	Spawn a subagent for a task
find-todo-doc	Locate the user's personal "TODO" Google Doc; read-only helper
go-api	Generate a production-ready Go API service
go-conventions	Go coding conventions (.agents/ only)
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 (.agents/ only)
markdown-to-skill	Bulk-convert Markdown to skills (.claude/ only)
next-task	Continue working through a project plan
refactor	Analyze a feature and produce a reimplementation plan
research-plan	Research topics deeply, then create implementation plans
slack-to-todo	Parse a pasted Slack message into the personal "TODO" Google Doc
systematic-debugging	Four-phase debugging with root cause analysis
tech-docs	Write or improve technical documentation via five documentation pillars
test-feedback	Parse test failures and fix them in a background subagent
today	Emoji-rich daily briefing — TODO doc, calendar, starred mail

Differences Between .claude/ and .agents/

Aspect	.claude/	.agents/
Orchestration	TeamCreate, SendMessage, TaskCreate	"Spawn a subagent" with role descriptions
Rules	Auto-loaded by file path glob	Converted to explicit skills
Prompting	AskUserQuestion with options	"Present numbered options and wait"
Frontmatter	user-invocable, argument-hint, allowed-tools	name, description only
markdown-to-skill	Included	Omitted (uses Claude-only features)
code-review dimensions	6 (consistency, Go, data, security, arch, docs)	4 (consistency, data, security, Go)

Workflow

• research-plan → critique → next-task → commit → code-review → cleanup → refactor

Contributing

When adding to this repository:

1. Ensure additions are truly global and applicable across multiple projects
2. Write clear, concise descriptions to ensure accurate interpretation
3. Include examples where helpful
4. Avoid project-specific details or configurations
5. Create both .claude/ and .agents/ versions for new skills — the two SKILL.md files must be byte-identical unless the skill genuinely needs Claude-only or generic-only language; verify with diff
6. Test with Claude to ensure the desired behavior

License

This repository contains personal coding skills and preferences. Feel free to use and adapt these skills for your own projects.

Notes

I have a global gitignore that prevents .claude/ from being committed. So I have to git add -f .claude/ every time I make a change.