--- name: token-efficiency description: Token optimization best practices for cost-effective Claude Code usage. Automatically applies efficient file reading, command execution, and output handling strategies. Includes model selection guidance (Opus for learning, Sonnet for development/debugging). Prefers bash commands over reading files. version: 1.5.0 allowed-tools: Read, Grep, Glob, Bash --- # 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 check metadata first? (file size, line count) 9. Can I filter before reading? (grep, head, tail) 10. Can I read just the structure? (first 50 lines, function names) 11. Can I summarize instead of showing raw data? 12. Does the user really need the full content? --- ## Cost Impact | Approach | Tokens/Week | Notes | |----------|-------------|-------| | **Wasteful** (Read/Edit/Write everything) | 500K | Reading files unnecessarily | | **Moderate** (filtered reads only) | 200K | Grep/head/tail usage | | **Efficient** (bash commands + filters) | 30-50K | Using cp/sed/awk instead of Read | **Applying these rules reduces costs by 90-95% on average.** --- ## Implementation **This skill automatically applies these optimizations when:** - Reading log files - Executing commands with large output - Navigating codebases - Debugging errors - Checking system status **You can always override by saying:** - "Show me the full output" - "Read the entire file" - "I want verbose mode" - "Don't worry about tokens" --- ## Supporting Files | File | Content | When to load | |------|---------|-------------| | [strategies.md](strategies.md) | Detailed bash command strategies, file operation patterns, sed/awk examples, Jupyter notebook manipulation, safe glob patterns, macOS/Linux compatibility | When implementing specific file operations or need detailed bash patterns | | [learning-mode.md](learning-mode.md) | Strategic file selection, targeted pattern learning workflows, broad repository exploration strategies, repository type identification | When entering learning mode or exploring a new codebase | | [examples.md](examples.md) | Extensive token savings examples with before/after comparisons, targeted learning examples (Galaxy wrappers, API patterns), cost calculations | When demonstrating token savings or learning from examples | | [project-patterns.md](project-patterns.md) | Analysis file organization, task management with TodoWrite, background process management, repository organization, MANIFEST system, efficient file operations | When organizing projects, managing long-running tasks, or setting up navigation patterns | --- ## Summary **Core motto: Right model. Right tool. Filter first. Read selectively. Summarize intelligently.** **Model selection (highest impact):** - **Use Opus for learning/understanding** (one-time investment) - **Use Sonnet for development/debugging/implementation** (default) **Tool selection (primary optimization):** - **Creating NEW files** -> Write tool directly - **LOW-COST operations** (< 100 lines) -> Claude context directly - **Modifying CODE files** -> Read + Edit (always) - **Modifying SMALL data files** (< 100 lines) -> Read + Edit is fine - **Modifying LARGE data files** -> bash commands (sed, awk, grep) - **Modifying CRITICAL DATA** -> bash commands + log file - **Complex edits** -> Read + Edit tools **Secondary rules:** - Filter before reading (grep, head, tail) - Read with limits when needed - Summarize instead of showing raw output - Use quiet modes for commands - Strategic file selection for learning By following these guidelines, users can get 5-10x more value from their Claude subscription while maintaining high-quality assistance.