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

Note: Claude Code enforces a hard 1,536-char limit per skill description. All hidden skills are written to fit within this — behavioral rules are front-loaded so nothing is 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
• Batch recall: read several related nodes at once

kg-maintain

What: Garden rhythm for proactive tending, reactive triggers, archival policy.

Key rules it carries:

• Garden rhythm: water (after each task, glance at recent nodes), prune (merge/compress when dense), fertilize (connect nodes when used)
• After capture: immediately 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
• Never delete archived nodes unprompted — archival is automatic and reversible

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	Limit	Type
kg-core	1,149	1,536	Hidden
kg-capture	1,450	1,536	Hidden
kg-recall	1,495	1,536	Hidden
kg-maintain	1,451	1,536	Hidden
kg-scout	~70	1,536	Visible
kg-extract	~50	1,536	Visible
Total	~5,665	16,000	35% of budget

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