agents-md

Production-ready configuration files for AI coding agents — instructions, commands, rules, skills, agents, and execution plans.

Quick Start

1. Fork this repo and customize for your team
2. Copy templates/CLAUDE.md.template to your project root as CLAUDE.md
3. Copy templates/settings.json.template to .claude/settings.json
4. Add commands for your daily workflows (commit, review, deploy)
5. Add rules as your CLAUDE.md grows beyond ~100 lines

Repository Layout

.claude/
├── settings.json              # Permissions: what agents can and can't do
├── commands/                  # Slash commands (/project:commit, /project:review, etc.)
├── rules/                     # Auto-loaded instruction modules
├── skills/                    # Complex multi-file workflows
└── agents/                    # Specialized subagent personas

templates/                     # Blank starter configs to copy into your projects
examples/                      # Realistic example configs (Python API, TypeScript app)

CLAUDE.md                      # Repo-level agent instructions
PLANS.md                       # Execution plan for this repo (working example)
CLAUDE.local.md.example        # Example personal overrides

Concepts

CLAUDE.md — The Entry Point

The most important file. Agents read it first and follow it for the entire session. Keep it under 200 lines. Include: build/test/lint commands, architecture overview, coding conventions, and gotchas.

Create CLAUDE.local.md (gitignored) for personal preferences that shouldn't be shared with the team.

Commands — Custom Slash Commands

Each .md file in .claude/commands/ becomes a /project:filename command. Commands support:

• $ARGUMENTS — text passed after the command name
• !`shell command` — embeds shell output into the prompt

Example: /project:fix-issue 234 fetches issue #234 and guides the agent through investigating and fixing it.

Rules — Modular Instructions

.md files in .claude/rules/ auto-load alongside CLAUDE.md every session. Use them to split large instruction sets by concern (code style, testing, security). Add path-scoped frontmatter to restrict rules to specific files:

---
paths:
  - "src/api/**/*.ts"
  - "src/handlers/**/*.ts"
---

Skills — Complex Workflows

Skills live in subdirectories under .claude/skills/ with a SKILL.md and optional supporting files. Unlike commands, skills can be auto-invoked when a task matches their description. Use @filename to reference bundled docs.

Skills are folders, not just markdown files. A well-structured skill uses:

• scripts/ — Shell scripts Claude can run (complexity checks, linting, data fetching)
• references/ — Detailed docs Claude reads when needed (progressive disclosure)
• config.json — User preferences stored on first setup
• On-demand hooks: in frontmatter — situational guardrails active only while the skill runs

See templates/skill-template/ for an annotated starter, or .claude/skills/code-quality/ for a full example with scripts, config, references, and hooks.

Agents — Subagent Personas

.md files in .claude/agents/ define specialized personas with restricted tool access and model preferences. Agents are spawned in isolated contexts — useful for focused tasks like code review (read-only) or research.

---
name: reviewer
description: Evaluates code quality and correctness
model: sonnet
tools: Read, Glob, Grep
---

Execution Plans (PLANS.md)

Structured planning documents for multi-step autonomous work, adapted from the ExecPlan pattern. Each plan is self-contained — any agent can pick it up and continue.

Key sections:

• Purpose — what and why
• Context Files — what to read before starting
• Progress — timestamped checklist
• Concrete Steps — actions, verification criteria, and commit checkpoints
• Decision Log — rationale for course changes
• Recovery — what to do when things go wrong

See templates/PLANS.md.template for the blank template, or PLANS.md in this repo for a working example.

Types of Skills to Build

Not sure what skills your team needs? These categories cover the most common use cases:

Category	What it does	Example skill names
Library & API Reference	Explains how to use an internal library or SDK, including gotchas	billing-lib, internal-cli
Product Verification	Tests that your code works end-to-end (often with Playwright, tmux)	signup-flow-driver, checkout-verifier
Data Fetching & Analysis	Connects to data/monitoring stacks with credentials and query patterns	funnel-query, grafana-dashboard
Business Process	Automates repetitive workflows into one command	standup-post, weekly-recap
Code Scaffolding	Generates framework boilerplate with your conventions baked in	new-service, new-migration
Code Quality & Review	Enforces quality standards beyond what linters catch	adversarial-review, code-style
CI/CD & Deployment	Fetches, pushes, and deploys code with guardrails	babysit-pr, deploy-service
Runbooks	Takes a symptom and walks through investigation to structured report	oncall-runner, log-correlator
Infrastructure Ops	Routine maintenance with guardrails for destructive actions	orphan-cleanup, cost-investigation

Distributing Skills

Two ways to share skills with your team:

1. Check into your repo (.claude/skills/) — Simple, versioned with your code. Best for small teams and repo-specific skills. Each checked-in skill adds to the agent's context.
2. Publish as a plugin — For skills used across many repos. Lets each engineer install only what they need. Better for scale.

Start by checking skills into your repo. Move to plugins when the skill count grows or you need cross-repo distribution.

Templates

Template	Purpose
templates/CLAUDE.md.template	Annotated starter with sections for commands, architecture, conventions
templates/settings.json.template	Common permission patterns for Node, Python, and Go projects
templates/PLANS.md.template	Blank execution plan template
templates/skill-template/	Annotated skill starter with all frontmatter fields and recommended sections

Examples

Example	Stack
examples/python-api/	FastAPI, SQLAlchemy, pytest, ruff, mypy
examples/typescript-app/	Next.js 14, Prisma, Vitest, ESLint, Tailwind

Each example includes a CLAUDE.md and .claude/settings.json ready to use.

Philosophy

• Concise and imperative — tell the agent what to do, not what you'd like
• Scope matters — repo-level rules in CLAUDE.md, task-specific rules in skills
• Less is more — over-constraining agents makes them worse, not better
• Show, don't tell — examples beat descriptions
• Progressive complexity — start with CLAUDE.md, add layers as needed

Two .claude Directories

There are two .claude locations:

Location	Scope	Committed?
your-project/.claude/	Team config for one project	Yes
~/.claude/	Your personal config across all projects	No

Global ~/.claude/ supports the same structure: CLAUDE.md, commands/, skills/, agents/, and settings.json. Personal commands show up as /user:name instead of /project:name.