anthropic-architect

What this skill does

# 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:
1. **Recommended architecture** - Specific primitives to use
2. **Decision reasoning** - Why this architecture fits
3. **Implementation guidance** - How to build it
4. **Best practices** - What to follow
5. **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 Agen