Files
skills/skills/kvb-agent-optimize/SKILL.md
T
Kevin Veen-BirkenbachandClaude Opus 5.5 b44cac5d37 fix(unify): repair the cross-branch integration failures of the skills unify
Probe sandboxes gain the channels, quietBubbles and known.now the merged branches added; the hub view keeps queue_jobs apart from the job list; the image ships sandbox_paths.py; kvb-match writes pages into the council root pages folder; the install test scaffolds the council parts and agent roots; skill texts move detail into their side files to stay under the word caps.

🎯 Fix: 88 %
💥 Break: 4 %
💸 Tokens: 98 %
⏱️ Velocity: 100 %
🛡️ Security: 100 %
🏆 Score: 86
🚦 Gate: ⛔ fix 88 % < 90

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-15 07:07:52 +00:00

4.1 KiB

name, description
name description
kvb-agent-optimize Make a repository easy for agents: a code graph index (codebase-memory-mcp) and lean agent instructions; kvb-optimize runs it.

An agent that queries a graph reads a fraction of what an agent exploring file by file reads, and short, current, consistent instructions get followed. This skill sets up the general code index, codebase-memory-mcp (MIT, fully local), and tightens the agent instructions of every repository in scope: the current one, or those kvb-optimize hands over.

Step 1: inventory

${CLAUDE_SKILL_DIR}/scripts/agents.py --repo <dir> prints one line per check: AGENTS.md, any runtime-specific instruction file beside it, dead relative links in it, whether it names the index, whether the index binary is installed, whether the daemon's auto_index is off, and the state of the shared snapshot .codebase-memory/graph.db.zst.

Step 2: index

  • Binary missing: the skills repository's make install runs the upstream installer, which installs the checksum-verified release (static on Linux) into ~/.local/bin and wires the graph into every agent it detects (Claude Code, Codex, Gemini, Hermes, OpenClaw and more); rerunning it updates. It writes the agents' configuration, so it is the operator's step: hand make install to the kvb-org-operator skill and continue after the restart.

  • Index: the skills repository's make install turns the daemon's auto_index off, because it would index a session root with no queue and no memory gate. The scripts/graph.py hook PreToolUse hook indexes instead: every git root a tool call touches, the session root included (additional working directories, worktrees, submodules), once it has no graph. It indexes nothing until ~/.config/kvb-code-graph/config.json sets queue_file_threshold and queue_task (no defaults; the operator sets both, the hook says so once per session). A root over the threshold is enqueued once through kvb-org-queue under queue_task, never started by the hook; the graph.py docstring holds every size, memory, git and retry gate. make install also enables kvb-code-graph.service, which keeps a permanent daemon so each watch outlives the last session; while the unit is inactive, the hook prints the enable command once per session and records it once as a kvb-org-operator row. Every skill that explores code asks the graph first. Check a root with index_status and check_index_coverage; every file kind it leaves out is a finding. Inside the sandbox read auto_index through agents.py (read-only _config.db), never codebase-memory-mcp config get.

  • Snapshot: ask whether the repository shares its graph. Shared: run index_repository with persistence: true and commit .codebase-memory/graph.db.zst at a fixed cadence (every commit of it adds a full blob; Git LFS avoids that). Not shared: add .codebase-memory/ to .gitignore, and every agent indexes on its own.

  • Domain graphs the generic index cannot see, such as dependencies a project declares in its own metadata, belong to the line that owns the repository: record them as its task in the kvb-org-rasci register, never build them here.

Step 3: instructions

  • AGENTS.md is the only instruction file: fold any CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md or GEMINI.md into it and remove them. Claude Code reads AGENTS.md natively (v2.1.277+) but skips it while a CLAUDE.md is on the path; Gemini CLI reads it once context.fileName lists it.
  • AGENTS.md sends code questions to the graph first (search_graph, trace_path, get_architecture) and to grep only after it.
  • /claude-api prompt-audit over AGENTS.md and the files it references finds stale, duplicate and contradicting rules; the dead links of step 1 join its findings.

Step 4: confirm

One AskUserQuestion per improvement, multiSelect: false: the change, its evidence, and Apply now, Record as a task, Skip. No repository file changes before the answer, and nothing is committed.

Output

| Repository | Check | Before | After | Action |