architecture/old2/skills/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

---
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

---
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:

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:

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:

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:

@~/.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:

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:

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

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

---

Instruction Anti-Patterns

7. Offering Too Many Options

Bad:

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:

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:

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:

## 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

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

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:

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

Why it's bad:

• Fails on Unix systems
• Causes errors on Mac/Linux

Good:

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

Always use forward slashes. They work everywhere.

---

Script Anti-Patterns

11. Punting to Claude

Bad script:

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:

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:

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:

# 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:

---
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:

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

Test with Haiku first. Only upgrade if needed.

---

14. Never Testing Haiku

Bad:

---
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:

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

Or:

---
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

# Reference

(500 lines of content with no navigation)

Why it's bad:

• Hard to preview
• Claude might miss sections
• User can't navigate

Good:

# 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