Skills Reference

Skills Reference

The plugin ships five skills. All of their descriptions auto-load into Claude's context every session (the skill body itself loads on demand). One is hidden-only (user-invocable: false); four are also user-invocable via /skill <name> for focused passes.

Until v0.9.30 there were three hidden skills (kg-core, kg-capture, kg-recall). They were collapsed into one kg-core following the context-engineering shift for Claude-5-generation models: judgment-based instincts over rule lists, no doctrine repeated across layers (tool mechanics live only in the kg_* tool descriptions; the session protocol lives only in the server's preload header), and roughly half the always-loaded text. An A/B bench (Sonnet, sandboxed) confirmed equal task outcomes at about half the output tokens, with zero unnecessary searching.

Skill	Hidden?	User-invocable?
kg-core	yes	no
kg-maintain	no	/skill kg-maintain
kg-scout	no	/skill kg-scout
kg-extract	no	/skill kg-extract
kg-ops	no	/skill kg-ops

Note: Claude Code enforces a per-skill description limit (currently 1,536 chars per skill). The global budget is set to 2% of context window via skillListingBudgetFraction in ~/.claude/settings.json — raise this if descriptions are being truncated.

Hidden Skill (Auto-Load Only)

kg-core

What: The memory doctrine in one voice — session protocol, then four working instincts.

The instincts its description carries:

• Recall in layers — memory is served compressed; when the preload and full read don't carry the detail but a gist points at it, fetch that node in full (batch depth reads)
• Capture at the moment of learning — whatever cost effort to gain
• Connect rather than duplicate — an edge beats a new node; name things once (a recurring entity gets one owning node; event nodes record the delta and edge to it)
• Search below the surface — the render shows the top of a grown graph, not all of it; in a rich graph the needed fact is often buried under fresher work, and a node found when truly needed earns the usefulness credit that keeps it alive

The body (loads on demand) covers: the preload/full-read protocol and its no-preload fallback, the three-tier state model and crumb-following, the capture craft (telegraphic gists, precise touches, cross-level edges), graph levels, subagent memory sizing, and a pointer to /kg-ops for anything operational.

kg-maintain (also user-invocable as /skill kg-maintain)

What: A bounded, resumable maintenance pass that pays down the graph's DEBT: line (rendered after HEALTH: in every read), plus the always-on reactive triggers.

Reactive triggers it carries (mid-conversation, no pass needed):

• User correction → update the stale node before continuing
• Node just proved useful → add one edge to current context
• Gist feels vague after using it → sharpen while context is live
• Just saved a node → check for duplicates and stale neighbors
• Archived nodes are memory traces — leave them alone unless factually wrong

The pass (invoked, DEBT HIGH, or dispatched as a subagent): one graph per pass, hard-capped categories in value order —

1. Entity consolidation (exactly ONE smeared term, when the DEBT line lists any as term×count→hub) — confirm or anoint the hub, move the durable entity facts into it, rewrite the worst satellites to delta-only gists plus an edge to the hub. The biggest lever; may take half the pass
2. Oversized gists (up to 8, longest first) — rewrite as ≤300-char headline, move detail to notes, discard no facts
3. Unconnected active nodes (up to 5) — batch-read, one honest edge each; no honest edge → sharpen the gist instead
4. Duplicate merges (up to 3) — verify overlap first, merge into the richer node, re-point edges
5. Notes hygiene (up to 3) — changelog-style notes rewritten to current truth only

Then verify (re-read: DEBT factors should drop) and stamp: kg_progress task "maintain" with last_ts — the stamp is what resets the DEBT staleness factor; an unstamped pass didn't happen. Checkpointing through kg_progress makes a cut pass resumable. Bounds: ~25 kg_* calls, never invent facts, archived stays untouched.

The skill body ships the exact subagent dispatch prompt — subagents get no preload, so the prompt carries everything needed to run the pass standalone.

User-Invocable Skills

/skill kg-scout

What: Mines Claude Code conversation history for patterns and insights worth preserving in the knowledge graph.

When to use:

• End of session with spare capacity
• Starting work on a dormant project (recover context)
• After major milestones (consolidate learnings)
• User explicitly asks to mine history

How it works:

1. Checks progress via kg_progress(session_id, task_id="scout")
2. Scans ~/.claude/history.jsonl (lightweight metadata — timestamps, project paths, first ~60 chars of each prompt)
3. Identifies tension signals: repetition (same topic 3+ times), corrections ("no I meant"), decisions ("let's use"), frustration ("still not working"), meta-instructions ("always do X")
4. Only deep-dives into full session transcripts when tension signals indicate value
5. Extracts knowledge using kg_put_node/kg_put_edge
6. Saves progress via kg_progress

Data sources:

Source	Cost	Content
~/.claude/history.jsonl	Low (~2-3k tokens for 500 lines)	Metadata: timestamp, project, first 60 chars
~/.claude/projects/{encoded-path}/{session}.jsonl	High (MBs per session)	Full transcripts with tool calls

Token budget: A productive scout run costs ~5-10k tokens. Blindly reading sessions would cost 50-100k.

Key principle: Tension-driven investigation — no tension signal, no deep dive.

/skill kg-extract

What: Builds a two-tier navigation index in the project graph so future sessions can answer "should I read this file?" without opening it.

When to use:

• First session in a new project (bootstrap foundational Tier 1 nodes)
• After major refactoring
• Spare capacity at session end
• User explicitly asks to map the codebase

How it works:

1. Checks progress via kg_progress(session_id, task_id="extract")
2. Surveys project structure (glob for config files, source dirs, entry points)
3. Tier 1 — Subsystem pass: maps 5-10 major bounded areas as subsystem nodes, connects them to resources and entry points
4. Tier 2 — Component pass (lazy): as you explore an area during real work, add a component node covering the 1-5 tightly-related files. Never bulk-create Tier 2 upfront
5. Saves progress via kg_progress

Node types:

Type	Tier	What it represents
subsystem	1	Major bounded area (auth, payments, ingestion pipeline)
component	2	Specific file cluster with a single clear responsibility
resource	—	External state: database, cache, queue, third-party API
entry	—	Invocation surface: HTTP route group, CLI command, cron, event
contract	—	Shared interface: API schema, event type, shared types package

Edge types:

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

Writing gists that enable skip decisions: the skip signal comes from knowing what's not there. "JWT issue/verify only — stateless, no DB calls, no session state" enables a read/skip decision; "Authentication module" does not. Exclusions are often more useful than inclusions.

Key principle: Sparse beats complete. 20 accurate nodes outperforms 50 approximate ones — noise degrades navigation.

/skill kg-ops

What: The operations runbook — every operational recipe in one skill, written to be agent-followable: diagnose → act → verify → undo.

Covers: install and first run, plugin updates (shim refresh, server restart, /mcp reconnect), server lifecycle and logs, systemd autostart, connecting Claude Desktop / Cowork (stdio bridge setup), configuration, the quota-gauge status line (how an agent reads its own 5h/7d limits), backup and restore, and troubleshooting (-32000 errors, tools offline, stale data, broken venv after OS Python upgrades).

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

Why one skill: skill descriptions load into every session; consolidating ops into a single runbook keeps that overhead flat while the recipe bodies load only when needed.

When NOT to Use Skills

• Mid-task — Skills like scout and extract disrupt flow. Use them at session boundaries.
• Near rate limit — Save capacity for actual work.
• Graph near its size budget — Compaction will archive newly mined content, defeating the purpose.
• Small/simple projects — Extract overhead exceeds value for trivial codebases.

Skill Budget

All skill descriptions share a global budget: 2% of context window (fallback: 16,000 characters). Each individual skill description is also hard-capped at 1,536 characters — content beyond this is silently truncated by Claude Code.

Exact char counts drift with each edit; check the YAML frontmatter description: blocks in skills/<name>/SKILL.md for the current size. Run /context in Claude Code to see what's loaded and whether the budget is being hit. If descriptions are being truncated, raise skillListingBudgetFraction in ~/.claude/settings.json.