Claude Code Agents Guide: How Skills Power Your Subagents

In the previous article, we covered how Skills teach Claude “how to work.” But Skills alone aren’t enough. If you’re manually calling /review-code or /gen-unit-test every time, you’re still the one making decisions.

This article shows you how to create Custom Agents (Subagents) that autonomously decide when to execute tasks, and how to combine them with Skills for maximum effectiveness.

---

1. What Is an Agent?

In Claude Code, an Agent (Subagent) is an autonomous decision-maker for specific domains. Each Agent has its own system prompt, tool permissions, and isolated context window.

Building on our previous analogy:

• Rules = Policy Documents — What’s allowed and forbidden
• Skills = Expertise — Reusable procedures and knowledge
• Agent = Specialist — Autonomously applies Skills to make decisions

Skills vs Agent

Aspect	Skills	Agent
Location	.claude/skills/	.claude/agents/
Invocation	Auto-match or /skill-name	Auto-delegate or @agent-name
Context	Shared with main conversation	Isolated context window
Purpose	Reusable expertise	Independent workflow execution

---

2. Why Agent + Skills Is the Best Practice

This is the approach recommended by Anthropic’s official blog:

“Use them together when you want subagents with specialized expertise. A code-review subagent can use Skills for language-specific best practices, combining the independence of a subagent with the portable expertise of Skills.”

Approach	Pros	Cons
Skills only	Simple	Context pollution, no parallelism
Agent only	Independent execution	Knowledge duplication, hard to maintain
Agent + Skills	Independent execution + Reusable knowledge	✅ Best Practice

---

3. Creating an Agent: /agents

> /agents

1. Select Create new agent
2. Choose Generate with Claude (recommended)
3. Describe the agent’s purpose in detail -> “senior-backend-reviewer”
4. Select Tools (Read-only / Edit / Execution / MCP)
5. Select Model (Sonnet / Opus / Haiku)
6. Choose background color
7. Review preview, press e to add the skills field

---

4. Connecting Skills to Your Agent (Key Step!)

Open the generated Agent file and add the skills field:

📎 senior-backend-reviewer.md

---
name: senior-backend-reviewer
description: Use this agent when you need expert-level code review for backend Python/FastAPI code.
model: sonnet
tools: Read, Grep, Glob
skills: clean-architecture-rules, security-checklist, python-backend-standards
---

You are a Senior Backend Engineer and Code Reviewer with 15+ years of experience in Python, FastAPI, SQLAlchemy, and distributed systems architecture.

## Review Methodology

When reviewing code, systematically evaluate:

1. **Architecture & Layer Compliance** — Apply `clean-architecture-rules` skill
2. **Security Review** — Apply `security-checklist` skill
3. **Code Quality & Standards** — Apply `python-backend-standards` skill

## Review Output Format

**Overall Assessment**: [APPROVED | APPROVED WITH SUGGESTIONS | CHANGES REQUESTED]
**Risk Level**: [LOW | MEDIUM | HIGH]

- ✅ What's Good
- 🔴 Critical Issues (Must Fix)
- 🟡 Recommendations (Should Fix)
- 💡 Suggestions (Nice to Have)

What the skills Field Does

• Auto-loads specified Skills when Agent activates
• Keeps System Prompt concise (detailed checklists live in Skills)
• Multiple Agents can share the same Skills
• Update Skills once, all Agents get the changes

---

5. Skills to Prepare

Create these Skills in .claude/skills/:

📎 clean-architecture-rules.md

---
name: clean-architecture-rules
description: Clean Architecture layer rules and violation checklist for Python/FastAPI
---

# Clean Architecture Rules

## Layer Dependencies (MUST FOLLOW)

API Layer → Service Layer → Repository Layer → Database

## API Layer Rules
- ✅ Services injected via `Depends()`
- ❌ NO Repository imports
- ❌ NO business logic

## Service Layer Rules
- ✅ Return Pydantic BaseModel, NEVER `Dict[str, Any]`
- ✅ Business logic encapsulated here

## Repository Layer Rules
- ✅ CRUD only, return SQLAlchemy models
- ❌ NO business logic

## Severity Levels
| Violation | Severity |
|-----------|----------|
| API imports Repository | 🔴 CRITICAL |
| Service returns Dict | 🔴 CRITICAL |
| Business logic in API | 🔴 CRITICAL |

📎 security-checklist.md

---
name: security-checklist
description: Backend security vulnerability checklist for Python/FastAPI
---

# Security Checklist

## 🔴 Critical Issues
- Hardcoded secrets/API keys
- SQL injection (use parameterized queries)
- Missing authentication on protected routes
- Missing authorization/ownership checks

## 🟡 Warning Issues
- Sensitive data in logs
- Missing input validation
- No rate limiting on auth endpoints
- Insecure password hashing

## 💡 Best Practices
- Generic error messages (no internal details)
- Proper CORS configuration
- JWT expiration set

📎 python-backend-standards.md

---
name: python-backend-standards
description: Python/FastAPI coding standards including Pydantic v2, SQLAlchemy 2.0
---

# Python Backend Standards

## No Hardcoding Rules
- Magic numbers → Named constants
- String literals → Enums
- URLs → Configuration
- Error messages → ErrorCode enums

## Pydantic v2 Standards
| Old (v1) | New (v2) |
|----------|----------|
| `@validator` | `@field_validator` |
| `Config` class | `model_config = ConfigDict()` |
| `.dict()` | `.model_dump()` |

## SQLAlchemy 2.0 Standards
- Use `Mapped` types and `mapped_column`
- Use `select()` instead of `query()`

---

6. File Structure

.claude/
├── agents/
│   └── senior-backend-reviewer.md
└── skills/
    ├── clean-architecture-rules.md
    ├── security-checklist.md
    └── python-backend-standards.md

---

7. How to Use

Run Skills Directly

> /clean-architecture-rules
> /security-checklist
> /python-backend-standards

Run Agent (Auto-loads All Skills)

> @senior-backend-reviewer

or just ask naturally:

> Review this commit for architecture and security issues

Claude auto-delegates to senior-backend-reviewer, which loads all 3 Skills.

---

8. Execution Result

> Review this commit

🤖 [senior-backend-reviewer]

🔧 Skills loaded: clean-architecture-rules, security-checklist, python-backend-standards

## 📋 Code Review Summary

**Overall Assessment**: CHANGES REQUESTED
**Risk Level**: MEDIUM

### ✅ What's Good
- Proper dependency injection in most endpoints
- Good use of Pydantic schemas

### 🔴 Critical Issues (Must Fix)

**user_router.py:67** - Business logic in API layer
- Found: `if user.subscription_tier == 'premium':`
- Fix: Move to `UserService.check_premium_access()`

**user_service.py:45** - Returns Dict instead of Pydantic model
- Found: `return {"status": "ok"}`
- Fix: Create and return `StatusResponse` model

### 🟡 Recommendations

**auth_router.py:23** - Missing rate limiting
- Add `@limiter.limit("5/minute")` for login endpoint

---
Summary: 2 critical, 1 warning

---

9. Built-in Agents

Agent	Model	Purpose
general-purpose	Sonnet	Complex multi-step tasks
Explore	Haiku	Quick codebase exploration
Plan	inherit	Research in plan mode

---

10. Agent Design Tips

1. Create Skills first — Define reusable expertise as separate .md files
2. Connect via skills field — Use skill names (matches name in YAML frontmatter)
3. Keep System Prompt concise — Delegate checklists to Skills
4. Minimize tools — For review-only, Read, Grep, Glob is enough
5. Name files consistently — skill-name.md where filename matches name field

---

11. When to Use What?

Use Case	Recommendation
Reusable expertise	Skills
Direct invocation needed	Skills (/skill-name)
Isolated context needed	Agent
Expertise + Independent execution	Agent + Skills ✅
Parallel task processing	Agent

---

Conclusion

Skills are “reusable expertise.” Agents are “specialists who apply that expertise independently.”

The best practice is combining both:

• Skills define checklists, rules, and procedures
• Agents auto-load these Skills and execute in isolated context

To transfer a senior developer’s judgment to AI:

1. Define the knowledge (Skills) behind those judgments
2. Create specialists (Agents) who apply that knowledge
3. Let the Agent decide when to use which Skill

---

📎 Attachments

📎 senior-backend-reviewer

📎 clean-architecture-rules

📎 security-checklist

📎 python-backend-standards

---

Series:

1. Skills Guide — Teaching AI your expertise
2. Claude Code Skills Guide: How to Automate Your Development Process
3. Agent Guide — Teaching AI to think for itself (this article)