# ⚡ Crafted Skills - Quick Start

**Get started with Crafted Skills in 5 minutes**

---

## 🚀 Installation

```bash
cd your-crafted-project
crafted install-skills
```

---

## 💡 How It Works

**You don't need to configure anything!**

Skills auto-detect your project level and adapt automatically.

---

## 🎯 Basic Usage

### Just describe what you want:

```
User: "Add user authentication with email/password"
```

Claude will:
1. ✅ Detect your level (rapid/balanced/crafted)
2. ✅ Design appropriate architecture
3. ✅ Implement following your level's rules
4. ✅ Write tests with correct coverage
5. ✅ Validate everything

**All automatically!**

---

## 📊 Skill Categories

### 1. Workflow Skills (Complete Tasks)

Use these for end-to-end workflows:

```bash
/feature "Add product catalog"    # Architecture → Implementation → Testing → Review
/bugfix "Users can't login"       # Reproduce → Diagnose → Fix → Test → Validate
/refactor "Extract service layer" # Analyze → Plan → Refactor → Test → Validate
/security "Review auth system"    # Scan → Analyze → Harden → Test → Document
```

### 2. Agent Skills (Specialized Roles)

Use these when you only need a specific role:

```bash
/architect "Design notification system"  # Architecture design only
/developer "Implement user registration" # Code implementation only
/tester "Add tests for auth"            # Testing only
/reviewer "Review this code"            # Code review only
```

### 3. Utility Skills (Quick Checks)

Use these during development for fast feedback:

```bash
/validate  # Check code quality (function length, params, duplication)
/guard     # Check architecture boundaries (layers, circular deps)
/coverage  # Check test coverage (meets level requirements)
```

### 4. Level Skills (Context Switchers)

Usually auto-detected, but you can activate manually:

```bash
/rapid     # Ship fast mode (0-100 users, max 100 lines/function)
/balanced  # Pragmatic quality (100-10K users, max 50 lines/function, 70% coverage)
/crafted   # Enterprise mode (10K-1M+ users, max 20 lines/function, 100% domain coverage)
```

---

## 🔄 Example Workflow

### Scenario: Add Product Catalog

**What you type:**
```
"I want to add a product catalog with filtering and pagination"
```

**What happens automatically:**

```
🔍 Auto-detect: balanced level, web platform
     ↓
🏗️  Architect: Design 3-layer architecture
     ↓
👨‍💻 Developer: Implement (Router < 20 lines, Service < 50 lines)
     ↓
🧪 Tester: Write tests (70% coverage)
     ↓
👀 Reviewer: Validate (code quality + architecture + coverage)
     ↓
✅ Feature ready!
```

**You get:**
- ✅ Clean, production-ready code
- ✅ Comprehensive tests
- ✅ Proper architecture
- ✅ ADRs for major decisions (Balanced+)

**All from one simple request!**

---

## 💪 Real Examples

### Build a Feature
```
User: "Add user authentication with email/password"

Claude:
  ✅ Detects: balanced level
  ✅ Creates: 3-layer architecture (Router → Service → Repository)
  ✅ Implements: Thin routers, services with business logic
  ✅ Tests: 75% coverage
  ✅ Validates: All rules pass
```

### Fix a Bug
```
User: "Bug: Users can't update email with + sign"

Claude:
  ✅ Writes failing test (reproduces bug)
  ✅ Finds root cause (Email regex too strict)
  ✅ Fixes validation logic
  ✅ Adds regression test
  ✅ Validates no side effects
```

### Refactor Code
```
User: "This router file is too big"

Claude:
  ✅ Analyzes: 250 lines (should be < 20 for balanced)
  ✅ Extracts: Service layer (business logic)
  ✅ Extracts: Repository layer (data access)
  ✅ Result: Router 15 lines, Service 80 lines, Repository 40 lines
  ✅ Validates: Architecture boundaries OK
```

### Quick Check
```
User: /validate

Claude:
  ✅ Function length: All < 50 lines
  ✅ Parameters: All < 3 params
  ✅ Type safety: All typed
  ⚠️  Duplication: 2 places (acceptable for balanced)

  No blocking issues!
```

---

## 🎓 Level Differences

Skills adapt to your project level:

| Aspect | Rapid | Balanced | Crafted |
|--------|-------|----------|---------|
| **Function length** | < 100 lines | < 50 lines | < 20 lines |
| **Parameters** | Flexible | Max 3 | Max 2 |
| **Coverage** | None required | 70% min | Domain 100%, Use-cases 100% |
| **Architecture** | Flat (routers) | 3-layer | Hexagonal (domain-driven) |
| **Duplication** | OK if < 3x | Extract if > 2x | ZERO (CI fails) |
| **ADRs** | Optional | Major decisions | ALL decisions |

---

## ✅ Best Practices

### 1. Let Skills Auto-Detect
```
✅ "Add authentication"
❌ "Add authentication using balanced level with 3 layers and 70% coverage"
```

### 2. Use Workflow Skills for Complete Tasks
```
✅ /feature "Add payments"
❌ /architect then /developer then /tester then /reviewer
```

### 3. Use Agent Skills for Specialized Tasks
```
✅ /architect "Design microservices split"  (just architecture)
✅ /reviewer "Review this PR"               (just review)
```

### 4. Use Utility Skills During Development
```
✅ /validate  (quick code quality check)
✅ /guard     (quick architecture check)
✅ /coverage  (quick coverage check)
```

---

## 🐛 Troubleshooting

### Skills not working?
```bash
# Verify installation
ls .claude/skills/

# Should show:
# README.md, levels/, workflows/, agents/, utils/
```

### Wrong level detected?
```bash
# Check .craftedrc.json
cat .craftedrc.json

# Should show:
# { "level": "balanced", "platform": "web" }
```

### Want to force a level?
```bash
/validate crafted  # Force crafted rules
/guard balanced    # Force balanced rules
```

---

## 📚 Next Steps

1. **Read full tutorial**: `.claude/skills/TUTORIAL.md`
2. **Explore skill docs**: `.claude/skills/README.md`
3. **Try on real tasks**: Start with `/feature "your feature name"`
4. **Check specific skills**: Read individual skill files in `levels/`, `workflows/`, `agents/`, `utils/`

---

## 🎯 TL;DR

**Just tell Claude what you want:**
```
"Add product catalog"
"Fix this bug"
"Refactor this code"
"Review security"
```

**Claude will:**
- ✅ Auto-detect your project level
- ✅ Apply appropriate rules
- ✅ Use correct architecture
- ✅ Write proper tests
- ✅ Validate everything

**No configuration needed. It just works! 🚀**

---

**Questions?**
- Full docs: `.claude/skills/README.md`
- Tutorial: `.claude/skills/TUTORIAL.md`
- Issues: https://github.com/crafted-saas/issues
