Route file and shell operations by capability rather than vendor-specific tool names.
Why This Skill Is Needed & Target State
Why this skill is needed: Agents often assume hardcoded tool names (e.g. str_replace_editor, Bash, readFile) that do not exist across different host platforms. This causes runtime execution crashes and unsafe mutations.
Target state: Workspace operations route through normalized capability tiers (read, search, patch, shell) respecting read-only boundaries and evidence collection across any host runtime.
Capability Order
Prefer the narrowest operation that fits:
- Read: a known file or line range
- List: a directory or workspace scope
- Search: broad concepts when wording or location is uncertain
- Grep: exact-match known terms, symbols, fields, or patterns
- Patch: a focused existing section
- Write: only when creation or replacement is authorized
- Shell: repository commands when narrower tools are insufficient
- Python / Deterministic: computation for parsing, hashes, package inspection, or verification
Do not use shell or Python merely to imitate a safer read/search/file operation.
Read-Only First
Before mutation:
- inspect repository instructions
- locate relevant files
- read enough context to preserve unrelated work
- distinguish source from generated/vendor files
- identify the smallest mutation that completes the request
Mutation Boundary
Treat write, patch, delete, move, rename, format, and mutating commands as state changes.
- Only mutate when the user requested or clearly authorized the change
- Prefer a focused patch over a broad rewrite
- Never write credentials or secrets into source, examples, manifests, logs, or artifacts
- After mutation, read changed areas and run relevant checks when the host can execute them
Evidence Rule
Never say a file was read, searched, modified, tested, or executed unless the host produced evidence of that action.
If the required capability is unavailable:
- do not invent a tool or manifest permission
- use another capability only if it preserves semantics and safety
- otherwise keep the dependent result unverified