Agent Design Skill for Claude
Design AI agents with recommended patterns and architectures
Install
one command, takes just this skill from the repositorynpx skills add https://github.com/majiayu000/claude-skill-registry --skill agent-designWhat comes with it
639 bytes besides the instructionWhat it tells the agent to use
found in the instruction textThe instruction itself
26 sections, as written by the authorAgent Design
Skill for designing high-performance AI agents following 2025 patterns.
Documentation
- patterns.md - Multi-agent architecture patterns
- workflows.md - Recommended workflows
Fundamental Distinction
Workflows vs Agents
| Type | Control | When to use |
|------|---------|-------------|
| Workflow | Code orchestrates LLM | Predictable tasks, need for control |
| Agent | LLM directs its actions | Flexibility, adaptive decisions |
Golden rule: Start simple, add complexity if necessary.
Agent Architecture
Minimal Structure
Agent:
identity: Who am I?
capabilities: What can I do?
tools: What tools do I have?
constraints: What are my limits?
workflow: How should I proceed?
Complete Structure (Production)
---
name: my-agent
description: Short description
model: sonnet|opus
tools: [list of tools]
skills: [associated skills]
---
# Identity
[Who the agent is]
# Capabilities
[What it can do]
# Workflow
[Steps to follow]
# Tools
[How to use each tool]
# Constraints
[Limits and rules]
# Examples
[Use cases]
# Forbidden
[What it must NEVER do]
Agent Patterns
1. Single Agent (Simple)
User → Agent → Response
Usage: Simple tasks, rapid prototyping.
2. Agent + Tools
User → Agent ↔ Tools → Response
↑
Tool Results
Usage: Tasks requiring external access (API, files, DB).
3. Orchestrator + Subagents
User → Orchestrator → Subagent 1 (specialized)
→ Subagent 2 (specialized)
→ Subagent 3 (specialized)
↓
Synthesis → Response
Usage: Complex tasks, separation of responsibilities.
4. Sequential Pipeline
User → Agent 1 → Agent 2 → Agent 3 → Response
(Analyze) (Plan) (Execute)
Usage: Linear processes (e.g., Analyst → Architect → Developer).
Fresh Eyes Principle
Key 2025 concept: Each sub-agent must have a "fresh" context.
❌ Bad: Pass entire history to each sub-agent
✅ Good: Give only necessary information
Orchestrator:
- Keeps complete history
- Extracts relevant context for each sub-agent
- Synthesizes results
Design Checklist
Before creating an agent
- [ ] Is the objective clear?
- [ ] Would a simple workflow suffice?
- [ ] What tools are needed?
- [ ] What guardrails are required?
During design
- [ ] Is identity well defined?
- [ ] Is workflow explicit?
- [ ] Are error cases handled?
- [ ] Are examples relevant?
After creation
- [ ] Standard case tests?
- [ ] Edge case tests?
- [ ] Security tests (jailbreak)?
- [ ] Acceptable performance?
Claude Code Agent Template
---
name: [kebab-case-name]
description: [1-2 lines max]
model: sonnet
color: blue
tools: Read, Edit, Write, Bash, Grep, Glob
skills: [associated-skills]
---
# [Agent Name]
[Purpose description]
## Core Principles
1. **[Principle 1]**: [Short explanation]
2. **[Principle 2]**: [Short explanation]
## Workflow (MANDATORY)
### Phase 1: [Name]
[Numbered actions]
### Phase 2: [Name]
[Numbered actions]
## Output Format
[Response structure]
## Forbidden
- [Prohibition 1]
- [Prohibition 2]
Anti-Patterns to Avoid
❌ Omniscient agent
You know everything and can do anything.
✅ Specialized agent
You are an expert in [specific domain].
For topics outside your domain, redirect to the appropriate agent.
❌ Implicit instructions
Do what's logical.
✅ Explicit instructions
Step 1: Analyze the problem
Step 2: Propose 3 solutions
Step 3: Recommend the best with justification
❌ No error handling
Execute the task.
✅ Explicit error handling
IF the task fails:
1. Identify the cause
2. Propose an alternative
3. Ask for confirmation before retrying
Forbidden
- Never create an agent without explicit workflow
- Never give access to all tools without necessity
- Never ignore the principle of least privilege
- Never forget security guardrails
Other skills for the same job
different authors, same section of the catalogue
Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.
Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.
Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.
Replace with description of the skill and when Claude should use it.
Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies
This skill should be used when the user wants to "create a skill", "add a skill to plugin", "write a new skill", "improve skill description", "organize skill content", or needs guidance on skill structure, progressive disclosure, or skill development best practices for Claude Code plugins.
Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
Use when creating new skills, editing existing skills, or verifying skills work before deployment
How to use it
Take majiayu000/claude-skill-registry-agent-design from the repository into ~/.claude/skills for personal
use, or into .claude/skills inside a project.
The agent identifies a skill by the name field in its header. Two skills with the
same name cannot sit side by side — one of them will be ignored.