Skip to content

Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

feat(init): install graft Claude Code skill into .claude/skills/graft

anirudhkumar-nanonetsd08cc7df74e8
diff --git a/src/claude/init.ts b/src/claude/init.ts
index 85d5aacf..4e7abb42 100644
--- a/src/claude/init.ts
+++ b/src/claude/init.ts
@@ -3,10 +3,12 @@ import { join } from 'node:path';
import { execFileSync } from 'node:child_process';
import { mergeGraftSettings } from './settings-merge.js';
import { statuslineShim, hooksShim } from './shim-template.js';
+import { skillTemplate } from './skill-template.js';
export interface InitResult {
settingsPath: string;
shims: string[];
+ skill: string;
warnings: string[];
built: boolean;
}
@@ -26,6 +28,13 @@ export function runInit(dir: string, opts: { build?: boolean; cliPath?: string }
writeFileSync(sl, statuslineShim()); chmodSync(sl, 0o755);
writeFileSync(hk, hooksShim()); chmodSync(hk, 0o755);
+ // Install the graft skill — the piece that redirects the agent to graft/ before it
+ // greps source. Overwritten each run (graft owns this file), like the shims above.
+ const skillDir = join(dir, '.claude', 'skills', 'graft');
+ mkdirSync(skillDir, { recursive: true });
+ const skillPath = join(skillDir, 'SKILL.md');
+ writeFileSync(skillPath, skillTemplate());
+
let built = false;
const wiring = join(dir, 'graft', '.graph', 'wiring.json');
if (opts.build !== false && opts.cliPath && !existsSync(wiring)) {
@@ -34,5 +43,5 @@ export function runInit(dir: string, opts: { build?: boolean; cliPath?: string }
built = true;
} catch { /* build best-effort; user can run `graft build` manually */ }
}
- return { settingsPath, shims: [sl, hk], warnings, built };
+ return { settingsPath, shims: [sl, hk], skill: skillPath, warnings, built };
}
diff --git a/src/claude/skill-template.ts b/src/claude/skill-template.ts
new file mode 100644
index 00000000..de223390
--- /dev/null
+++ b/src/claude/skill-template.ts
@@ -0,0 +1,48 @@
+// The graft Claude Code skill, bundled as a string so `graft init` can write it into a
+// consumer repo's .claude/skills/graft/SKILL.md — no network fetch, version-locked to the
+// installed graft. This is the single source of truth for the skill text; graft's own
+// repo copy is regenerated from here when `init` runs in this repo. Mirrors the `.cjs`
+// shim pattern in shim-template.ts.
+export function skillTemplate(): string {
+ return `---
+name: graft
+description: This repo is indexed by graft/. For ANY task here — understanding
+ how something works, finding where code lives, or scoping a change — get your
+ context from graft before grepping or reading source files.
+---
+
+# graft
+
+This repo's code is summarised in \`graft/\` — small markdown nodes, each
+explaining one part in plain prose and naming the exact files and line-spans it
+covers. Reading a node costs a few hundred tokens; reading source to rebuild the
+same understanding costs thousands.
+
+**Get context from graft first — two ways, both land here:**
+
+- Ask: \`graft ask "<your task, in plain words>"\` — returns the relevant nodes,
+ ranked, with file:line pointers. Add \`--source\` to inline the actual code at
+ each span, so the result IS the code you need — no separate file read.
+- Or explore as usual: grep / ls / cat inside \`graft/\`. A grep for any concept,
+ symbol, or filename hits the node that covers it; \`graft/INDEX.md\` lists them
+ all.
+
+**Then STOP at the node. It is the answer, not a lookup toward the answer.**
+
+- **Explaining / tracing / understanding** (no code change): the node's prose
+ IS your deliverable. Cite files and functions straight from its \`covers:\`
+ list — \`covers:\` gives you the exact \`file:line\` for every symbol, so you can
+ cite precisely **without opening the source at all.** Do NOT open source to
+ "verify," "confirm," or "see the real code" — the node was generated from that
+ source and the spans are authoritative. Opening it costs thousands of tokens
+ and changes nothing in your answer.
+- **Editing:** run \`graft ask "<symbol>" --source\` to pull the exact span's
+ code inline, and edit straight from that. Only touch the file to apply the
+ change at the named \`file:line\` — never read the whole file, never open
+ neighbouring files to "get oriented"; the pack already oriented you.
+
+If a node genuinely lacks a detail you need, \`graft ask\` for a more specific
+node before falling back to source. Reading whole source files to build
+understanding is the thing graft exists to replace — it already did that work.
+`;
+}
diff --git a/src/cli.ts b/src/cli.ts
index d0d8bb3e..3367f0a4 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -194,6 +194,7 @@ program
const res = runInit(resolve(dir), { build: opts.build, cliPath });
console.error(`✓ wrote ${res.settingsPath}`);
for (const s of res.shims) console.error(`✓ wrote ${s}`);
+ console.error(`✓ wrote ${res.skill}`);
console.error(res.built ? "✓ built the graph (graft build)" : "· skipped graph build");
for (const w of res.warnings) console.error(`⚠ ${w}`);
console.error("\nDone. The statusline + hooks activate in Claude Code sessions in this repo.");
diff --git a/test/claude-init.test.ts b/test/claude-init.test.ts
index 76ca9e7f..63ebe3e3 100644
--- a/test/claude-init.test.ts
+++ b/test/claude-init.test.ts
@@ -15,18 +15,31 @@ function runPostinstall(env: Record<string, string>): string {
} catch { return ''; }
}
-test('runInit scaffolds settings + both shims (build skipped)', () => {
+test('runInit scaffolds settings + both shims + the skill (build skipped)', () => {
const d = fresh();
const r = runInit(d, { build: false });
assert.ok(existsSync(join(d, '.claude', 'settings.json')));
assert.ok(existsSync(join(d, '.claude', 'helpers', 'graft-statusline.cjs')));
assert.ok(existsSync(join(d, '.claude', 'helpers', 'graft-hooks.cjs')));
+ const skillPath = join(d, '.claude', 'skills', 'graft', 'SKILL.md');
+ assert.ok(existsSync(skillPath), 'writes the graft skill');
+ assert.equal(r.skill, skillPath);
+ assert.match(readFileSync(skillPath, 'utf8'), /name: graft/);
assert.equal(r.built, false);
const s = JSON.parse(readFileSync(join(d, '.claude', 'settings.json'), 'utf8'));
assert.ok(s.statusLine.command.includes('graft-statusline.cjs'));
assert.ok(s.hooks.Stop[0].hooks[0].command.includes('graft-hooks.cjs'));
});
+test('runInit overwrites a stale skill file', () => {
+ const d = fresh();
+ const skillPath = join(d, '.claude', 'skills', 'graft', 'SKILL.md');
+ mkdirSync(join(d, '.claude', 'skills', 'graft'), { recursive: true });
+ writeFileSync(skillPath, 'stale junk');
+ runInit(d, { build: false });
+ assert.match(readFileSync(skillPath, 'utf8'), /name: graft/);
+});
+
test('runInit preserves foreign settings and warns on foreign statusLine', () => {
const d = fresh();
mkdirSync(join(d, '.claude'), { recursive: true });
diff --git a/test/claude-skill-template.test.ts b/test/claude-skill-template.test.ts
new file mode 100644
index 00000000..1655ca5f
--- /dev/null
+++ b/test/claude-skill-template.test.ts
@@ -0,0 +1,13 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { skillTemplate } from '../src/claude/skill-template.js';
+
+test('skill template is a well-formed SKILL.md', () => {
+ const src = skillTemplate();
+ assert.ok(src.startsWith('---\n'), 'starts with YAML frontmatter');
+ assert.match(src, /^name: graft$/m, 'declares name: graft');
+ assert.match(src, /^description:/m, 'has a description');
+ const body = src.split(/\n---\n/)[1] ?? '';
+ assert.ok(body.trim().length > 0, 'has a non-empty body');
+ assert.match(body, /graft ask/, 'body tells the agent to use `graft ask`');
+});