🤖 Claude Code Agents

Specialised AI workers for Claude Code and similar CLI coding assistants.

A collection of focused, task-specific agents that handle complex workflows autonomously.

1. 🎯 What are Agents?
2. 🔧 Compatibility
3. 📦 Setup
4. 🚀 Usage
   1. Example Workflow
5. ✨ Creating Custom Agents
   1. Best Practices for Agent Design
6. 📄 License

🎯 What are Agents?

Agents are specialised AI workers that handle complex, multi-step tasks autonomously. Each has a specific focus area and toolset—quality assurance pipelines, codebase searches, refactoring operations.

Strategic Model Selection: Configure different models per agent based on complexity. Use Opus for sophisticated orchestration and architecture, Haiku for rapid tasks like linting and formatting. Create cost-effective, multi-tiered workflows where the right model handles the right job.

When you invoke an agent, it:

• Receives your task description
• Works autonomously with its available tools
• Returns a comprehensive report of completed work
• Handles errors and edge cases within its domain

🔧 Compatibility

Designed for Claude Code and CLI coding assistants that support YAML-formatted Markdown agent definitions.

Note: As of the time of writing, the Gemini CLI does not have a similar agent feature.

📦 Setup

1. Fork this repository to your own Git account

2. Clone to ~/.claude/agents:

   git clone https://git.tomfos.tr/tom/claude-code-agents.git ~/.claude/agents
   

   Benefits:

   • Maintain your customised agent collection
   • Sync changes across machines
   • Pull updates or push modifications
   • Share agents with your team

🚀 Usage

Each .md file defines an available agent. YAML frontmatter specifies name, description, tools, and configuration.

Usage in Claude Code:

1. Assistant auto-detects when tasks match an agent's specialisation
2. Explicitly request: "Use the python-ci-readiness agent to check my code"
3. Agent runs autonomously and reports findings

Example Workflow

User: "I've finished implementing the new authentication module. Can you make sure it's ready for CI?"
Assistant: "I'll use the python-ci-readiness agent to run through the complete quality assurance process."
[Agent runs pytest, mypy, ruff check, and ruff format, fixing issues along the way]
[Returns comprehensive report of fixes and remaining tasks]

✨ Creating Custom Agents

To create a new agent, add a Markdown file with YAML frontmatter:

---
name: your-agent-name
description: Brief description and usage examples
tools: Glob, Grep, Read, Edit, MultiEdit, Write, TodoWrite, LS
model: haiku  # or opus for complex tasks
color: blue   # visual identifier in UI
---

# Agent Instructions

Detailed instructions for the agent's behaviour and methodology...

Best Practices for Agent Design

1. Single Responsibility: Each agent should excel at one type of task
2. Clear Triggers: Include examples showing when to use the agent
3. Comprehensive Instructions: Provide detailed steps and error handling
4. Tool Selection: Only include tools the agent actually needs
5. Strategic Model Choice:
   • Haiku: Perfect for fast, deterministic tasks (linting, formatting, simple fixes)
   • Opus: Essential for complex reasoning (architecture decisions, refactoring, debugging)
   • Mixed Workflows: Let Opus orchestrate whilst Haiku handles the grunt work

📄 License

This project is licensed under the Apache License 2.0.