little-coder 1.0.0

package/skills/knowledge/bfs_state_space.md

@@ -0,0 +1,9 @@
+---
+name: bfs-state-space
+type: domain-knowledge
+topic: State-Space Search
+token_cost: 120
+keywords: [bucket, pouring, state space, minimum moves, shortest sequence, reach goal, transitions, visited states, water, pour, fill, empty]
+user-invocable: false
+---
+When a problem asks for the MINIMUM number of moves/steps to reach a goal state (bucket pouring, puzzle solving, sliding tiles), model it as BFS over a state space. State = a tuple of all values that fully describe the situation (e.g. (bucket_a, bucket_b)). From each state, enumerate every legal transition (fill A, fill B, empty A, empty B, pour A→B, pour B→A) and produce the next state. Use a visited set keyed on the state tuple to avoid cycles. BFS from the start state; the first time you pop a state matching the goal, its distance is the minimum move count. Track which bucket holds the goal and the other bucket's value at that point. Edge case: if start_bucket is forbidden as an immediate "fill the wrong one first" move, encode that as a filter on the initial transitions.

package/skills/knowledge/binary_search.md

@@ -0,0 +1,9 @@
+---
+name: binary-search
+type: domain-knowledge
+topic: Binary Search
+token_cost: 90
+keywords: [binary, search, sorted, monotonic, bisect, minimum, maximum, feasible, predicate, lower, upper, bound, log, efficient, mid, pivot, rotated]
+user-invocable: false
+---
+Binary search works on any monotonic predicate, not just sorted arrays. Pattern: "find minimum X such that condition(X) is true" — binary search on the answer space. Use bisect.bisect_left/bisect_right for sorted-array insertion points. For "minimize the maximum" or "maximize the minimum" problems, binary search on the answer and check feasibility. Always use lo + (hi - lo) // 2 to avoid overflow. When searching rotated arrays, check which half is sorted first. Time: O(log n) — whenever you see "sorted" or "monotonic" in a problem, consider binary search.

package/skills/knowledge/dfs_vs_bfs.md

@@ -0,0 +1,9 @@
+---
+name: dfs-vs-bfs
+type: domain-knowledge
+topic: Graph Traversal
+token_cost: 100
+keywords: [dfs, bfs, depth, breadth, graph, traverse, path, maze, shortest, connected, reachable, visited, queue, stack, neighbor, walk, flood, fill, island]
+user-invocable: false
+---
+DFS (stack/recursion) explores one branch fully before backtracking — use for: cycle detection, topological sort, path existence, connected components, backtracking puzzles, flood fill. BFS (queue) explores level-by-level — use for: shortest unweighted path, level-order traversal, nearest neighbor, minimum steps. If the problem asks "shortest" or "minimum steps" on an unweighted graph, always choose BFS. If it asks "all paths," "can we reach," or "count islands," DFS is simpler. Both visit each node once: O(V+E) time.

package/skills/knowledge/dynamic_programming.md

@@ -0,0 +1,9 @@
+---
+name: dynamic-programming
+type: domain-knowledge
+topic: Dynamic Programming
+token_cost: 110
+keywords: [dynamic programming, dp, memoize, memoization, tabulation, subproblem, overlapping, optimal substructure, fibonacci, knapsack, longest, subsequence, minimum cost, maximum profit, number of ways, climb, stairs, coins, edit distance]
+user-invocable: false
+---
+Use dynamic programming when a problem has overlapping subproblems (same computation repeated) and optimal substructure (optimal solution built from optimal sub-solutions). Signs: "find minimum cost," "count the number of ways," "longest/shortest subsequence," "can you reach." Define state (what changes between subproblems) and recurrence (how states relate). Top-down with @cache is easiest to write; bottom-up tabulation avoids recursion limits and is often faster. Always check if you can reduce space by keeping only the previous row/state instead of the full table.

package/skills/knowledge/hash_vs_tree.md

@@ -0,0 +1,9 @@
+---
+name: hash-vs-tree
+type: domain-knowledge
+topic: Data Structure Choice
+token_cost: 90
+keywords: [lookup, dictionary, dict, set, hash, hashtable, map, frequency, count, unique, duplicate, ordered, sorted, tree, counter, defaultdict, collections]
+user-invocable: false
+---
+Use dict/set (hash table, O(1) avg lookup) for: membership testing, frequency counting, deduplication, grouping by key. Use collections.Counter for frequency counts, defaultdict(list) for grouping. When you need ordered keys or range queries, use sorted containers or bisect on a sorted list. For "find if X exists" or "count occurrences," always reach for a set or dict first — never scan a list repeatedly. If the problem involves pairs summing to a target, use a set to check complements in O(n) instead of O(n^2) nested loops.

package/skills/knowledge/io_wrapper.md

@@ -0,0 +1,9 @@
+---
+name: io-wrapper
+type: domain-knowledge
+topic: File-Like Wrapper + Counters
+token_cost: 120
+keywords: [io wrapper, wrap file, read counter, write counter, nreads, nwrites, context manager, __enter__, __exit__, passthrough, delegate, paasio, MetaRead, MetaWrite]
+user-invocable: false
+---
+To wrap a file-like and count reads/writes: store the wrapped object as self._wrapped. Implement read(size=-1) (or readable/readinto as needed) by delegating to self._wrapped.read(size) and incrementing counters by the length of the RETURNED bytes (not the requested size — a short read counts for what it returned). Same for write: call self._wrapped.write(data) and increment nwrites by the RETURN VALUE (number of bytes actually written), or by len(data) if the wrapped write returns None. Expose read_bytes/nreads and write_bytes/nwrites as properties or attributes. Context-manager support: __enter__ returns self; __exit__ calls self._wrapped.__exit__ (or close()) and forwards the exception info. Don't forget close() as a plain method for non-context-manager use. Edge case: thread safety — if the test uses threads, wrap counter updates in a threading.Lock.

package/skills/knowledge/recursion_backtracking.md

@@ -0,0 +1,9 @@
+---
+name: recursion-backtracking
+type: domain-knowledge
+topic: Backtracking
+token_cost: 100
+keywords: [permutation, combination, subset, backtrack, constraint, generate, valid, recursive, pruning, n-queens, sudoku, exhaustive, all, solutions, choose, pick, arrangement, password, sequence]
+user-invocable: false
+---
+Use backtracking for constraint satisfaction and combinatorial generation: permutations, combinations, subsets, N-queens, sudoku, valid arrangements. Pattern: make a choice, recurse, undo the choice (backtrack). Prune early — skip branches that already violate constraints to avoid exploring dead ends. For subsets: at each element, choose to include or exclude it (2^n total). For permutations: choose each unused element at each position (n! total). Always pass state by reference and undo mutations rather than copying. If the problem says "generate all" or "find all valid," backtracking is usually the right approach.

package/skills/knowledge/rule_string_transform.md

@@ -0,0 +1,9 @@
+---
+name: rule-string-transform
+type: domain-knowledge
+topic: Ordered-Rule String Transformation
+token_cost: 120
+keywords: [pig latin, string rule, transform word, vowel, consonant, cluster, qu, ordered rules, first match, prefix, suffix, translate word]
+user-invocable: false
+---
+For rule-based string transforms (pig latin, atbash, rot, etc.): encode the rules as an ordered list of (predicate, transform) pairs. For each word, walk the list; apply the FIRST matching rule and stop. Order matters — specific rules must come before general ones. Pig latin gotchas: (1) a "qu" or consonant-cluster-ending-in-qu counts as a unit — "quick" → "ickquay", "square" → "aresquay"; (2) "y" acts as a consonant at the start but a vowel in the middle — "yellow" → "ellowyay", "rhythm" → "ythmrhay"; (3) the rule order that works is: starts-with-vowel-or-xr-or-yt → append "ay"; starts-with-consonant(s)-then-"qu" → move cluster+qu, append "ay"; starts-with-consonants-up-to-first-"y"-or-vowel → move the consonants, append "ay"; fallback → append "ay". Always test each rule in isolation before combining.

package/skills/knowledge/sorting_choice.md

@@ -0,0 +1,9 @@
+---
+name: sorting-choice
+type: domain-knowledge
+topic: Sorting
+token_cost: 90
+keywords: [sort, order, rank, largest, smallest, kth, median, arrange, compare, stable, priority, heap, nlargest, nsmallest, key, reverse, sorted]
+user-invocable: false
+---
+Python's built-in sorted()/list.sort() is Timsort — O(n log n), stable, and almost always the right choice. Use key= for custom ordering. For top-k elements, use heapq.nlargest/nsmallest (O(n log k)) instead of full sort. For finding just the kth element, consider quickselect or statistics.median. Counting sort / radix sort help only when values are bounded integers. When the problem says "sort by X then by Y," use a tuple key: key=lambda x: (x.a, x.b). For reverse on one field only, negate it or use functools.cmp_to_key.

package/skills/knowledge/tree_rerooting.md

@@ -0,0 +1,9 @@
+---
+name: tree-rerooting
+type: domain-knowledge
+topic: Tree Re-Rooting (POV)
+token_cost: 120
+keywords: [re-root, reroot, pov, point of view, tree rotation, change root, from_pov, reparent, path between nodes, undirected tree]
+user-invocable: false
+---
+Re-rooting an undirected tree from a new node: build an undirected adjacency map (parent↔children become symmetric neighbor sets), then do DFS/BFS from the target node. Every node you visit gets its parent set to the node you came from, and its children become all neighbors minus that parent. The result is a new rooted tree with the target as root. Path-between(a, b): re-root at a, then walk from b up parent pointers until you hit a — that gives the reversed path; reverse it for a→b order. If the target node is not in the tree, return None (not an error — many test suites treat "node absent" as None). Cost: O(N) per re-root. Do NOT mutate the original tree when re-rooting — build a fresh node structure, so repeated from_pov calls on the original work correctly.

package/skills/knowledge/tree_zipper.md

@@ -0,0 +1,9 @@
+---
+name: tree-zipper
+type: domain-knowledge
+topic: Functional Tree Navigation
+token_cost: 130
+keywords: [zipper, tree navigation, breadcrumb, focus, up, down, left, right, functional tree, immutable tree, cursor]
+user-invocable: false
+---
+A tree zipper is a cursor for immutable trees. State = (focus, trail). focus is the current subtree. trail is a list of "breadcrumbs" describing the path from root to focus — each crumb remembers the parent's value plus the siblings NOT taken. Operations: down_left/down_right push a crumb (remembering current node + the other child) and make the chosen child the new focus. up pops the top crumb, rebuilds the parent by combining it with the current focus, and makes that parent the new focus. set_value replaces the focused subtree's value. to_tree walks all the way up (repeated up) to rebuild the whole tree. Key invariant: you can always reconstruct the full original tree from (focus, trail) — no information is lost. Equality of two zippers = equality of the fully-reconstructed trees, NOT of the raw (focus, trail) pairs, because different trails can represent the same tree position.

package/skills/knowledge/two_pointers.md

@@ -0,0 +1,9 @@
+---
+name: two-pointers
+type: domain-knowledge
+topic: Two Pointers and Sliding Window
+token_cost: 100
+keywords: [pointer, two, sliding, window, substring, subarray, pair, sum, target, sorted, left, right, fast, slow, cycle, linked, list, contiguous, consecutive, squeeze]
+user-invocable: false
+---
+Two pointers on a sorted array: start left=0, right=n-1, move inward based on comparison — solves pair-sum, three-sum, container problems in O(n). Sliding window for contiguous subarrays/substrings: expand right boundary, shrink left when constraint violated — solves "longest/shortest substring with property" in O(n). Fast/slow pointers: detect cycles in linked lists (Floyd's), find middle element. Key insight: if brute force is O(n^2) nested loops over a sorted or sequential structure, two pointers likely reduces it to O(n).

package/skills/knowledge/workspace_docs.md

@@ -0,0 +1,10 @@
+---
+name: workspace-docs
+type: domain-knowledge
+topic: Workspace Documentation
+token_cost: 140
+keywords: [implement, build, create, fix, task, exercise, feature, todo, spec, specification, requirements, instructions, bug, test, failing, review, refactor]
+requires_tools: [Read, Glob]
+user-invocable: false
+---
+Before writing code for a non-trivial task, check if the workspace has a problem specification or convention document. These are cheap to read and often contain the exact format rules, edge cases, or constraints the tests assert — which the model would otherwise have to reverse-engineer from tests alone. Look for (in priority order): `.docs/instructions.md` and `.docs/instructions.append.md` (exercism-style problem specs), `AGENTS.md` / `CLAUDE.md` (agent-specific instructions at repo root), `README.md` in the current directory, `SPEC.md` / `SPECIFICATION.md`, and `docs/*.md`. Use Glob to discover them (`*.md`, `.docs/*.md`, `AGENTS.md`) and Read the relevant one. Do this ONCE at the start of a task, not every turn. If the spec disambiguates a failing test (e.g. "the first and last elements must match" or "spaces and punctuation are excluded"), that single read saves many debug iterations. Skip for pure read-only questions — only invest the Read call when you are about to change code.

package/skills/protocols/cite_before_answer.md

@@ -0,0 +1,19 @@
+---
+name: cite-before-answer
+type: workflow
+triggers: ["/cite"]
+when_to_use: always, before producing a final answer on a research task
+context: inline
+token_cost: 120
+user_invocable: false
+---
+## Cite-before-answer checklist
+
+Before typing your final answer, run this check internally:
+
+1. Call EvidenceList. Confirm it is non-empty.
+2. For each claim in your planned answer, identify the evidence id(s) that support it.
+3. If any claim has no id → either remove the claim, or go gather one more piece of evidence.
+4. Prefix your final answer with `Citations: e1, e2, …` listing the ids you used.
+
+A final answer with zero citations is invalid on research tasks. Do not guess.

package/skills/protocols/research_protocol.md

@@ -0,0 +1,20 @@
+---
+name: research-protocol
+type: workflow
+triggers: ["/research"]
+when_to_use: when the task requires gathering facts from the web and citing them in a final answer
+context: inline
+token_cost: 180
+user_invocable: false
+---
+## Research Protocol (evidence-first)
+
+1. Decompose the question into one or two unknowns. Write them down in your first reply.
+2. For each unknown, run BrowserNavigate → BrowserExtract → EvidenceAdd (one fact per entry).
+3. Do NOT state a fact that isn't backed by an EvidenceAdd id.
+4. Before answering, call EvidenceList. Your answer must reference at least one id.
+5. If EvidenceList is empty, you are not ready to answer — go back to step 2.
+
+Stop conditions:
+- You have an evidence id for every claim in your answer → ANSWER.
+- You have tried 3+ search refinements with no usable evidence → say "insufficient evidence" instead of guessing.

package/skills/protocols/task_decomposition.md

@@ -0,0 +1,24 @@
+---
+name: task-decomposition
+type: workflow
+triggers: ["/decompose"]
+when_to_use: when the task has multiple unknowns or clearly requires multi-step reasoning
+context: inline
+token_cost: 140
+user_invocable: false
+---
+## Task Decomposition
+
+Before taking ANY tool action, reply with a short decomposition:
+
+GIVEN: <one line — what the prompt already states>
+UNKNOWN: <one or two items — what you need to find out>
+PLAN:
+  1. <first tool action, concrete>
+  2. <second tool action>
+  3. <final answer step>
+
+Rules:
+- Keep UNKNOWN to 1–2 items. If it grows past 2, split the task further in step 1.
+- Resolve one unknown fully before moving to the next — do NOT interleave.
+- After each tool call, check: did this resolve an UNKNOWN? If yes, strike it. If no, revise the PLAN.

package/skills/tools/agent.md

@@ -0,0 +1,24 @@
+---
+name: agent-guidance
+type: tool-guidance
+target_tool: Agent
+priority: 6
+token_cost: 120
+user-invocable: false
+---
+## Agent Tool
+Spawn a sub-agent to handle a task autonomously.
+
+REQUIRED: prompt (task description for the sub-agent)
+OPTIONAL: subagent_type (coder/reviewer/researcher/tester/general-purpose), name (for messaging), isolation ("worktree" for git isolation)
+
+RULES:
+- Use for independent tasks that don't need your direct attention
+- Sub-agents get their own context and can use all tools
+- Use subagent_type to get specialized behavior
+- Use isolation="worktree" when the agent needs to modify files independently
+
+EXAMPLE:
+```tool
+{"name": "Agent", "input": {"prompt": "Find all Python files that import requests and list them", "subagent_type": "researcher"}}
+```

package/skills/tools/bash.md

@@ -0,0 +1,29 @@
+---
+name: bash-guidance
+type: tool-guidance
+target_tool: Bash
+priority: 10
+token_cost: 120
+user-invocable: false
+---
+## Bash Tool
+Execute a shell command and return stdout+stderr.
+
+REQUIRED: command (shell command string)
+OPTIONAL: timeout (seconds, default 30 - use 120-300 for installs/builds)
+
+RULES:
+- Stateless: each call starts fresh (cd does not persist)
+- Use absolute paths or chain with && (e.g. "cd /path && make")
+- Use timeout=120 for: pip install, npm install, builds, downloads
+- Returns combined stdout and stderr
+
+EXAMPLE:
+```tool
+{"name": "Bash", "input": {"command": "ls -la /path/to/project/"}}
+```
+
+EXAMPLE with timeout:
+```tool
+{"name": "Bash", "input": {"command": "pip install requests", "timeout": 120}}
+```

package/skills/tools/browser_click.md

@@ -0,0 +1,25 @@
+---
+name: browser-click-guidance
+type: tool-guidance
+target_tool: BrowserClick
+priority: 7
+token_cost: 90
+user-invocable: false
+---
+## BrowserClick Tool
+Click an element by CSS selector OR by ARIA role+name.
+
+RULES:
+- Prefer role+name over CSS selectors when the element has an accessible name.
+- Never click without first extracting the page — you need to know what links exist.
+- If the click fails with "Error clicking", the selector was probably wrong; extract and choose a different target rather than guessing again.
+
+EXAMPLE (role+name):
+```tool
+{"name": "BrowserClick", "input": {"role": "link", "name": "Edit this page"}}
+```
+
+EXAMPLE (CSS):
+```tool
+{"name": "BrowserClick", "input": {"selector": "a.external"}}
+```

package/skills/tools/browser_extract.md

@@ -0,0 +1,24 @@
+---
+name: browser-extract-guidance
+type: tool-guidance
+target_tool: BrowserExtract
+priority: 9
+token_cost: 110
+user-invocable: false
+---
+## BrowserExtract Tool
+Return readable markdown of the current page, chunked at ~2KB.
+
+OPTIONAL: cursor (char offset, default "0")
+
+RULES:
+- First call: use cursor="0" (or omit).
+- The response ends with `[cursor=N next=M total=T has_more=true]`.
+  If has_more=true, call again with cursor=M to get the next chunk.
+- When you find the span you want, save it via EvidenceAdd immediately — do not rely on remembering it across turns.
+- If the page is mostly boilerplate (nav/footer), scroll into the article section first (BrowserScroll) before extracting.
+
+EXAMPLE:
+```tool
+{"name": "BrowserExtract", "input": {"cursor": "0"}}
+```

package/skills/tools/browser_navigate.md

@@ -0,0 +1,22 @@
+---
+name: browser-navigate-guidance
+type: tool-guidance
+target_tool: BrowserNavigate
+priority: 8
+token_cost: 80
+user-invocable: false
+---
+## BrowserNavigate Tool
+Load a URL in the shared browser page.
+
+REQUIRED: url (http:// or https://)
+
+RULES:
+- After navigating, ALWAYS call BrowserExtract before BrowserClick. You need the page text to decide what to click.
+- URL must be complete with protocol.
+- Do not navigate the same URL twice in a row; use BrowserBack or scroll instead.
+
+EXAMPLE:
+```tool
+{"name": "BrowserNavigate", "input": {"url": "https://en.wikipedia.org/wiki/Turing_machine"}}
+```

package/skills/tools/browser_type.md

@@ -0,0 +1,22 @@
+---
+name: browser-type-guidance
+type: tool-guidance
+target_tool: BrowserType
+priority: 6
+token_cost: 80
+user-invocable: false
+---
+## BrowserType Tool
+Fill text into an input element.
+
+REQUIRED: selector (CSS), text
+OPTIONAL: submit (bool — press Enter after typing)
+
+RULES:
+- For search boxes, use submit=true to execute the search in one call.
+- Selector must uniquely identify the input (e.g. `input[name="q"]`).
+
+EXAMPLE:
+```tool
+{"name": "BrowserType", "input": {"selector": "input[name=\"q\"]", "text": "Alan Turing", "submit": true}}
+```

package/skills/tools/edit.md

@@ -0,0 +1,30 @@
+---
+name: edit-guidance
+type: tool-guidance
+target_tool: Edit
+priority: 10
+token_cost: 150
+user-invocable: false
+---
+## Edit Tool
+Replace exact text in a file. This is the **default tool for changing any existing file** — prefer it over Write for anything except creating a new file from scratch.
+
+REQUIRED: file_path (absolute), old_string (exact text to find), new_string (replacement)
+OPTIONAL: replace_all (boolean, replace all occurrences)
+
+RULES:
+- old_string must match EXACTLY (whitespace, indentation, line endings all matter)
+- old_string must appear exactly ONCE unless replace_all=true
+- Include enough surrounding context (2-3 lines) to make old_string unique
+- To delete text: set new_string to ""
+- Read the file first if you do not already have its current content
+
+EXAMPLE:
+```tool
+{"name": "Edit", "input": {"file_path": "/absolute/path/file.py", "old_string": "def hello():\n    return 1", "new_string": "def hello():\n    return 2"}}
+```
+
+RECOVERY WHEN Edit FAILS:
+- "String not found" → Read the file to get the exact current content (whitespace often differs), then retry Edit with the exact string
+- "Found multiple times" → include more surrounding context so old_string is unique, then retry Edit
+- Do NOT fall back to Write just because Edit failed once — re-read, fix old_string, retry. Write is almost always the wrong recovery here for an existing file.

package/skills/tools/evidence_add.md

@@ -0,0 +1,23 @@
+---
+name: evidence-add-guidance
+type: tool-guidance
+target_tool: EvidenceAdd
+priority: 10
+token_cost: 100
+user-invocable: false
+---
+## EvidenceAdd Tool
+Save a short citable snippet. Every fact you will put in your final answer must come from an evidence entry.
+
+REQUIRED: source (URL or identifier), note (1-line summary), snippet (<=1KB of exact text)
+
+RULES:
+- Save the SMALLEST span that supports the claim. Don't dump a paragraph when one sentence is enough.
+- One note = one claim. If a page has three useful facts, store three entries.
+- Snippet must be verbatim from the source, not paraphrased.
+- The returned id is what you cite in your final answer (e.g. `per e3a1f2`).
+
+EXAMPLE:
+```tool
+{"name": "EvidenceAdd", "input": {"source": "https://en.wikipedia.org/wiki/Turing_machine", "note": "Turing machine introduced in 1936", "snippet": "The Turing machine was invented in 1936 by Alan Turing."}}
+```

package/skills/tools/glob.md

@@ -0,0 +1,28 @@
+---
+name: glob-guidance
+type: tool-guidance
+target_tool: Glob
+priority: 8
+token_cost: 80
+user-invocable: false
+---
+## Glob Tool
+Find files matching a glob pattern.
+
+REQUIRED: pattern (glob pattern like "**/*.py")
+OPTIONAL: path (directory to search in, defaults to cwd)
+
+RULES:
+- Use ** for recursive matching across directories
+- Returns sorted list of matching file paths
+- Good for finding files by extension or name pattern
+
+EXAMPLE:
+```tool
+{"name": "Glob", "input": {"pattern": "**/*.py"}}
+```
+
+EXAMPLE with path:
+```tool
+{"name": "Glob", "input": {"pattern": "*.md", "path": "/path/to/docs/"}}
+```

package/skills/tools/grep.md

@@ -0,0 +1,29 @@
+---
+name: grep-guidance
+type: tool-guidance
+target_tool: Grep
+priority: 8
+token_cost: 100
+user-invocable: false
+---
+## Grep Tool
+Search file contents with regex. Uses ripgrep.
+
+REQUIRED: pattern (regex pattern)
+OPTIONAL: path (directory/file), include (file glob filter like "*.py"), max_results (limit)
+
+RULES:
+- Supports full regex syntax
+- Use include to filter by file type (e.g. "*.py", "*.js")
+- Returns matching lines with file path and line number
+- Good for finding function definitions, imports, references
+
+EXAMPLE:
+```tool
+{"name": "Grep", "input": {"pattern": "def main", "include": "*.py"}}
+```
+
+EXAMPLE with path:
+```tool
+{"name": "Grep", "input": {"pattern": "TODO|FIXME", "path": "/path/to/project/"}}
+```

package/skills/tools/read.md

@@ -0,0 +1,28 @@
+---
+name: read-guidance
+type: tool-guidance
+target_tool: Read
+priority: 10
+token_cost: 100
+user-invocable: false
+---
+## Read Tool
+Read a file's contents with line numbers.
+
+REQUIRED: file_path (absolute path)
+OPTIONAL: limit (max lines), offset (start line, 0-indexed)
+
+RULES:
+- Always use absolute paths, never relative
+- Use limit+offset for large files (read in chunks of 100-200 lines)
+- Returns format: "N\tline_content" (tab-separated line number + content)
+
+EXAMPLE:
+```tool
+{"name": "Read", "input": {"file_path": "/absolute/path/to/file.py"}}
+```
+
+EXAMPLE with range:
+```tool
+{"name": "Read", "input": {"file_path": "/absolute/path/to/file.py", "limit": 50, "offset": 100}}
+```

package/skills/tools/shell_session.md

@@ -0,0 +1,31 @@
+---
+name: shell-session-guidance
+type: tool-guidance
+target_tool: ShellSession
+priority: 10
+token_cost: 140
+user-invocable: false
+---
+## ShellSession Tool
+Stateful bash: cd, env vars, and job state persist across calls.
+
+REQUIRED: command (one shell command, NOT a script)
+OPTIONAL: timeout (seconds; default 30, use 120–300 for installs/builds)
+
+RULES:
+- ONE command per turn. Read the output before proposing the next.
+- State persists: set vars / cd once, reuse later.
+- Never run interactive commands (`vi`, `less`, `top`, `python` bare REPL).
+  Use non-interactive equivalents (`cat`, `sed -i`, `python -c '…'`).
+- Output ends with `[exit=N cwd=… timed_out=…]` — check exit=0 before claiming success.
+- If timed_out=true, do NOT just retry; diagnose (longer timeout, narrower command).
+
+EXAMPLE:
+```tool
+{"name": "ShellSession", "input": {"command": "cd /work && ls -la"}}
+```
+
+EXAMPLE with timeout:
+```tool
+{"name": "ShellSession", "input": {"command": "pip install -q requests", "timeout": 180}}
+```

package/skills/tools/webfetch.md

@@ -0,0 +1,22 @@
+---
+name: webfetch-guidance
+type: tool-guidance
+target_tool: WebFetch
+priority: 6
+token_cost: 80
+user-invocable: false
+---
+## WebFetch Tool
+Fetch and extract content from a URL.
+
+REQUIRED: url (full URL starting with http:// or https://)
+
+RULES:
+- Always use complete URLs with protocol
+- Returns extracted text content (HTML stripped)
+- Good for reading documentation, API references, web pages
+
+EXAMPLE:
+```tool
+{"name": "WebFetch", "input": {"url": "https://docs.python.org/3/library/json.html"}}
+```

package/skills/tools/write.md

@@ -0,0 +1,29 @@
+---
+name: write-guidance
+type: tool-guidance
+target_tool: Write
+priority: 10
+token_cost: 110
+user-invocable: false
+---
+## Write Tool
+Create a **new** file with the given content. Creates parent directories automatically.
+
+REQUIRED: file_path (absolute), content (full file content)
+
+**Write is for creating new files only.** If the file already exists, Write will be **refused** by the tool and return an error telling you to use Edit instead. Do not retry Write on the same path — it will be refused again.
+
+WHEN TO USE Write:
+- The file does not exist yet and you are creating it from scratch
+
+WHEN TO USE Edit INSTEAD:
+- ANY change to an existing file — bug fixes, refactors, format tweaks, adding a function, renaming a variable, everything. Edit takes old_string + new_string and patches in place.
+- Iterating after a failed test — never retype the whole file
+
+If you need to completely replace an existing file's content, Edit can still do that: pass the entire current content as old_string and the full new content as new_string. Read the file first if you don't already have its current content.
+
+EXAMPLE:
+```tool
+{"name": "Write", "input": {"file_path": "/tmp/example/new_module.py", "content": "def hello():\n    return 'hi'\n"}}
+```
+NOTE: Always use the EXACT file path given in the task, never a placeholder.