Skills Reference

Skills Reference

The knowledge graph plugin uses two types of skills:

• Hidden skills (user-invocable: false) — Descriptions automatically loaded into Claude's context every session. Carry behavioral rules. No user action needed.
• User-invocable skills — Loaded via /skill <name> when needed for specific workflows.

Hidden Skills (Always Active)

These skills guide Claude's memory behavior automatically. Their descriptions (~5.6K chars total) are always in context. Their full body content loads when Claude determines it's relevant.

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.

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: Maps a codebase's architecture into the project-level knowledge graph. Creates a navigable map of how the code fits together.

When to use:

• First session in a new project (bootstrap foundational 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. Maps modules — cohesive units of functionality (aim for 5-20, not hundreds)
4. Maps relationships via edges between modules, resources, entry points
5. Saves progress via kg_progress

Node types used:

Type	What	Example
module	Cohesive functionality unit	service, package, feature
resource	External/persistent state	database, cache, API
entry	System invocation point	HTTP endpoint, CLI command
artifact	File or directory	source file, config
contract	Interface between modules	API schema, shared types

Edge types used:

Edge	Meaning
contains	File/dir implements this module
exposes	Module provides this interface
consumes	Module depends on this interface
persists	Module reads/writes this resource
serves	Module handles this entry point
calls	Direct module dependency
configures	Config affects behavior

Key principle: Sparse is better. 10 well-connected nodes beats 50 isolated ones.

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 token limit — 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.

Current usage:

Skill	Chars	Type
kg-core	~1,991	Hidden
kg-capture	~1,715	Hidden
kg-recall	~1,884	Hidden
kg-maintain	~2,268	Hidden + User-invocable
kg-scout	~70	User-invocable
kg-extract	~50	User-invocable
Total	~7,978

Budget is skillListingBudgetFraction × context_window. At 2% of 200K = 4,000 chars — if you're hitting limits, raise the fraction in ~/.claude/settings.json.

Run /context in Claude Code to verify skills are loaded and check for budget warnings.