Initial commit
This commit is contained in:
Zhongwei Li
571
skills/anthropic-architect/SKILL.md
Normal file
571
skills/anthropic-architect/SKILL.md
Normal file
@@ -0,0 +1,571 @@
|
||||
---
|
||||
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:
|
||||
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 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:
|
||||
|
||||
- [ ] Analyzed task complexity accurately
|
||||
- [ ] Considered reusability requirements
|
||||
- [ ] Evaluated context management needs
|
||||
- [ ] Assessed security requirements
|
||||
- [ ] Applied progressive disclosure where beneficial
|
||||
- [ ] Chose simplest solution that works
|
||||
- [ ] Documented architectural decisions
|
||||
- [ ] Planned for maintenance and updates
|
||||
- [ ] Considered cost implications
|
||||
- [ ] Validated with prototype/POC
|
||||
|
||||
## 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."**
|
||||
Reference in New Issue
Block a user