Skills Reference

Skills Reference

Skills are instruction sets that Claude loads via /skill <name>. They don't add new tools — they guide Claude on how to use existing kg_* tools for specific workflows.

/skill memory

What: Full reference for the knowledge graph system — API, compression rules, capture triggers, recall strategies, maintenance.

When to use: When you need Claude to deeply understand the memory system, or as a refresher mid-session.

What it includes:

• Quick API reference for all tools
• Capture priority table (what to save at which level)
• Compression rules (5 levels of increasingly aggressive compression)
• Memory trace protocol
• Auto-compaction explanation

Sub-files loaded:

• CAPTURE.md — Decision trees for what/when/how to capture, edge-first thinking, anti-patterns
• RECALL.md — When to sync, memory trace following, batch recall strategies
• MAINTAIN.md — Self-reflection triggers, session lifecycle, graph health checks

/skill 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_get(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_set

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 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_get(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_set

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.