Chisel Agent Skill

You have access to a Chisel MCP server. Chisel exposes precision filesystem tools designed to minimise token cost and maximise safety. The cardinal rule: never read a full file when you only need part of it, and never write a full file when you only need to change part of it.

⚠️ shell_exec has no shell interpreter. Pipe (|), &&, ||, $(), and all shell metacharacters are passed as literals to the process — they are never interpreted. Each shell_exec call runs exactly one command. Compose multi-step logic across separate calls.

Tool Selection

Need to find something in a file or directory?
  └─ shell_exec (grep / find / sed / awk / stat / ls)

Need to edit an existing file?
  ├─ Small targeted change (< whole file)  → patch_apply
  │    └─ patch_apply fails twice on a small file?  → write_file (see below)
  └─ Overwrite entirely / file is tiny     → write_file

Need to add content to the end of a file?
  └─ append

Need to create a directory?
  └─ create_directory

Need to rename or relocate a file?
  └─ move_file

Reading — Never Fetch What You Don't Need

Always start with the minimum slice required. Only escalate if the first call does not give enough context.

Avoid calling cat on a file longer than ~50 lines. Use sed -n 'M,Np' to window in, or cat -n on short files to get line numbers before writing a patch.

Editing — Prefer Diffs Over Full Rewrites

patch_apply — primary edit tool

Send only the changed lines. The file is written atomically; a hunk mismatch returns PatchFailed and leaves the original untouched.

--- a/src/main.rs
+++ b/src/main.rs
@@ -12,7 +12,7 @@
 fn main() {
-    let port = 3000;
+    let port = 8080;
     start_server(port);
 }

Rules for a valid patch:

• Context lines (no prefix) must match the file exactly, including whitespace.
• @@ -L,N +L,N @@ line numbers must be exact for the current file state — both the start line and the count. A wrong line number in the header produces PatchFailed even if the content lines are correct. Always run grep -n or cat -n first to confirm the real line numbers before writing the hunk header.
• To create a new file use --- /dev/null as the source header; the file must not exist.
• You can include multiple @@ hunks in a single call — all are applied atomically.

When PatchFailed is returned:

1. Re-read the exact lines with grep -n or sed -n 'L-3,L+3p'.
2. Regenerate the patch from the actual content — both context lines and hunk header.
3. If PatchFailed happens twice on a file under ~100 lines: stop debugging the hunk. Use cat -n to read the whole file, correct it in full, and use write_file instead.

write_file — full overwrite

Use when:

• Creating a new file with substantial initial content.
• The change touches so much of the file that a diff would be larger than the file itself.
• The file is short (< ~30 lines) and a full rewrite is cleaner.
• patch_apply has failed twice on a short file — write_file is the safe recovery path.

append

Use for log entries, appending lines to a config, or adding to an incrementally-built file. The file must already exist.

In-place Transformation with shell_exec sed -i

For bulk replacements (rename a symbol, fix a repeated pattern), sed mutates the file directly — no diff needed.

⚠️ sed -i has different signatures on macOS (BSD sed) vs Linux (GNU sed). Use exactly the forms below — do not improvise alternatives.

Platform	Argument array
Linux (GNU sed)	["-i", "s/Old/New/g", "/abs/path/file"]
macOS (BSD sed)	["-i", "", "s/Old/New/g", "/abs/path/file"]

On macOS the empty string "" is the backup-suffix argument (meaning: no backup file). Chisel passes it through to BSD sed correctly as a separate argument — do not omit it, do not replace it with -i.bak, and do not combine it with -i into a single arg like "-i''". Any deviation produces a cryptic BSD sed parse error (command a expects \…) and wastes turns.

If you are unsure which platform you're on, use shell_exec stat ["/proc/version"] (Linux) or shell_exec uname ["-s"] to check. Alternatively, prefer patch_apply or write_file for single-file edits — they are platform-independent.

# Linux
shell_exec sed ["-i", "s/OldName/NewName/g", "/root/src/lib.rs"]

# macOS — the "" is mandatory and is passed correctly; do not second-guess this
shell_exec sed ["-i", "", "s/OldName/NewName/g", "/root/src/lib.rs"]

A successful in-place edit returns exit_code: 0 with empty stdout. Non-zero exit or any stderr output means the expression or path is wrong — fix those, do not change the -i form.

Workflow Patterns

Locate → Read slice → Patch

The standard low-token edit loop:

1. grep -n "target_symbol" /root/file — find the line number.
2. sed -n "L-5,L+10p" /root/file — read a tight window around it.
3. Verify the @@ -L,N +L,N @@ header matches exactly.
4. patch_apply — send the diff against that exact content.

Short files only: use cat -n /root/file in step 1 to see every line numbered at once — faster than a grep/sed pair when the file is < 50 lines.

Explore unfamiliar codebase

1. ls -la /root — top-level layout.
2. find /root -name "*.rs" -not -path "*/target/*" — enumerate source files.
3. grep -rn "struct MyStruct" /root/src — locate the definition.
4. sed -n "L,L+30p" /root/src/file.rs — read the struct body.

Relative paths are auto-anchored to root. . means the root itself, subdir/file means root/subdir/file. Absolute paths also work. Traversal (../escape) is always blocked.

Create a new file with boilerplate

Use write_file. Once it exists, all subsequent edits go through patch_apply.

Rename a symbol across many files

Preferred — one call via find -exec … {} +:

find -exec cmd {} + batches all matched paths into a single command invocation. No shell, no loop, one shell_exec call regardless of how many files match.

# macOS (BSD sed)
shell_exec find ["/root/src", "-name", "*.rs", "-exec", "sed", "-i", "", "s/OldName/NewName/g", "{}", "+"]

# Linux (GNU sed)
shell_exec find ["/root/src", "-name", "*.rs", "-exec", "sed", "-i", "s/OldName/NewName/g", "{}", "+"]

The {} placeholder and + terminator are passed literally to find — they are not shell metacharacters and require no escaping.

Fallback — one call per file (only if find -exec is unavailable or the pattern needs per-file logic):

1. grep -rl "OldName" /root/src — get the file list.
2. For each file:
   • Linux: sed ["-i", "s/OldName/NewName/g", "/root/src/file.rs"]
   • macOS: sed ["-i", "", "s/OldName/NewName/g", "/root/src/file.rs"]

Scaffold a directory tree

create_directory /root/src/handlers
write_file /root/src/handlers/mod.rs "..."
write_file /root/src/handlers/auth.rs "..."

Error Handling

What Not To Do