Skills Reference

Skills Reference

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

Skill	Hidden?	User-invocable?
kg-core	yes	no
kg-capture	yes	no
kg-recall	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 Skills (Auto-Load Only)

kg-core

What: Session start protocol, memory-first orientation, storage model, API reference.

Key rules it carries:

• SESSION START: if kg_read not yet called, call it now — before any task work
• Memory-first: check the graph before reaching for files, docs, or web search
• Two levels (user/project), two entry types (node/edge)
• Prefer edges — they reuse existing concepts rather than multiplying nodes
• API quick-reference (full signatures in skill body)

kg-capture

What: When and how to capture knowledge, encoding rules, edge-first thinking.

Key rules it carries:

• Capture immediately at discovery, not at session end
• kg_search before creating — update existing nodes rather than duplicating
• Capture triggers: debugging >10min, user correction, same thing explained twice, architectural decision
• Telegraphic encoding: gist = one headline, ≤120 chars, no filler. If it needs "and" → split into two nodes + edge
• Gist vs notes: gist = compressed fact (always visible), notes = rationale/steps/why (read on demand)
• Edge-first: prefer a relationship between existing things over a new node

kg-recall

What: When and how to retrieve knowledge, three-tier state model, crumb-following.

Key rules it carries:

• At task start: scan all node IDs and gists, read anything related in full
• Three tiers: active (gist visible) → archived (ID+edges visible) → orphaned (invisible, searchable)
• Crumb-following: edges to archived IDs are trails — read them, they chain-rescue orphaned neighbors
• kg_search reaches all tiers including orphaned — last lifeline for buried nodes. Pass session_id to include the project graph; without it, searches all loaded project graphs as best-effort
• Batch recall: read several related nodes at once

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. Oversized gists (up to 8, longest first) — rewrite as ≤300-char headline, move detail to notes, discard no facts
2. Unconnected active nodes (up to 5) — batch-read, one honest edge each; no honest edge → sharpen the gist instead
3. Duplicate merges (up to 3) — verify overlap first, merge into the richer node, re-point edges
4. 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, 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.