Agent Design

majiayu000/claude-skill-registry-agent-design

Design AI agents with recommended patterns and architectures

1k tokens

context cost

the whole folder, loaded on every use

files

instructions only

copies elsewhere

how many repositories repackaged it

532

stars on the repo

on the repository, not the skill itself

Install

one command, takes just this skill from the repository

npx skills add https://github.com/majiayu000/claude-skill-registry --skill agent-design

What comes with it

639 bytes besides the instruction

metadata.json

What it tells the agent to use

found in the instruction text

Task spawns other agents

The instruction itself

26 sections, as written by the author

Agent 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

How to use it

Copy the folder

Take majiayu000/claude-skill-registry-agent-design from the repository into ~/.claude/skills for personal use, or into .claude/skills inside a project.

Check the name does not clash

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.