anthropic-architect skill by jamesrochabrun

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

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:

Benefits:

Parallel execution
Isolated contexts
Specialized expertise
Clear responsibilities

Pattern 3: Hybrid Architecture

Use when: Complex projects with varied requirements

Structure:

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:

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:

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:

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:

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:

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."