token-efficiency

What this skill does

# Token Efficiency Expert

This skill provides token optimization strategies for cost-effective Claude Code usage across all projects. These guidelines help minimize token consumption while maintaining high-quality assistance.

## Core Principle

**ALWAYS follow these optimization guidelines by default unless the user explicitly requests verbose output or full file contents.**

Default assumption: **Users prefer efficient, cost-effective assistance.**

---

## Model Selection Strategy

**Use the right model for the task to optimize cost and performance:**

### Opus - For Learning and Deep Understanding

**Use Opus when:**
- Learning new codebases - Understanding architecture, code structure, design patterns
- Broad exploration - Identifying key files, understanding repository organization
- Deep analysis - Analyzing complex algorithms, performance optimization
- Reading and understanding - When you need to comprehend existing code before making changes
- Very complex debugging - Only when Sonnet can't solve it or issue is architectural

### Sonnet - For Regular Development Tasks (DEFAULT)

**Use Sonnet (default) for:**
- Writing code, editing and fixing, debugging, testing, documentation, deployment, general questions

**Typical session pattern:**
1. **Start with Opus** - Spend 10-15 minutes understanding the codebase (one-time investment)
2. **Switch to Sonnet** - Use for ALL implementation, debugging, and routine work
3. **Return to Opus** - Only when explicitly needed for deep architectural understanding

**Savings: ~50% token cost vs all-Opus usage.**

---

## Skills and Token Efficiency

**Myth:** Having many skills in `.claude/skills/` increases token usage.

**Reality:** Skills use **progressive disclosure** - Claude sees only skill descriptions at session start (~155 tokens for 4 skills). Full skill content loaded only when activated.

**It's safe to symlink multiple skills to a project.** Token waste comes from reading large files unnecessarily, not from having skills available.

---

## Token Optimization Rules (Quick Reference)

### 1. Use Quiet/Minimal Output Modes
Use `--quiet`, `-q`, `--silent` flags by default. Only use verbose when user explicitly asks.

### 2. NEVER Read Entire Log Files
Always filter before reading: `tail -100`, `grep -i "error"`, specific time ranges.

### 3. Check Lightweight Sources First
Check `git status --short`, `package.json`, `requirements.txt` before reading large files.

### 4. Use Grep Instead of Reading Files
Search for specific content with Grep tool instead of reading entire files.

### 5. Read Files with Limits
Use offset and limit parameters. Check file size with `wc -l` first.

### 6. Use Bash Commands Instead of Reading Files
**CRITICAL OPTIMIZATION** for pure transformations and inspection. Reading files costs tokens; bash commands don't.

| Operation | Wasteful | Efficient |
|-----------|----------|-----------|
| Copy file | Read + Write | `cp source dest` |
| Replace text | Read + Edit | `sed -i '' 's/old/new/g' file` |
| Append | Read + Write | `echo "text" >> file` |
| Delete lines | Read + Write | `sed -i '' '/pattern/d' file` |
| Merge files | Read + Read + Write | `cat file1 file2 > combined` |
| Count lines | Read file | `wc -l file` |
| Check content | Read file | `grep -q "term" file` |
| Inspect JSON | Read + parse mentally | `python3 -c "import json; ..."` or `jq` |

**When to break this rule — prefer Read + Edit instead:**
- **Code edits** (`.py`, `.js`, `.xml`, `.ga`, `.tsx`, etc.) where the user benefits from seeing a reviewable diff. The cost of reading a small file is worth the reviewability.
- **Validation matters** — when a syntactic mistake would corrupt the file (workflow JSON, config schemas).
- **Interactive review** — the user explicitly wants to see what changed.

The right framing is **scope-based** (see next section), not "always bash" or "always Read+Edit". For more detailed strategies and patterns, see [strategies.md](strategies.md).

### 7. Filter Command Output
Limit scope: `head -50`, `find . -maxdepth 2`, `tree -L 2`.

### 8. Summarize, Don't Dump
Provide structured summaries of directory contents, code structure, command output.

### 9. Use Head/Tail for Large Output
`head -100`, `tail -50`, sample from middle with `head -500 | tail -100`.

### 10. Use JSON/Data Tools Efficiently
Extract specific fields: `jq '.metadata'`, `jq 'keys'`. For CSV: `head -20`, `wc -l`.

### 11. Optimize Code Reading
Get overview first (find, grep for classes/functions), read structure only, search for specific code, read only relevant sections.

### 12. Use Task Tool for Exploratory Searches
Use Task/Explore subagent for broad codebase exploration. Saves 70-80% tokens vs direct multi-file exploration.

### 13. Efficient Scientific Literature Searches
Batch 3-5 related searches in parallel. Save results immediately. Document "not found" items.

For detailed strategies, bash patterns, and extensive examples, see [strategies.md](strategies.md).

---

## Scope-Based Tool Selection

The choice between bash and Read+Edit isn't about token cost alone — it's about whether the user benefits from seeing the change. Match the tool to the scope of work:

| Scope | Preferred tool | Why |
|---|---|---|
| Read-only inspection of structured data (JSON, YAML, JSONL, large logs) | `python3 -c`, `jq`, `grep`, `awk` | Bash output is filterable; no risk of misediting source files. Inline `python3 -c` for JSON inspection is faster and cheaper than Read+parse. |
| In-place edit of CODE (`.py`, `.js`, `.xml`, `.ga`, `.tsx`) | Read + Edit | User sees a reviewable diff; syntactic mistakes are caught early. |
| Transformation of large data files (CSV, big JSON, BAM-derived TSV) | `sed`, `awk`, `python3` script | Reading the whole file would cost thousands of tokens. |
| New file from scratch | Write tool | One round-trip; bash heredocs add no value and aren't reviewable. |

**Quick rule**: if the user would want to see and approve the change, use Read+Edit. If it's pure data wrangling or inspection, use bash/python.

## Decision Tree for File Operations

**Ask yourself:**
1. **Creating new file?** -> Write tool
2. **Low-cost operation** (< 100 lines output)? -> Use Claude context directly
3. **Modifying code file** (.py, .js, .xml)? -> Read + Edit (always)
4. **Modifying small data file** (< 100 lines)? -> Read + Edit is fine
5. **Modifying critical data** (genome stats, enriched tables)? -> bash + log file
6. **Modifying large data file?** -> sed/awk
7. **Copying/moving files?** -> cp/mv

---

## When to Override These Guidelines

**Override efficiency rules when:**

1. **User explicitly requests full output** ("Show me the entire log file")
2. **Filtered output lacks necessary context** (error references missing line numbers)
3. **File is known to be small** (< 200 lines)
4. **Learning code structure and architecture** - Prioritize understanding over efficiency

**In learning mode:**
- Read 2-5 key files fully to establish understanding
- Use grep to find other relevant examples
- Summarize patterns found across many files
- After learning phase, return to efficient mode for implementation
- For detailed learning mode strategies, see [learning-mode.md](learning-mode.md)

**In cases 1-3, explain token cost to user and offer filtered view first.**

---

## Quick Reference Card

**Model Selection (First Priority):**
- **Learning/Understanding** -> Use Opus
- **Development/Debugging/Implementation** -> Use Sonnet (default)

**Before ANY file operation, ask yourself:**

1. Am I creating a NEW file? -> Write tool directly
2. Is this a LOW-COST operation? (< 100 lines) -> Use Claude context directly
3. Am I modifying a CODE file? -> Read + Edit (always)
4. Am I modifying a SMALL data file? (< 100 lines) -> Read + Edit is fine
5. Am I modifying CRITICAL DATA? -> bash + log file
6. Am I modifying a LARGE data file? -> bash commands (99%+ savings)
7. Am I copying/merging files? -> cp/cat, not Read/Write
8. Can I che