Custom Agent Toolkit

A hands-on learning project that teaches Claude Code custom agent fundamentals by building 6 progressively complex agents — from a minimal "hello world" agent to a multi-agent security review team.

What Are Custom Agents?

Custom agents (subagents) are specialized AI assistants you define as markdown files. Each agent gets its own isolated context window, custom system prompt, and configurable tool access. Claude Code automatically delegates tasks to matching agents, or you can invoke them explicitly.

Agents are defined in .claude/agents/ with YAML frontmatter + a markdown body:

---
name: my-agent
description: What this agent does
model: sonnet
tools: Read Grep Glob
---

You are a specialist in [domain]. When working on tasks...

Learning Roadmap

Each lesson introduces one core concept, with a working agent you can invoke and test.

Lesson	Agent	Concept	Key Frontmatter
01	greeter	File structure, frontmatter basics, invoking agents	name, description
02	code-reader	Least-privilege tool access (read-only agent)	tools
03	quick-summarizer	Model routing for cost control	model
04	vuln-scanner	Structured output via prompt engineering	Output templates
05	security-reviewer	Full-featured agent combining all concepts	model, effort, tools
06	security-lead	Multi-agent coordination and delegation	spawn-agents

Quick Start

1. Clone this repo
2. Open the directory in Claude Code
3. Start with Lesson 1: "Use the greeter agent"
4. Work through each lesson in the guides/ directory

Try the Security Agents

The test-targets/ directory contains intentionally vulnerable code (SQL injection, XSS, hardcoded secrets) for the security agents to scan:

"Use the vuln-scanner to scan test-targets/"
"Use the security-reviewer to audit test-targets/"
"Use the security-lead to assess test-targets/"

Project Structure

.claude/agents/          Working agent definitions (the deliverables)
  greeter.md             Lesson 1 — minimal agent
  code-reader.md         Lesson 2 — read-only tool restrictions
  quick-summarizer.md    Lesson 3 — Haiku model for cost control
  vuln-scanner.md        Lesson 4 — structured vulnerability findings
  security-reviewer.md   Lesson 5 — deep security audit (Opus + high effort)
  security-lead.md       Lesson 6 — coordinates vuln-scanner + security-reviewer

guides/                  Written guides explaining each concept
  01-your-first-agent.md
  02-tool-restrictions.md
  03-model-and-effort.md
  04-structured-output.md
  05-full-featured-agents.md
  06-multi-agent-coordination.md

test-targets/            Intentionally vulnerable code for agents to scan
  sql_injection.py       Flask routes with raw SQL string formatting
  xss_example.js         Express routes reflecting unsanitized user input
  hardcoded_secrets.py   API keys, passwords, and credentials in source

Concepts Covered

• Agent file anatomy — YAML frontmatter + markdown system prompt
• Tool restrictions — Principle of least privilege for AI agents
• Model routing — Using cheaper models (Haiku) for simple tasks, powerful models (Opus) for deep analysis
• Effort tuning — Controlling reasoning depth for cost/quality tradeoffs
• Structured prompting — Role definition, checklists, process steps, output templates
• Multi-agent coordination — Lead/specialist pattern with spawn-agents control
• Security automation — OWASP Top 10 scanning, CWE classification, remediation guidance

Skills Demonstrated

• AI/LLM customization and agent architecture
• Security automation via AI agent prompts
• Multi-agent coordination and delegation patterns
• Prompt engineering for consistent, structured output
• Technical documentation and progressive curriculum design

Prerequisites

• Claude Code CLI, desktop app, or IDE extension
• Basic familiarity with markdown and YAML
• No coding experience required (guides explain everything)

License

Educational project — use freely for learning and reference.