Skip to content

Skills Reference

Jump to bottom
Maxim Mironenko edited this page May 12, 2026 · 10 revisions

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)
  • 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: reads graph health, prunes if large (merge duplicates, tighten verbose gists), fertilizes after pruning (connect clarified nodes), reports what changed.

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.

Clone this wiki locally