graft
This repo is indexed by graft/. For ANY task here, whether
arcasilesgroup · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add arcasilesgroup/ai-engineering --skill graftAbout this skill
name: graft description: This repo is indexed by graft/. For ANY task here, whether understanding how something works, finding where code lives, tracing what calls a symbol or what a change breaks, or scoping an edit, get your context from graft before grepping or reading source files.
graft
graft/ holds a graph of this repo: small markdown nodes that each explain one
part in prose and name the exact file:line spans they cover, plus a wiring
graph of who-calls-what. Querying a node costs a few hundred tokens; rebuilding
that understanding by reading source costs thousands, and misses the edges.
Every command below is $0, needs no API key, and returns in under a second.
There are six of them. Pick the one that fits the task, run it, act on the
answer; don't chain tools hoping for more. Most tasks need one call.
The tools
1 · graft ask "<question>" --source: locate + understand (the default)
Ranked retrieval over the graph, routed automatically between prose nodes and
the wiring graph, returning the top hits with exact file:line.
--sourceinlines the code at each hit, the ≤8-line crux of each definition, so the result IS the code you need, no follow-up file read. Add--fullonly when the crux is too small to act on.--in <path>narrows to a subtree before ranking;-n Ncaps results (default 8).- Use it when the question is conceptual or locational: "how does auth work", "where is rate-limiting handled", "what assembles the request pipeline".
- One ask usually answers. A genuinely multi-part question needs one ask per distinct sub-aspect, never the same question reworded. Few or weak hits mean switch tool (grep / skeleton / callers), don't re-ask.
2 · graft grep "<pattern>": exhaustive find
Regex (or --fixed for a literal) over every indexed file, hits grouped by
enclosing symbol and ranked by coupling; it also reports files it couldn't read.
- Use it when you need every occurrence: all call sites, all uses of a
constant, all providers.
askis ranked top-N and will miss instances; grep won't. One grep replaces a spray of asks. - Search a short symbol name or literal, not a full guessed signature: an
over-specific regex (
func (s *Server) GenerateHandler) returns nothing even when the code is indexed. If a grep misses, loosen it (drop the receiver and signature, keep the bare name) and retrygraft grep— do NOT switch to rawgrep -rn, which is slower and unranked. -icase-insensitive;--in <path>scopes to a subtree. Rawgrep -rnis only for files graft genuinely doesn't index (docs, configs, brand-new files).
3 · graft skeleton <file>: a file's API at a glance
Signatures-only view of one file (every function / method / type with its span) in ~200 tokens, ~10x cheaper than reading the file.
- Use it when you need "what's in this file / what can I call here" before
editing or wiring into it. One skeleton is the whole answer for a file; don't
re-skeleton the same file, and don't skeleton every file
mapalready named.
4 · graft callers <symbol>: the exact edges
Precomputed call/reference edges, not a text search. Symbol can be bare
(Foo), qualified (Class.method), or package-qualified (pkg.Fn).
- default
--direction in: who calls/references this; run before you rename, delete, or change its signature. --direction out: what this symbol itself calls/depends on (the oldcallees).--depth N: walk transitively N hops for the full blast radius (the oldimpact);--depth 2is the usual "what breaks if I touch this".--depth all: the entire connected closure — every source reachable through the edges. Reach for this before a refactor, rename, or any multi-file change: it surfaces the sibling and downstream files (platform variants, a module you must split out) that a single-file edit would miss.
5 · graft map: orientation for an unfamiliar repo or area
A token-budgeted tour: directory clusters, per-directory hubs, and global hotspots, straight from the wiring graph.
- Use it when you land in a repo cold or are asked for "the architecture".
mapalone is the answer: read the hub cards it names; do NOT then skeleton or ask your way through every subsystem it lists.--max-dirs Nwidens it.
6 · Lifecycle: graft build / graft check
Every tool above refreshes the graph itself before answering, so what those tools
return always describes the code as it is right now — including edits you just made
and have not committed. You do not need to run build after editing.
One caveat, if you grep the markdown under graft/ directly: those cards are a
projection, rebuilt at the end of the turn rather than on each query, so after an edit
they can lag. The tools above never do — prefer them, and treat a card's spans as
stale if you have edited that file this turn.
build is for the LLM layer (--deep adds a concept map; skip unless asked);
check fails when graft/ is stale, for CI.
Scenarios: the shortest path through a coding task
| When you're… | Reach for | Calls |
|---|---|---|
| Onboarding / "explain this codebase" | graft map, then read the named hub cards | 1 |
| Understanding a flow ("how does X work") | graft ask "<flow>" --source | 1 |
| Finding where a change belongs | graft ask "where is <behavior>" --source | 1 |
| Editing a symbol you can already name | graft grep "<symbol>", edit at the file:line (skip ask — you know where it is) | 1 |
| Renaming / deleting / changing a signature | graft callers <sym> --depth 2 first | 1 |
| Refactor / multi-file change (before editing) | graft callers <sym> --depth all — map every connected file, don't stop at the first | 1 |
| "What does this depend on?" | graft callers <sym> --direction out | 1 |
| Finding every occurrence of a pattern | graft grep "<literal>" | 1 |
| "What's the API of this file?" |