architecture/skills/capability-writing/reference/anti-patterns.md

# Anti-Patterns to Avoid

Common mistakes when creating skills and agents.

## Skill Design Anti-Patterns

### 1. Overly Broad Components

**Bad:** One skill that does everything

```yaml
---
name: project-management
description: Handles issues, PRs, releases, documentation, deployment, testing, CI/CD...
---

# Project Management

This skill does:
- Issue management
- Pull request reviews
- Release planning
- Documentation
- Deployment
- Testing
- CI/CD configuration
...
```

**Why it's bad:**
- Huge context window usage
- Hard to maintain
- Unclear when to trigger
- Tries to do too much

**Good:** Focused components

```yaml
---
name: issue-writing
description: How to write clear, actionable issues with acceptance criteria.
---
```

**Separate skills for:**
- `issue-writing` - Issue quality
- `review-pr` - PR reviews
- `gitea` - CLI reference
- Each does one thing well

---

### 2. Vague Instructions

**Bad:**

```markdown
1. Handle the issue
2. Do the work
3. Finish up
4. Let me know when done
```

**Why it's bad:**
- No clear actions
- Claude has to guess
- Inconsistent results
- Hard to validate

**Good:**

```markdown
1. **View issue**: `tea issues $1 --comments`
2. **Create branch**: `git checkout -b issue-$1-<title>`
3. **Plan work**: Use TodoWrite to break down steps
4. **Implement**: Make necessary changes
5. **Commit**: `git commit -m "feat: ..."`
6. **Create PR**: `tea pulls create --title "..." --description "..."`
```

---

### 3. Missing Skill References

**Bad:**

```markdown
Use the gitea skill to create an issue.
```

**Why it's bad:**
- Skills have ~20% auto-activation rate
- Claude might not load the skill
- Inconsistent results

**Good:**

```markdown
@~/.claude/skills/gitea/SKILL.md

Use `tea issues create --title "..." --description "..."`
```

**The `@` reference guarantees the skill content is loaded.**

---

### 4. God Skills

**Bad:** Single 1500-line skill covering everything

```
skills/database/SKILL.md (1500 lines)
- PostgreSQL
- MySQL
- MongoDB
- Redis
- All queries
- All optimization tips
- All schemas
```

**Why it's bad:**
- Exceeds recommended 500 lines
- Loads everything even if you need one thing
- Hard to maintain
- Wastes tokens

**Good:** Progressive disclosure

```
skills/database/
├── SKILL.md (200 lines - overview)
├── reference/
│   ├── postgres.md
│   ├── mysql.md
│   ├── mongodb.md
│   └── redis.md
└── schemas/
    ├── users.md
    ├── products.md
    └── orders.md
```

Claude loads only what's needed.

---

### 5. Premature Agent Creation

**Bad:** Creating an agent for every task

```
agents/
├── issue-viewer/
├── branch-creator/
├── commit-maker/
├── pr-creator/
└── readme-updater/
```

**Why it's bad:**
- Overhead of spawning agents
- Most tasks don't need isolation
- Harder to follow workflow
- Slower execution

**Good:** Use agents only when needed:
- Context isolation (parallel work)
- Skill composition (multiple skills together)
- Specialist persona (architecture review)

**Simple tasks → Skills**
**Complex isolated work → Agents**

---

### 6. Verbose Explanations

**Bad:**

```markdown
Git is a distributed version control system that was created by Linus Torvalds in 2005. It allows multiple developers to work on the same codebase simultaneously while maintaining a complete history of all changes. When you want to save your changes, you use the git commit command, which creates a snapshot of your current working directory...
```

**Why it's bad:**
- Wastes tokens
- Claude already knows git
- Slows down loading
- Adds no value

**Good:**

```markdown
`git commit -m 'feat: add feature'`
```

**Assume Claude is smart. Only add domain-specific context.**

---

## Instruction Anti-Patterns

### 7. Offering Too Many Options

**Bad:**

```markdown
You can use pypdf, or pdfplumber, or PyMuPDF, or pdf2image, or camelot, or tabula, or...
```

**Why it's bad:**
- Decision paralysis
- Inconsistent choices
- No clear default

**Good:**

```markdown
Use pdfplumber for text extraction:

\`\`\`python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
\`\`\`

For scanned PDFs requiring OCR, use pdf2image + pytesseract instead.
```

**Provide default, mention alternative only when needed.**

---

### 8. Time-Sensitive Information

**Bad:**

```markdown
If you're doing this before August 2025, use the old API.
After August 2025, use the new API.
```

**Why it's bad:**
- Will become wrong
- Requires maintenance
- Confusing after the date

**Good:**

```markdown
## Current Method
Use v2 API: `api.example.com/v2/messages`

## Old Patterns
<details>
<summary>Legacy v1 API (deprecated 2025-08)</summary>
The v1 API: `api.example.com/v1/messages`
No longer supported.
</details>
```

---

### 9. Inconsistent Terminology

**Bad:** Mixing terms for the same thing

```markdown
1. Get the API endpoint
2. Call the URL
3. Hit the API route
4. Query the path
```

**Why it's bad:**
- Confusing
- Looks like different things
- Harder to search

**Good:** Pick one term and stick with it

```markdown
1. Get the API endpoint
2. Call the API endpoint
3. Check the API endpoint response
4. Retry the API endpoint if needed
```

---

### 10. Windows-Style Paths

**Bad:**

```markdown
Run: `scripts\helper.py`
See: `reference\guide.md`
```

**Why it's bad:**
- Fails on Unix systems
- Causes errors on Mac/Linux

**Good:**

```markdown
Run: `scripts/helper.py`
See: `reference/guide.md`
```

**Always use forward slashes. They work everywhere.**

---

## Script Anti-Patterns

### 11. Punting to Claude

**Bad script:**

```python
def process_file(path):
    return open(path).read()  # Let Claude handle errors
```

**Why it's bad:**
- Script fails with no helpful message
- Claude has to guess what happened
- Inconsistent error handling

**Good script:**

```python
def process_file(path):
    try:
        with open(path) as f:
            return f.read()
    except FileNotFoundError:
        print(f"ERROR: File {path} not found")
        print("Creating default file...")
        with open(path, 'w') as f:
            f.write('')
        return ''
    except PermissionError:
        print(f"ERROR: Cannot access {path}")
        print("Using default value")
        return ''
```

**Scripts should solve problems, not punt to Claude.**

---

### 12. Magic Numbers

**Bad:**

```bash
TIMEOUT=47  # Why 47?
RETRIES=5   # Why 5?
DELAY=3.7   # Why 3.7?
```

**Why it's bad:**
- No one knows why these values
- Hard to adjust
- "Voodoo constants"

**Good:**

```bash
# HTTP requests typically complete in <30s
# Extra buffer for slow connections
TIMEOUT=30

# Three retries balances reliability vs speed
# Most intermittent failures resolve by retry 2
RETRIES=3

# Exponential backoff: 1s, 2s, 4s
INITIAL_DELAY=1
```

**Document why each value is what it is.**

---

## Model Selection Anti-Patterns

### 13. Always Using Sonnet/Opus

**Bad:**

```yaml
---
name: dashboard
model: opus  # "Just to be safe"
---
```

**Why it's bad:**
- 60x more expensive than Haiku
- 5x slower
- Wasted cost for simple task

**Good:**

```yaml
---
name: dashboard
model: haiku  # Tested: 5/5 tests passed
---
```

**Test with Haiku first. Only upgrade if needed.**

---

### 14. Never Testing Haiku

**Bad:**

```yaml
---
name: review-pr
model: sonnet  # Assumed it needs Sonnet, never tested Haiku
---
```

**Why it's bad:**
- Might work fine with Haiku
- Missing 12x cost savings
- Missing 2.5x speed improvement

**Good:**

```yaml
---
name: review-pr
model: haiku  # Tested: Haiku 4/5 (80%), good enough!
---
```

Or:

```yaml
---
name: review-pr
model: sonnet  # Tested: Haiku 2/5 (40%), Sonnet 4/5 (80%)
---
```

**Always test Haiku first, document results.**

---

## Progressive Disclosure Anti-Patterns

### 15. Deeply Nested References

**Bad:**

```
SKILL.md → advanced.md → details.md → actual-info.md
```

**Why it's bad:**
- Claude may partially read nested files
- Information might be incomplete
- Hard to navigate

**Good:**

```
SKILL.md → {advanced.md, reference.md, examples.md}
```

**Keep references one level deep from SKILL.md.**

---

### 16. No Table of Contents for Long Files

**Bad:** 500-line reference file with no structure

```markdown
# Reference

(500 lines of content with no navigation)
```

**Why it's bad:**
- Hard to preview
- Claude might miss sections
- User can't navigate

**Good:**

```markdown
# Reference

## Contents
- Authentication and setup
- Core methods
- Advanced features
- Error handling
- Examples

## Authentication and Setup
...
```

**Files >100 lines should have TOC.**

---

## Checklist to Avoid Anti-Patterns

Before publishing a skill:

- [ ] Not overly broad (does one thing well)
- [ ] Instructions are specific (not vague)
- [ ] Skill references use `@` syntax
- [ ] Under 500 lines (or uses progressive disclosure)
- [ ] Only creates agents when needed
- [ ] Concise (assumes Claude knows basics)
- [ ] Provides default, not 10 options
- [ ] No time-sensitive information
- [ ] Consistent terminology
- [ ] Forward slashes for paths
- [ ] Scripts handle errors, don't punt
- [ ] No magic numbers in scripts
- [ ] Tested with Haiku first
- [ ] References are one level deep
- [ ] Long files have table of contents