Token Efficiency

Load this skill at session start. Token waste impacts cost and speed.

OpenCode Read Protection

OpenCode requires reading a file before editing/writing it (for existing files). Partial reads satisfy this requirement - but you must read the section you intend to change.

Why this matters: The protection prevents overwriting content you haven't seen. If you read lines 1-50 but edit lines 200-250, you risk corrupting code you never reviewed.

# CORRECT - read the area you're changing
read({ filePath: "src/app.ts", offset: 200, limit: 50 })
edit({ filePath: "src/app.ts", oldString: "// line 220 content", newString: "..." })

# WRONG - reading unrelated section then editing elsewhere
read({ filePath: "src/app.ts", offset: 0, limit: 50 })
edit({ filePath: "src/app.ts", oldString: "// line 220 content", newString: "..." })  # Dangerous!

File Reading Guidelines

When Full Reads Are Acceptable

• Small files (<50 lines)
• Data files you need to analyze completely (JSON, CSV, config)
• Files where you need to understand the full structure
• New/unfamiliar codebases where you need context

When to Use Partial Reads

• Large files (>100 lines) where you're editing a specific section
• Files you've already read in this session
• When grep/codegraph already told you the line numbers

Tool Priority for Finding Code

1. grep → Find line numbers and file paths
2. codegraphcontext → Find symbol definitions and relationships
3. glob → Find file paths by pattern
4. read with offset/limit → Get targeted content

Read Tool Usage

# Full read - fine for small files or when you need everything
read({ filePath: "config.json" })

# Partial read - preferred for large files
read({ filePath: "src/app.ts", offset: 100, limit: 50 })

Edit vs Write Tool Selection

Use edit when:

• Modifying existing code (most common case)
• You know the exact text to replace
• Changing a specific section of a large file

Edit workflow:

1. grep/codegraph → find location (line ~245)
2. read with offset/limit → get the lines around your target (read what you'll change)
3. edit({ filePath, oldString: "<exact match from step 2>", newString: "<replacement>" })

Important: Your oldString must come from what you actually read. Don't guess at content.

Use write when:

• Creating new files (no prior read needed)
• Replacing entire small file content
• File is small AND you're changing most of it

Token Comparison

Common Patterns

Editing a function you found with grep:

grep "handleRequest" src/ → found at src/handler.ts:145
read({ filePath: "src/handler.ts", offset: 140, limit: 50 })
edit({ filePath: "src/handler.ts", oldString: "...", newString: "..." })

Creating a new file:

write({ filePath: "src/new-feature.ts", content: "..." })
# No prior read needed for new files

Analyzing a data file:

# Full read is appropriate here
read({ filePath: "data/config.json" })

Anti-Patterns to Avoid

❌ Reading 500-line file to change 5 lines (use partial read) ❌ Using write to modify existing large files (use edit) ❌ Re-reading same file sections repeatedly (remember what you read) ❌ Reading full file "just in case" when grep already found the lines