SKILL.md
implicit-token-savings
Bias every coding session toward the smallest command that answers the real question.
Prefer inventories, summaries, scoped searches, and path-selective test commands before full file dumps, wide diffs, or whole-repo test runs.
Decision Tree
What do you need right now?
- Repo shape, top-level files, or candidate paths
- Start with ls -1, tree -L 2, or rg --files - Read references/filesystem.md
- A specific symbol, literal, stack trace, or TODO
- Start with rg -n - Read references/filesystem.md
- A file excerpt or line range
- Prefer the harness's targeted read tool if one exists - Otherwise use sed -n 'start,endp' file, head -n 80, or tail -n 80 - Read references/filesystem.md
- Working tree state, scope of change, or recent history
- Start with git status --short, git diff --stat, git diff --name-only, or git log --oneline - Read references/git.md
- Staging, committing, or pushing
- Stage only the intended paths - Review the staged summary before the commit - Push HEAD instead of spelling the branch when the remote is already known - Read references/git.md
- Test, lint, or container health for a specific stack
- Start with the narrowest stack-native command that exists: cargo test, npm test, ruff check, pytest, go test, or docker ps - Read references/runners.md
- The preferred command is missing
- Follow the fallback matrix - Read references/patterns.md
Default Operating Rules
- Inventory before contents. Ask "which path?" before "what does the whole file say?"
- Scope before detail. Prefer
--files,--name-only,--stat, and explicit paths before raw output. - Search before read. Use
rgto identify the few files worth opening. - Summarize before hunk. Use
git diff --statorgit diff --name-onlybeforegit diff. - Narrow test surfaces aggressively. Run the smallest path, package, test name, or pattern that can answer the question.
- Prefer machine-readable output when another tool or script will consume it:
--json,--format '{{json .}}',jq -r. - Escalate in steps: terse, then structured, then full output.
- If a preferred tool is absent, use the nearest cheaper equivalent rather than stalling.
Quick Reference
| Need | Start here | Escalate only if needed | Why | |
|---|---|---|---|---|
| Top-level repo inventory | ls -1 |
ls -lah, then tree -L 2 |
File names beat decorative output when you just need bearings | |
| Directory shape | tree -L 2 path/ |
tree -a -L 3 path/ |
Depth caps keep structure readable | |
| Candidate paths only | rg --files path/ |
`rg --files path/ \ | rg 'pattern'` | Avoid opening file contents at all |
| Text or symbol search | rg -n -F 'needle' path/ |
rg -n 'regex' path/ |
Match first, read later | |
| File excerpt | sed -n '1,80p' file |
head -n 120 file, then full read |
Pull only the needed slice | |
| Working tree state | git status --short --branch |
git status |
Short form is enough for most decisions | |
| Change scope | git diff --stat |
git diff --name-only, then git diff -- path |
Summaries first, hunks last | |
| Recent history | git log --oneline --decorate -n 15 |
git log --stat -- path |
Commit headlines answer many questions quickly | |
| Stage and review | git add -- path && git diff --cached --stat |
git diff --cached -- path |
Review only what you are about to commit | |
| Push current branch | git push -u origin HEAD |
git remote -v, then explicit branch push |
HEAD avoids branch-name lookup noise |
|
| Node test surface | npm test -- --help |
npm test -- <runner-args> |
Confirm how the project forwards args before widening | |
| Rust test surface | cargo test name -- --nocapture |
cargo test package::module::name |
Target a single test before a suite | |
| Python lint surface | ruff check path/ |
ruff check path/ --fix |
Keep fixes explicit | |
| Python test surface | pytest -q tests/test_file.py -k expr |
pytest -q tests/ |
Start with a file or expression, not the whole suite | |
| Go test surface | go test ./pkg/... -run Pattern |
go test ./... |
Package and -run filters cut noise |
|
| Container inventory | docker ps --format '{{json .}}' |
docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}' |
Structured rows are easier to filter or summarize |
Reading Guide
| Task | Read |
|---|---|
| Repo shape, search, and targeted file reads | references/filesystem.md |
| Compact git status, diff, history, staging, and push patterns | references/git.md |
| Narrow test, lint, and container commands | references/runners.md |
| Fallbacks, escalation ladders, and session choreography | references/patterns.md |
| Missing results, over-compression mistakes, and command traps | references/gotchas.md |
Verified Environment
- Verified locally on April 19, 2026 in a Unix-like shell.
- Found during verification:
/bin/ls,tree 2.2.1,ripgrep 15.1.0,git 2.53.0,npm 11.7.0,docker 28.5.2, andjq 1.8.1. - Not on
PATHduring verification:cargo,ruff,pytest, andgo. - Re-run
python3 scripts/probeimplicittoken_savings.py --format prettyto refresh availability and behavior on the current machine.
Gotchas
rgrespects ignore rules. Missing results usually need--hidden,-u, or--debug, not a tool switch.treeis for shape, not truth. Cap depth early or you will spend tokens on directory art.sed -nis cheaper thancatwhen you need a slice, but repeated slicing can cost more than one full read once you know the exact short file you need.git diff --stathides semantics. Escalate to a path-specific diff before drawing conclusions about behavior.npm testforwards extra runner flags only after--.docker pscan succeed while the container you care about is unhealthy. ReadStatus, not just presence.git add .is the opposite of token discipline when only one file matters. Stage explicit paths.
Helper Scripts
scripts/probeimplicittoken_savings.pydetects available tools and verifies compact command behavior on temporary local fixtures.scripts/validate.pychecks packaging, required files, and syntax.scripts/test_skill.pyruns validation, eval coverage checks, cross-reference checks, and the probe suite.templates/session-checklist.mdis a reusable checklist for starting a low-noise coding session.