| name | anthropic-architect |
| description | Determine the best Anthropic architecture for your project by analyzing requirements and recommending the optimal combination of Skills, Agents, Prompts, and SDK primitives. |
Anthropic Architect
Expert architectural guidance for Anthropic-based projects. Analyze your requirements and receive tailored recommendations on the optimal architecture using Skills, Agents, Subagents, Prompts, and SDK primitives.
What This Skill Does
Helps you design the right Anthropic architecture for your project by:
- Analyzing project requirements - Understanding complexity, scope, and constraints
- Recommending architectures - Skills vs Agents vs Prompts vs SDK primitives
- Applying decision rubrics - Data-driven architectural choices
- Following best practices - 2025 Anthropic patterns and principles
- Progressive disclosure design - Efficient context management
- Security considerations - Safe, controllable AI systems
Why Architecture Matters
Without proper architecture:
- Inefficient context usage and high costs
- Poor performance and slow responses
- Security vulnerabilities and risks
- Difficult to maintain and scale
- Agents reading entire skill contexts unnecessarily
- Mixed concerns and unclear boundaries
With engineered architecture:
- Optimal context utilization
- Fast, focused responses
- Secure, controlled operations
- Easy to maintain and extend
- Progressive disclosure of information
- Clear separation of concerns
- Scalable and reusable components
Quick Start
Analyze Your Project
Using the anthropic-architect skill, help me determine the best
architecture for: [describe your project]
Requirements:
- [List your key requirements]
- [Complexity level]
- [Reusability needs]
- [Security constraints]
Get Architecture Recommendation
The skill will provide:
- Recommended architecture - Specific primitives to use
- Decision reasoning - Why this architecture fits
- Implementation guidance - How to build it
- Best practices - What to follow
- Example patterns - Similar successful architectures
The Four Anthropic Primitives
1. Skills (Prompt-Based Meta-Tools)
What: Organized folders of instructions, scripts, and resources that agents can discover and load dynamically.
When to use:
- ✅ Specialized domain knowledge needed
- ✅ Reusable across multiple projects
- ✅ Complex, multi-step workflows
- ✅ Reference materials required
- ✅ Progressive disclosure beneficial
When NOT to use:
- ❌ Simple, one-off tasks
- ❌ Project-specific logic only
- ❌ No need for reusability
Example use cases:
- Prompt engineering expertise
- Design system generation
- Code review guidelines
- Domain-specific knowledge (finance, medical, legal)
2. Agents/Subagents (Autonomous Task Handlers)
What: Specialized agents with independent system prompts, dedicated context windows, and specific tool permissions.
When to use:
- ✅ Complex, multi-step autonomous tasks
- ✅ Need for isolated context
- ✅ Different tool permissions required
- ✅ Parallel task execution
- ✅ Specialized expertise per task type
When NOT to use:
- ❌ Simple queries or lookups
- ❌ Shared context required
- ❌ Sequential dependencies
- ❌ Resource-constrained environments
Example use cases:
- Code exploration and analysis
- Test generation and execution
- Documentation generation
- Security audits
- Performance optimization
3. Direct Prompts (Simple Instructions)
What: Clear, explicit instructions passed directly to Claude without additional structure.
When to use:
- ✅ Simple, straightforward tasks
- ✅ One-time operations
- ✅ Quick questions or clarifications
- ✅ No need for specialization
- ✅ Minimal context required
When NOT to use:
- ❌ Complex, multi-step processes
- ❌ Need for reusability
- ❌ Requires domain expertise
- ❌ Multiple related operations
Example use cases:
- Code explanations
- Quick refactoring
- Simple bug fixes
- Documentation updates
- Direct questions
4. SDK Primitives (Custom Workflows)
What: Low-level building blocks from the Claude Agent SDK to create custom agent workflows.
When to use:
- ✅ Unique workflow requirements
- ✅ Custom tool integration needed
- ✅ Specific feedback loops required
- ✅ Integration with existing systems
- ✅ Fine-grained control needed
When NOT to use:
- ❌ Standard use cases covered by Skills/Agents
- ❌ Limited development resources
- ❌ Maintenance burden concern
- ❌ Faster time-to-market priority
Example use cases:
- Custom CI/CD integration
- Specialized code analysis pipelines
- Domain-specific automation
- Integration with proprietary systems
Decision Rubric
Use this rubric to determine the right architecture:
Task Complexity Analysis
Low Complexity → Direct Prompts
- Single operation
- Clear input/output
- No dependencies
- < 5 steps
Medium Complexity → Skills
- Multiple related operations
- Reusable patterns
- Reference materials helpful
- 5-20 steps
High Complexity → Agents/Subagents
- Multi-step autonomous workflow
- Needs isolated context
- Different tool permissions
-
20 steps or parallel tasks
Custom Complexity → SDK Primitives
- Unique workflows
- System integration required
- Custom tools needed
- Specific feedback loops
Reusability Assessment
Single Use → Direct Prompts
- One-time task
- Project-specific
- No future reuse
Team Reuse → Skills
- Multiple team members benefit
- Common workflows
- Shareable knowledge
Organization Reuse → Skills + Marketplace
- Cross-team benefit
- Standard patterns
- Company-wide knowledge
Product Feature → SDK Primitives
- End-user facing
- Production deployment
- Custom integration
Context Management Needs
Minimal Context → Direct Prompts
- Self-contained task
- No external references
- Simple instructions
Structured Context → Skills
- Progressive disclosure needed
- Reference materials required
- Organized information
Isolated Context → Agents/Subagents
- Separate concerns
- Avoid context pollution
- Parallel execution
Custom Context → SDK Primitives
- Specific context handling
- Integration requirements
- Fine-grained control
Security & Control Requirements
Basic Safety → Direct Prompts + Skills
- Standard guardrails
- No sensitive operations
- Read-only or low-risk
Controlled Access → Agents with Tool Restrictions
- Specific tool permissions
- Allowlist approach
- Confirmation required
High Security → SDK Primitives + Custom Controls
- Deny-all default
- Explicit confirmations
- Audit logging
- Custom security layers
Architecture Patterns
Pattern 1: Skills-First Architecture
Use when: Building reusable expertise and workflows
Structure:
Project
├── skills/
│ ├── domain-expert/
│ │ ├── SKILL.md
│ │ └── references/
│ │ ├── patterns.md
│ │ ├── best_practices.md
│ │ └── examples.md
│ └── workflow-automation/
│ ├── SKILL.md
│ └── scripts/
│ └── automate.sh
└── .claude/
└── config
Benefits:
- Reusable across projects
- Progressive disclosure
- Easy to share and maintain
- Clear documentation
Pattern 2: Agent-Based Architecture
Use when: Complex autonomous tasks with isolated concerns
Structure:
Main Agent (orchestrator)
├── Explore Agent (codebase analysis)
├── Plan Agent (task planning)
├── Code Agent (implementation)
└── Review Agent (validation)
Benefits:
- Parallel execution
- Isolated contexts
- Specialized expertise
- Clear responsibilities
Pattern 3: Hybrid Architecture
Use when: Complex projects with varied requirements
Structure:
Main Conversation
├── Direct Prompts (simple tasks)
├── Skills (reusable expertise)
│ ├── code-review-skill
│ └── testing-skill
└── Subagents (complex workflows)
├── Explore Agent
└── Plan Agent
Benefits:
- Right tool for each task
- Optimal resource usage
- Flexible and scalable
- Best of all approaches
Pattern 4: SDK Custom Architecture
Use when: Unique requirements or product features
Structure:
Custom Agent SDK Implementation
├── Custom Tools
├── Specialized Feedback Loops
├── System Integrations
└── Domain-Specific Workflows
Benefits:
- Full control
- Custom integration
- Unique workflows
- Production-ready
Key Principles (2025)
1. Progressive Disclosure
What: Show only what's needed, when it's needed.
Why: Avoids context limits, reduces costs, improves performance.
How: Organize skills with task-based navigation, provide query tools, structure information hierarchically.
2. Context as Resource
What: Treat context window as precious, limited resource.
Why: Every token counts toward limits and costs.
How: Use progressive disclosure, prefer retrieval over dumping, compress aggressively, reset periodically.
3. Clear Instructions
What: Explicit, unambiguous directions.
Why: Claude 4.x responds best to clarity.
How: Be specific, define output format, provide examples, avoid vagueness.
4. Security by Design
What: Deny-all default, allowlist approach.
Why: Safe, controlled AI systems.
How: Limit tool access, require confirmations, audit operations, block dangerous commands.
5. Thinking Capabilities
What: Leverage Claude's extended thinking mode.
Why: Better results for complex reasoning.
How: Request step-by-step thinking, allow reflection after tool use, guide initial thinking.
6. Two-Message Pattern
What: Use meta messages for context without UI clutter.
Why: Clean UX while providing necessary context.
How: Set isMeta: true for system messages, use for skill loading, keep UI focused.
Reference Materials
All architectural patterns, decision frameworks, and examples are in the references/ directory:
- decision_rubric.md - Comprehensive decision framework
- architectural_patterns.md - Detailed pattern catalog
- best_practices.md - 2025 Anthropic best practices
- use_case_examples.md - Real-world architecture examples
Usage Examples
Example 1: Determining Architecture for Content Generation
Input:
Using anthropic-architect, I need to build a system that:
- Generates blog posts from product features
- Ensures brand voice consistency
- Includes SEO optimization
- Reusable across marketing team
Analysis:
- Medium complexity (structured workflow)
- High reusability (team-wide)
- Domain expertise needed (content, SEO, brand)
- Progressive disclosure beneficial
Recommendation: Skills-First Architecture
- Create
content-generator skill
- Include brand voice references
- SEO guidelines in references
- Example templates
- Progressive disclosure for different content types
Example 2: Code Refactoring Tool
Input:
Using anthropic-architect, I want to:
- Analyze codebase for refactoring opportunities
- Generate refactoring plan
- Execute refactoring with tests
- Review and validate changes
Analysis:
- High complexity (multi-step, autonomous)
- Different contexts needed (explore, plan, code, review)
- Parallel execution beneficial
- Tool permissions vary by stage
Recommendation: Agent-Based Architecture
- Main orchestrator agent
- Explore subagent (read-only, codebase analysis)
- Plan subagent (planning, no execution)
- Code subagent (write permissions)
- Review subagent (validation, test execution)
Example 3: Simple Code Review
Input:
Using anthropic-architect, I need to:
- Review this PR for bugs
- Check code style
- Suggest improvements
Analysis:
- Low complexity (single operation)
- One-time task
- No reusability needed
- Minimal context
Recommendation: Direct Prompt
- Simple, clear instructions
- No skill/agent overhead
- Fast execution
- Sufficient for task
Example 4: Custom CI/CD Integration
Input:
Using anthropic-architect, I want to:
- Integrate Claude into CI pipeline
- Custom tool for deployment validation
- Specific workflow for our stack
- Production feature
Analysis:
- Custom complexity
- System integration required
- Production deployment
- Unique workflows
Recommendation: SDK Primitives
- Build custom agent with SDK
- Implement custom tools
- Create specialized feedback loops
- Integration with CI system
Best Practices Checklist
When designing your architecture:
Common Anti-Patterns
Anti-Pattern 1: Over-Engineering
Problem: Using Agents/SDK for simple tasks
Solution: Start simple, scale complexity as needed
Anti-Pattern 2: Context Dumping
Problem: Loading entire skills into context
Solution: Use progressive disclosure, query tools
Anti-Pattern 3: Mixed Concerns
Problem: Single skill/agent doing too much
Solution: Separate concerns, use subagents or multiple skills
Anti-Pattern 4: No Security Boundaries
Problem: Full tool access for all agents
Solution: Allowlist approach, minimal permissions
Anti-Pattern 5: Ignoring Reusability
Problem: Recreating same prompts repeatedly
Solution: Extract to skills, share across projects
Getting Started
Step 1: Describe Your Project
Provide clear requirements, complexity level, and constraints.
Step 2: Receive Recommendation
Get tailored architecture with reasoning.
Step 3: Review Patterns
Explore similar successful architectures.
Step 4: Implement
Follow implementation guidance.
Step 5: Iterate
Refine based on results and feedback.
Summary
The Anthropic Architect skill helps you:
- Choose the right primitives for your needs
- Design scalable, maintainable architectures
- Follow 2025 best practices
- Avoid common pitfalls
- Optimize for performance and cost
Key Primitives:
- Skills - Reusable domain expertise
- Agents - Autonomous complex workflows
- Prompts - Simple direct tasks
- SDK - Custom integrations
Core Principles:
- Progressive disclosure
- Context as resource
- Security by design
- Clear instructions
- Right tool for the job
"The best architecture is the simplest one that meets your requirements."
