# 🎯 Crafted Skills for Claude Code

**Advanced AI skills for context-aware software development**

Crafted Skills transform Claude Code into a context-aware development assistant that automatically adapts to your project's quality level (Rapid, Balanced, or Crafted).

---

## 📋 Table of Contents

- [What Are Skills?](#what-are-skills)
- [Skill Categories](#skill-categories)
- [How It Works](#how-it-works)
- [Quick Start](#quick-start)
- [Skill Reference](#skill-reference)
- [Examples](#examples)
- [Best Practices](#best-practices)

---

## What Are Skills?

Skills are **specialized modes** that give Claude Code deep expertise in specific tasks. Unlike traditional prompts or MCP tools, skills:

- ✅ **Auto-detect context** (project level, platform)
- ✅ **Adapt workflows** based on quality requirements
- ✅ **Enforce rules** automatically
- ✅ **Orchestrate tools** (MCP servers)
- ✅ **Provide guidance** step-by-step

Think of skills as **AI personas** that Claude can switch between:
- 🏗️ **Architect** mode for designing systems
- 👨‍💻 **Developer** mode for writing code
- 🧪 **Tester** mode for comprehensive testing
- 👀 **Reviewer** mode for quality assurance

---

## Skill Categories

### 1. Level Skills - Context Switchers

Set the quality level context for all operations:

| Skill | Level | Purpose |
|-------|-------|---------|
| `/rapid` | 🚀 Rapid | Ship fast, 0-100 users, $0-5K MRR |
| `/balanced` | ⚖️ Balanced | Pragmatic quality, 100-10K users, $5K-100K MRR |
| `/crafted` | 🏆 Crafted | Enterprise grade, 10K-1M+ users, $100K+ MRR |

**Auto-detection**: Skills automatically detect your project level using MCP tools.

---

### 2. Workflow Skills - Action Triggers

Complete workflows from start to finish:

| Skill | Purpose | Steps |
|-------|---------|-------|
| `/feature` | Build new feature | Architecture → Implementation → Testing → Review |
| `/bugfix` | Fix bugs systematically | Reproduce → Diagnose → Fix → Test → Validate |
| `/refactor` | Improve code quality | Analyze → Plan → Refactor → Test → Validate |
| `/security` | Security review & hardening | Scan → Analyze → Harden → Test → Document |

**Adaptive**: Workflows adapt to your project level (Rapid/Balanced/Crafted).

---

### 3. Agent Skills - Role-Based Modes

Specialized AI personas for different roles:

| Skill | Role | Focus |
|-------|------|-------|
| `/architect` | 🏗️ Software Architect | System design, ADRs, architecture decisions |
| `/developer` | 👨‍💻 Craftsman Developer | Clean code, implementation, refactoring |
| `/tester` | 🧪 Quality Engineer | Comprehensive testing, coverage, quality |
| `/reviewer` | 👀 Code Reviewer | Quality assurance, validation, approval |

**Context-aware**: Each agent follows level-appropriate rules.

---

### 4. Utility Skills - Quick Actions

Fast validation and checks:

| Skill | Purpose |
|-------|---------|
| `/validate` | Validate code quality (function length, params, duplication) |
| `/guard` | Check architecture boundaries (layer violations, circular deps) |
| `/coverage` | Validate test coverage (70% Balanced, 100% Crafted domain) |

**Fast**: Direct MCP tool invocation for quick checks.

---

## How It Works

### Auto-Detection Flow

```
User: "I want to add user authentication"
          ↓
    /feature skill activated
          ↓
  Detect project context:
  - Level: balanced
  - Platform: web
          ↓
  Execute workflow:
  1. Architecture (Balanced rules)
     - 3-layer design
     - Create ADR
          ↓
  2. Implementation (Balanced rules)
     - Thin routers (< 20 lines)
     - Services (< 50 lines)
     - Max 3 params
          ↓
  3. Testing (Balanced rules)
     - Unit tests
     - 70% coverage
          ↓
  4. Review (Balanced rules)
     - Validate architecture
     - Check coverage
          ↓
       ✅ Done!
```

### Level Adaptation

Skills automatically apply different rules based on level:

**Example: Function Length**
```typescript
// RAPID level (< 100 lines)
export const productRouter = createTRPCRouter({
  create: procedure.mutation(async ({ input }) => {
    // 80 lines of logic - OK for Rapid
  }),
});

// BALANCED level (< 50 lines in services)
export const productService = {
  async create(data: CreateProductInput) {
    // 45 lines - OK for Balanced
  },
};

// CRAFTED level (< 20 lines)
export class Product {
  static create(props: CreateProductProps): Result<Product> {
    // 15 lines - OK for Crafted
  }
}
```

---

## Quick Start

### 1. Activate a Level Skill

```bash
# Tell Claude what level you're working at
/rapid      # For MVP/validation
/balanced   # For growth phase
/crafted    # For enterprise scale
```

Or let it auto-detect:
```
User: "Add product catalog feature"
Claude: *Detects level: balanced*
        *Applies Balanced workflow automatically*
```

### 2. Use a Workflow Skill

```bash
# Complete feature development
/feature "Add user authentication"

# Fix a bug systematically
/bugfix "Users can't update email"

# Refactor code
/refactor "Extract service layer from router"

# Security review
/security "Review authentication system"
```

### 3. Switch to Agent Mode

```bash
# Design architecture
/architect "Design product catalog"

# Write code
/developer "Implement user registration"

# Write tests
/tester "Add tests for auth flow"

# Review code
/reviewer "Review product catalog implementation"
```

### 4. Quick Validation

```bash
# Validate code quality
/validate balanced

# Check architecture boundaries
/guard crafted

# Check test coverage
/coverage balanced
```

---

## Skill Reference

### Level Skills

#### `/rapid` - Ship Fast
**Context**: 1-2 developers, 3-6 months, 0-100 users, $0-5K MRR

**Rules**:
- Functions < 100 lines
- Duplication OK if < 3 times
- No coverage minimum
- Flat architecture (logic in routers)

**Philosophy**: "Code that works > Perfect code"

[Full documentation](./levels/rapid.md)

---

#### `/balanced` - Pragmatic Quality
**Context**: 3-10 developers, 1-3 years, 100-10K users, $5K-100K MRR

**Rules**:
- Functions < 50 lines
- Max 3 parameters
- Extract if duplication > 2 times
- 70% coverage
- 3-layer architecture (Router → Service → Repository)

**Philosophy**: "Quality where it matters"

[Full documentation](./levels/balanced.md)

---

#### `/crafted` - Software Craftsmanship
**Context**: 10-200+ developers, 5-10+ years, 10K-1M+ users, $100K+ MRR

**Rules**:
- Functions < 20 lines
- Max 2 parameters
- ZERO duplication
- Domain 100% coverage, Use-cases 100%, Infrastructure 80%
- Hexagonal architecture (Domain → Application → Infrastructure)
- Domain has ZERO external dependencies

**Philosophy**: "Build it right, sustainable for 10+ years"

[Full documentation](./levels/crafted.md)

---

### Workflow Skills

#### `/feature` - Feature Development
**Workflow**: Architecture → Implementation → Testing → Review

**Adapts to level**:
- Rapid: Flat structure, basic tests
- Balanced: 3-layer, 70% coverage
- Crafted: Hexagonal, Spec-First TDD, 100% domain coverage

[Full documentation](./workflows/feature.md)

---

#### `/bugfix` - Bug Fixing
**Workflow**: Reproduce → Diagnose → Fix → Test → Validate

**Adds regression test** to prevent bug from coming back

[Full documentation](./workflows/bugfix.md)

---

#### `/refactor` - Code Refactoring
**Workflow**: Analyze → Plan → Refactor → Test → Validate

**Common refactorings**:
- Extract function
- Extract service (Rapid → Balanced)
- Extract domain (Balanced → Crafted)
- Replace comment with function
- Introduce value object

[Full documentation](./workflows/refactor.md)

---

#### `/security` - Security Review
**Workflow**: Scan → Analyze (OWASP Top 10) → Harden → Test → Document

**Checks**:
- Broken access control
- Cryptographic failures
- Injection vulnerabilities
- Security misconfiguration
- And more...

[Full documentation](./workflows/security.md)

---

### Agent Skills

#### `/architect` - Software Architect Mode
**Focus**: System design, ADRs, architecture decisions

**Tasks**:
- Design level-appropriate architecture
- Create ADRs for major decisions
- Validate architecture boundaries

[Full documentation](./agents/architect.md)

---

#### `/developer` - Craftsman Developer Mode
**Focus**: Clean code, implementation

**Tasks**:
- Write self-documenting code
- NO inline comments (refactor instead)
- Follow level-specific rules
- Validate with tools

[Full documentation](./agents/developer.md)

---

#### `/tester` - Quality Engineer Mode
**Focus**: Comprehensive testing

**Tasks**:
- Write meaningful tests (not just coverage %)
- Test happy path AND edge cases
- For Crafted: Write tests FIRST (Spec-First TDD)

[Full documentation](./agents/tester.md)

---

#### `/reviewer` - Code Reviewer Mode
**Focus**: Quality assurance, validation

**Tasks**:
- Validate code quality
- Check architecture compliance
- Verify test coverage
- Ensure security best practices

[Full documentation](./agents/reviewer.md)

---

### Utility Skills

#### `/validate` - Code Quality Validation
Validates code against level-specific rules:
- Function length
- Parameter count
- Duplication
- Test coverage

[Full documentation](./utils/validate.md)

---

#### `/guard` - Architecture Boundary Enforcement
Checks architecture boundaries:
- Balanced: 3-layer separation
- Crafted: Domain has ZERO external dependencies

[Full documentation](./utils/guard.md)

---

#### `/coverage` - Test Coverage Validation
Validates test coverage:
- Rapid: No minimum (but critical flows)
- Balanced: 70% minimum
- Crafted: Domain 100%, Use-cases 100%, Infrastructure 80%

[Full documentation](./utils/coverage.md)

---

## Examples

### Example 1: Feature Development (Balanced)

```
User: "Add product catalog with filtering"

Claude: I'll help you build this feature. Let me first detect your project context.

*Uses MCP: get_architecture_info()*
Result: { level: "balanced", platform: "web" }

I'll use the Balanced-level workflow:

**Step 1: Architecture (Architect mode)**
Designing 3-layer structure:
- Router: productRouter.list() < 20 lines
- Service: productService.list() with filtering logic < 50 lines
- Repository: productRepository.findMany() with Prisma

Creating ADR-042: Use cursor pagination for scalability

**Step 2: Implementation (Developer mode)**
*Creates thin router*
*Creates service with business logic*
*Creates repository with data access*
*Validates with MCP: validate_code(level: "balanced")*
✅ No violations

**Step 3: Testing (Tester mode)**
*Writes unit tests for service*
*Writes integration tests*
*Ensures 70% coverage*
*MCP: check_coverage({ threshold: 70 })*
✅ Coverage: 75%

**Step 4: Review (Reviewer mode)**
*MCP: check_layer_boundaries()*
✅ No architecture violations
*MCP: run_tests()*
✅ All tests pass

Feature complete! 🎉
```

### Example 2: Bug Fix

```
User: "Users can't update their email address"

Claude: I'll help fix this bug systematically.

**Step 1: Reproduce**
*Writes failing test*
it('should update user email', async () => {
  const result = await userService.updateEmail('user-123', 'new@email.com');
  expect(result.isSuccess).toBe(true); // FAILS
});

**Step 2: Diagnose**
*Searches code: updateEmail*
*Finds issue: Email validation too strict, rejects + sign*

**Step 3: Fix**
*Updates Email value object*
export class Email {
  private static readonly REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  // Now accepts + sign in emails
}

**Step 4: Test (Regression test)**
it('should accept email with plus sign', async () => {
  const result = await userService.updateEmail('user-123', 'user+test@email.com');
  expect(result.isSuccess).toBe(true);
});
✅ Tests pass

**Step 5: Validate**
*Runs all tests*
✅ All tests pass
*No side effects*

Bug fixed! 🎉
```

### Example 3: Refactoring (Rapid → Balanced)

```
User: "This router is getting too big, can you refactor it?"

Claude: Let me analyze this code.

*Reads file: packages/api/routers/product.ts*
Current: 250 lines in router

*MCP: get_architecture_info()*
Level: balanced

**Issue**: Router has 250 lines (should be < 20 for Balanced)
Business logic should be in service layer.

**Refactoring Plan**:
1. Extract productService
2. Extract productRepository
3. Thin down router to < 20 lines

**Step 1: Extract Service**
*Creates packages/services/product.service.ts*

**Step 2: Extract Repository**
*Creates packages/database/repositories/product.repository.ts*

**Step 3: Thin Router**
*Updates router to call service (now 15 lines)*

**Validation**:
*MCP: validate_code(level: "balanced")*
✅ No violations

*MCP: check_layer_boundaries()*
✅ Proper 3-layer separation

Before: 250 lines in router
After: 15 lines router, 80 lines service, 40 lines repository

Refactoring complete! Architecture now follows Balanced level. 🎉
```

---

## Best Practices

### 1. Let Skills Auto-Detect

```
✅ GOOD
User: "Add authentication"
Claude: *Auto-detects level: balanced*
        *Applies appropriate workflow*

❌ AVOID
User: "Add authentication"
User: "Use balanced level"
User: "Make sure to follow 3-layer architecture"
(Claude already knows this)
```

### 2. Use Workflow Skills for Complete Tasks

```
✅ GOOD
/feature "Add product catalog"
(Handles architecture → implementation → testing → review)

❌ AVOID
/architect "Design product catalog"
/developer "Implement product catalog"
/tester "Test product catalog"
/reviewer "Review product catalog"
(Manually invoking each step)
```

### 3. Use Agent Skills for Specialized Tasks

```
✅ GOOD
/architect "Design microservices architecture"
(When you ONLY need architecture design)

/reviewer "Review this PR"
(When you ONLY need code review)

❌ AVOID
/architect "Add authentication feature"
(Use /feature instead - it includes architecture + more)
```

### 4. Use Utility Skills for Quick Checks

```
✅ GOOD
/validate balanced
/guard crafted
/coverage balanced

(Quick validation during development)

❌ AVOID
/reviewer "Check code quality"
(Too heavy for quick check)
```

### 5. Trust Auto-Detection

Skills automatically:
- Detect project level
- Apply appropriate rules
- Use correct MCP tools
- Adapt workflows

You don't need to specify:
- "Use balanced level rules"
- "Check 70% coverage"
- "Ensure 3-layer architecture"

Just describe what you want to build!

---

## Integration with MCP Servers

Skills orchestrate MCP tools automatically:

```
Skill: /feature
  ↓
Auto-detects level
  ↓ uses
mcp__crafted-context__get_architecture_info()
  ↓
Validates code
  ↓ uses
mcp__rules-validator__validate_code({ level: "balanced" })
  ↓
Checks architecture
  ↓ uses
mcp__architecture-guard__check_layer_boundaries({ level: "balanced" })
  ↓
Runs tests
  ↓ uses
mcp__vitest__run_tests()
mcp__vitest__check_coverage({ threshold: 70 })
  ↓
✅ Feature complete!
```

You don't manually call MCP tools - skills do it for you!

---

## Troubleshooting

### Skill not working?

1. **Check skill exists**
   ```bash
   ls .claude/skills/
   ```

2. **Check skill syntax**
   Skills are invoked with `/skillname`

3. **Let Claude auto-detect**
   Don't force a level if Claude should detect it

### Wrong level detected?

Check `.craftedrc.json`:
```json
{
  "level": "balanced",
  "platform": "web"
}
```

### Rules too strict?

You might be at the wrong level:
- MVP/Prototype → Use Rapid
- Growing product → Use Balanced
- Enterprise → Use Crafted

---

## Contributing

Want to add a custom skill?

1. Create skill file in appropriate category
2. Follow existing skill structure
3. Document MCP tools used
4. Add examples

---

## Support

- **Documentation**: Each skill has detailed docs
- **Issues**: https://github.com/crafted-saas/issues
- **Discord**: https://discord.gg/crafted-saas

---

**Built with ❤️ for the Crafted SaaS community**

Transform Claude Code into a context-aware development partner that adapts to your quality level!
