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 (~8.3K chars total) are always in context. Their full body content loads when Claude determines it's relevant.

kg-core

What: Session protocol, self-awareness mechanism, API reference, storage model.

Key rules it carries:

• Before ANY task, check if kg_read has been called this session
• If graph not loaded, immediately register + read
• After loading: review all nodes, scan archived IDs, recall related ones
• Self-awareness check: if a problem "feels familiar", kg_search before guessing
• Two levels (user/project), two entry types (node/edge), core principle (compress meaning)
• Full quick API reference

kg-capture

What: When and how to capture knowledge, compression rules, search-before-put discipline.

Key rules it carries:

• Capture immediately at discovery, not at session end
• ALWAYS kg_search before creating a node (check for duplicates)
• Capture triggers: debugging >10min, user correction, explained same thing twice, found better approach
• Proactive capture without being asked
• Edge-first thinking: prefer relationships over new nodes
• Compression: headline test, no filler, references over descriptions
• Notes vs gist: gist = compressed fact, notes = rationale/"why"

kg-recall

What: When and how to retrieve knowledge, memory trace protocol, sync timing.

Key rules it carries:

• At task start: scan archived IDs, recall anything related (bias false positive)
• Follow memory traces (edges to archived nodes are hints)
• Recall notes when making decisions near related nodes
• Batch recall for efficiency
• Sync timing: before shared decisions, every 30+ min, after subagents

kg-maintain

What: Self-reflection triggers, graph health awareness, session lifecycle, update discipline.

Key rules it carries:

• Spinning wheels → stop, search memory, capture learning
• User correction → stop, understand signal, capture pattern
• Deja vu → check graph before re-solving
• Session lifecycle: start (register+read), during (capture check), end (flush insights)
• Graph health: notice orphans, connect nodes, merge duplicates
• Memory update discipline: update incorrect nodes, scope appropriately, clean up

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). Current usage:

Skill	Chars	Type
kg-core	~2,300	Hidden
kg-capture	~2,300	Hidden
kg-recall	~1,600	Hidden
kg-maintain	~2,000	Hidden
kg-scout	~70	Visible
kg-extract	~50	Visible
Total	~8,300	52% of budget

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