Skills Reference

Skills Reference

The plugin ships six 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); three 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

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: Garden rhythm for proactive tending, reactive triggers, archival policy. Can also be invoked directly for a focused maintenance pass.

Key rules it carries:

• Garden rhythm: water (after each task, glance at recent nodes), prune (merge/compress when dense), fertilize (connect nodes when used)
• Gist hygiene: every pass checks all gists against the current kg-capture standard — old nodes not exempt
• Notes hygiene: notes accumulate silently as a changelog; rewrite (not just append) when a node has 3+ touches or notes contain contradictions — collapse to current truth only
• After capture: ask if adjacent nodes need updating or if this is a duplicate
• Reactive: spinning wheels → kg_search; user correction → update stale node; deja vu → check graph first
• Archived nodes are memory traces — leave them alone unless content is factually wrong

When invoked as /skill kg-maintain: runs a focused pass in order:

1. Scans all gists against the current kg-capture standard — tightens any exceeding it, regardless of graph size or node age
2. Spot-checks notes on recently-touched nodes — rewrites any that have grown into a changelog or contain contradictions (collapses to current truth)
3. Prunes if graph is large: merges duplicates, splits oversized nodes, removes stale touches
4. Fertilizes after pruning: connects nodes clarified during pruning, adds missing edges
5. Reports what changed: nodes merged/split, gists tightened, edges added

Key distinction: gist and notes hygiene run always (steps 1–2), not only when the graph is large.

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.

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.