Claude Code Starter Kit

A minimal skeleton for building your own agents, skills, hooks, and scripts for Claude Code.

What This Is

Claude Code supports a powerful extension system through your ~/.claude/ directory. This repo gives you the starting structure and examples to build your own toolkit.

Architecture

┌─────────────────────────────────────────────────┐
│  CLAUDE.md (project instructions)               │
├─────────────────────────────────────────────────┤
│  Agents      │ Domain experts (markdown files)  │
│  Skills      │ Workflows/methodologies          │
│  Hooks       │ Event-driven automation          │
│  Scripts     │ Deterministic operations          │
└─────────────────────────────────────────────────┘

Component	What It Does	Format
Agent	A persona with domain knowledge that Claude adopts when handling specific tasks	Markdown + YAML frontmatter
Skill	A reusable workflow/methodology (like a recipe)	SKILL.md in a directory
Hook	Code that runs automatically on Claude Code events	Python script
Script	Deterministic operations (validation, analysis)	Python CLI

How They Connect

1. CLAUDE.md tells Claude Code about your project and links to your components
2. Agents get loaded when Claude needs domain expertise (e.g., "Go engineer" for Go code)
3. Skills get invoked as slash commands or by agents for structured workflows
4. Hooks fire automatically on events (session start, before/after tool use, etc.)
5. Scripts are called by hooks, skills, or agents for mechanical work

Quick Start

1. Clone and personalize

git clone <this-repo> ~/my-toolkit
cd ~/my-toolkit

2. Symlink into Claude Code

# Symlink agents and skills so Claude Code discovers them
ln -sf "$(pwd)/agents" ~/.claude/agents
ln -sf "$(pwd)/skills" ~/.claude/skills

Or copy individual files:

cp agents/example-engineer.md ~/.claude/agents/
cp -r skills/example-skill ~/.claude/skills/

3. Configure hooks

Copy .claude/settings.json into your project's .claude/settings.json:

mkdir -p /path/to/your/project/.claude
cp .claude/settings.json /path/to/your/project/.claude/settings.json

4. Use it

cd /path/to/your/project
claude
# Your agents, skills, and hooks are now active

Directory Structure

claude-code-starter-kit/
├── CLAUDE.md                          # Project instructions (Claude reads this)
├── README.md                          # You are here
├── agents/
│   └── example-engineer.md            # Example agent definition
├── skills/
│   └── example-skill/
│       ├── SKILL.md                   # Skill definition
│       └── references/
│           └── patterns.md            # Reference material loaded on demand
├── hooks/
│   ├── session-start.py               # Runs when a session begins
│   └── post-tool-use.py               # Runs after each tool invocation
├── scripts/
│   └── validate-something.py          # Deterministic validation script
├── .claude/
│   └── settings.json                  # Hook configuration
└── pyproject.toml                     # Python project config (for ruff/linting)

Creating Your Own

New Agent

Create agents/your-domain-engineer.md:

---
name: your-domain-engineer
description: "Brief description of expertise"
routing:
  triggers:
    - keyword1
    - keyword2
  pairs_with:
    - skill-name
  complexity: Simple
  category: domain
allowed-tools:
  - Read
  - Write
  - Bash
  - Edit
---

# Your Domain Engineer

You are an expert in [domain]. When working on [domain] tasks...

## Key Principles

1. ...
2. ...

## Common Patterns

...

New Skill

Create skills/your-skill/SKILL.md:

---
name: your-skill
description: "What workflow this skill provides"
allowed-tools:
  - Read
  - Bash
---

# Your Skill Name

## When to Use

...

## Steps

1. PHASE 1: ...
2. PHASE 2: ...
3. PHASE 3: ...

New Hook

Create hooks/your-hook.py and register in .claude/settings.json.

See the examples in this repo for the full pattern.

Hook Events

Event	When It Fires	Common Uses
SessionStart	Session begins	Load context, set up environment
UserPromptSubmit	Before processing a prompt	Inject context, detect patterns
PostToolUse	After a tool runs	Learn from errors, suggest next steps
PreCompact	Before context compression	Save important state
Stop	Session ends	Cleanup, summarize

Design Principles

1. Load only what you need — Context is expensive. Load references on demand.
2. LLMs orchestrate, programs execute — Use scripts for deterministic work.
3. Agents carry knowledge, skills carry methodology — Keep them separate.
4. Hooks automate, they don't block — Keep hooks fast (< 3s timeout).

License

MIT