Skills Reference

Skills Reference

The plugin ships five skills, in knowledge-graph/skills/. A skill's short description is listed to the agent in every session; its body loads only when the skill is used. One skill is hidden (user-invocable: false) and works in the background. The other four you can call by name: /kg-maintain and the others in Claude Code; in Codex, ask the agent for the skill by name. The Antigravity package carries the same skill folder.

Skill	Hidden?	How to call it
kg-core	yes	Not called; its description is always in context
kg-maintain	no	/kg-maintain
kg-scout	no	/kg-scout
kg-extract	no	/kg-extract
kg-ops	no	/kg-ops

Before 0.9.31 there were three hidden skills (kg-core, kg-capture and kg-recall). They were merged into one kg-core, so that the always-loaded text is shorter and no instruction is repeated across layers: tool mechanics live only in the kg_* tool descriptions, and the session protocol lives in the server's preload header.

Hidden Skill

kg-core

What: The memory doctrine in one place: how a session starts, and how to recall, capture, connect and endorse.

Its description (always in context) says:

• Session start: part of memory arrives preloaded with the session id; the full kg_read comes before any work.
• Recall: when a gist points the right way, read the full node; search for more, because in a grown graph the needed fact is often buried under fresher work, and search reaches every tier.
• Capture at the moment of learning. One lesson per node: the gist states the lesson so it holds beyond the case that taught it, and each note tells one case. Before writing, walk back through the session: each point where another choice would have changed the outcome is a lesson.
• Name: the id names the subject in three to five words, never a container such as …-lessons or …-log.
• Connect rather than duplicate, but a new lesson still earns its own node.
• Endorse with kg_useful: the nodes that helped (judged at wrap-up against results), and the ones that were missing when they were needed (sent as soon as the gap shows). That credit keeps a node alive, and a miss is the only signal that corrects a wrong archival.

The body (loaded on demand) covers: the preload and full-read protocol, reading a long reply in parts, the fallback when there is no preload (Claude Desktop chat, a general chat with no project), the three tiers (active, archived, orphaned), searching below the surface, the capture craft (one concept per node, name things once, no dates in ids or gists, precise touches, cross-level edges, renaming only with kg_rename_node), why documents should point into memory and not the other way round, how to endorse, the two graph levels, how to size memory into subagent prompts, and a pointer to /kg-ops for anything operational.

User-Invocable Skills

/kg-maintain

What: A bounded, resumable maintenance pass that pays down the graph's DEBT: line (shown after HEALTH: in every full read), plus reactive habits the agent applies mid-conversation.

Reactive triggers (no pass needed):

• The user corrects something: update the stale node before continuing.
• A node just proved useful: add one edge to the current context.
• A gist feels vague after using it: sharpen it while the context is live.
• A node was just saved: check for duplicates and neighbours that need updating.
• Archival is automatic and reversible, so archived nodes are left alone. Deletion is a last resort, only for what is factually wrong and cannot be fixed.

The pass (when you invoke it, when DEBT reads HIGH, or as a dispatched subagent) works on one graph:

0. Orient: kg_read(session_id, maintenance=true), so the pass's own reads and writes do not count as use of the nodes it judges. If the pass judges that a lesson should stay in view, it can credit it with kg_useful(ids, credits=1-3), at most 15 credits per pass. A credit fades like an endorsement, so the lesson stays only if sessions keep finding it useful.
1. Resume: read the trail of earlier passes through kg_progress, including what they considered and declined, so it does not weigh the same merge a third time.
2. Work the list, in this order, each category capped:
   1. Entity consolidation: exactly one smeared term, when the DEBT line lists any as term×count→hub. Confirm or choose the hub node, move the durable facts into it, and rewrite the worst satellite nodes to their own delta plus an edge to the hub. The biggest lever; it may take half the pass.
   2. Oversized gists: up to 8, longest first. Rewrite as a headline of at most 300 characters and move detail into notes, discarding no facts.
   3. Id refinement: up to 5, only with kg_rename_node. Ids name the subject in three to five words, without dates; beyond repair, rename toward the vocabulary the graph actually uses.
   4. Unconnected active nodes: up to 5. One honest edge each; if there is no honest edge, sharpen the gist instead.
   5. Duplicate merges: up to 3. Verify the overlap first, merge into the richer node and re-point edges.
   6. Notes hygiene: up to 3 nodes. Rewrite changelog-style notes to current truth only.
   7. Recurring principles: at most one. A principle that keeps gaining new failure cases after it was written is missing something. The pass classifies the cases, separates a placement problem from a content problem, and writes a new shape as a HYPOTHESIS: node that only real work can confirm.
3. Verify and stamp: re-read (the worked DEBT factors should drop), then record a kg_progress stamp for task "maintain" with counts per category and a declined list. The server writes the time, because an agent has no reliable clock. Only a stamped pass resets the DEBT staleness factor.
4. Report debt before and after.

Bounds: roughly 25 kg_* calls, never invent facts, and leave archived nodes untouched except for promotions its own edges cause. The skill body also carries the exact prompt for dispatching a pass to a subagent, since subagents get no preload.

Background upkeep (chores and passes). If you switch it on (kg setup --only upkeep; see Configuration#maintenance-chores), the server does the same work while you use the agent, as a detached headless agent through Claude Code, Codex or Antigravity ("runner": auto, claude, codex or antigravity). Your session spends no context on it. There are two tiers:

• A chore is one category on one or two nodes the server picks (a lift takes a cluster of two to five), in six or seven tool calls (about ten for a lift). Its kinds are oversized gist, long or dated id, unconnected node, changelog-style notes, and two kinds only the server can prepare: anchor (apply the new location of a file a touches entry points to, which the server has already found) and lift (write the lesson that two or more episode nodes share once, as a principle node, and edge the episodes to it). A chore never renames a node a live session holds, never touches a node an earlier pass declined, and never rewrites the text of a node whose gist was already rewritten more than twice in 30 days (repeated rewriting is the one maintenance pattern measured to degrade memory). Entity consolidation, duplicate merges and recurring principles are left to the full pass. Chores run only on a graph whose debt is above a floor, while the runner's quota gauge shows 5-hour use below 55% and weekly use below 80%, at least 45 minutes apart and at most 8 a day. They cannot delete.
• A pass is the full structural pass above (categories 1 to 6; not recurring principles, and it cannot credit with kg_useful). It is dispatched when a graph you are using has gone 21 days without a stamped pass, and only while 5-hour use is below 40%, weekly use below 70% and the week's pace is at most 1.0, meaning the week is on course to leave quota unused. It may delete, because merges need it, but never renames, merges away or deletes a node a live session holds.

Every run and every refusal is logged in ~/.knowledge-graph/chores.jsonl. Lessons about maintenance itself go to the maintain graph level, the maintenance agent's own memory, which is never preloaded or searched in normal sessions. /kg-ops has the switch, the gates and the runner details.

/kg-scout

What: Mines Claude Code transcripts, Codex rollouts and Antigravity CLI conversations for lessons worth keeping.

When to use:

• At the end of a session with spare capacity
• When picking up a dormant project, to recover context
• After a major milestone, to consolidate what was learned
• When you ask it to mine history, or to rebuild memory after data loss (see Data and Backup)

How it works:

1. Checks where it left off with kg_progress(session_id, task_id="scout").
2. Scans a lightweight index: Claude Code's history.jsonl, the Codex rollout inventory and its session metadata, or Antigravity's history.jsonl joined to its conversation database.
3. Looks for tension signals: repetition (the same topic three or more times), corrections ("no, I meant"), decisions ("let's use"), frustration ("still not working") and standing instructions ("always do X").
4. When you are present, lists the candidate sessions with their signals and rough size, and lets you choose which to read in full. A request that already names specific sessions or a narrow topic skips this step.
5. Reads only the chosen sessions selectively and writes what it finds with kg_put_node and kg_put_edge, with a note naming the source session.
6. Saves progress with kg_progress: a timestamp for Claude Code history, a cursor per Codex rollout file and per Antigravity conversation. A resumed session that kept growing is picked up where scout stopped, and candidates it had no budget for stay pending.

Data sources:

Source	Cost	Content
~/.claude/history.jsonl	Low (about 2,000 to 3,000 tokens for 500 lines)	Timestamp, project and the first characters of each prompt
~/.claude/projects/<encoded-path>/<session>.jsonl	High (megabytes per session)	Full Claude Code transcripts with tool calls
${CODEX_HOME:-~/.codex}/sessions/**/rollout-*.jsonl	Metadata first, then selective reads	Codex session metadata, user and assistant turns, tool records; resumed files can keep growing
~/.gemini/antigravity-cli/history.jsonl	Low	Antigravity CLI prompt index
~/.gemini/antigravity-cli/conversation_summaries.db	Low (read-only SQLite)	Antigravity conversation inventory: workspace, step count, last change
~/.gemini/antigravity-cli/brain/<conversation-id>/.system_generated/logs/transcript_full.jsonl	High	Full Antigravity CLI transcripts, one step per line

Antigravity subagent conversations and the plugin's own maintenance runs are skipped. The Antigravity desktop app and IDE keep their history elsewhere and are out of scope.

Token budget: the skill estimates 5,000 to 10,000 tokens for a selective pass over Claude Code history. That is a rough guide, not a fixed cost.

Unattended runs: with nobody there to ask, scout picks the sessions itself and records what it chose and skipped. It continues only while the runner's own quota gauge shows 5-hour use below 40%, weekly use below 70% and a weekly pace of at most 1.0, and it stops when the gauge is missing or unreadable, or when the pace cannot be computed yet (the first few hours of a new week), saving its cursor first.

Key principle: no tension signal, no deep read.

/kg-extract

What: Builds a two-tier navigation index in the project graph, so future sessions can decide whether to open a file without reading it.

When to use:

• The first session in a new codebase
• After a major refactor
• When you ask it to map the codebase

It is not worth running on a project small enough to survey in one glance.

How it works:

1. Checks progress with kg_progress(session_id, task_id="extract").
2. Surveys the project structure: config files, source directories, entry points, READMEs.
3. Tier 1, subsystems: maps the 5 to 10 major areas as subsystem nodes and connects them to resources and entry points.
4. Tier 2, components (lazy): adds a component node for a cluster of one to five related files only when real work explores that area. Tier 2 is never bulk-created up front.
5. Saves progress with kg_progress.

Node types:

Type	Tier	What it represents
subsystem	1	A major bounded area (auth, payments, an ingestion pipeline)
component	2	A specific file cluster with one clear responsibility
resource	—	External state: a database, cache, queue or third-party API
entry	—	An invocation surface: an HTTP route group, CLI command, cron job or event
contract	—	A shared interface: an API schema, event type or shared types package

Edge types:

Edge	Meaning
calls	Runtime dependency (A uses B)
persists	Reads or writes a resource
serves	Handles an entry point
exposes	Provides a contract
consumes	Depends on a contract
configures	A config artifact affects behavior
guards	Middleware or validation wrapping another component

Gists that enable skip decisions: the useful signal is often what a part does not do. "JWT issue/verify only — stateless, no DB calls, no session state" lets the next session decide to read or skip; "Authentication module" does not. Touches can point at a line range with a short anchor (src/auth/jwt.ts:88-120 (rotation schedule)), so the next session reads ten lines instead of the file.

Key principle: sparse beats complete. Twenty accurate nodes are worth more than fifty approximate ones.

/kg-ops

What: The operations runbook, written so an agent can follow it step by step: diagnose, act, verify, undo.

Covers: install and first run (kg setup, kg doctor, Codex hook trust), updates (kg update), server lifecycle and logs, systemd autostart, connecting Claude Desktop and Cowork through kg mcp, Codex and Antigravity specifics, background upkeep (chores, passes and their runner), configuration, the quota-gauge status line (how an agent reads its own 5-hour and 7-day limits), renaming nodes safely, backup and restore, troubleshooting (tools offline, -32000 errors, stale data after disk edits, a broken tool environment after an OS Python upgrade, Desktop issues) and uninstalling.

When to use: anything operational. Telling the agent "run /kg-ops and fix the memory server" is a complete instruction, because the recipes carry the exact commands and paths.

Why one skill: every skill's description is loaded into every session. Keeping operations in one runbook keeps that overhead small, while the recipes load only when needed.

When Not to Run the Skills

• Mid-task: scout and extract interrupt the work. Run them at session boundaries.
• Near a rate limit: keep the capacity for the actual work.
• A graph with high maintenance debt: run /kg-maintain before adding a large batch from scout or extract.
• Small or simple projects: extract costs more than it returns on a trivial codebase.

Skill Description Size

Claude Code caps how much of each skill's description it lists and how much listing text all skills may use together; text past the cap is cut off silently. The kg-memory descriptions are written to fit, and kg-core's is the longest at about 1,500 characters. To check what is loaded in your session, run /context in Claude Code. The descriptions themselves are the description: blocks at the top of each skills/<name>/SKILL.md.