537 lines
9.1 KiB
Markdown
537 lines
9.1 KiB
Markdown
# 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
|