Consolidate 4 skills into 1 with progressive disclosure

[gdilla]

Summary

• Consolidates the 4 separate skills (codebase-memory-exploring, codebase-memory-tracing, codebase-memory-quality, codebase-memory-reference) into a single codebase-memory skill with a references/ directory
• Follows the Agent Skills specification and Anthropic's best practices for skill creators
• Net reduction: 413 lines removed, 321 added (–92 lines)

Why

Problem: 4 description entries at startup

Every installed skill registers a name + description entry that the agent scans at session startup to decide which skills are relevant. With 4 separate skills, that's 4 entries consuming listing space — when a single skill with a comprehensive description covers all the same trigger phrases.

Problem: no progressive disclosure

The official spec recommends SKILL.md under 500 lines / ~5000 tokens, with detailed reference material in separate files loaded on demand. The current 4 skills are each standalone SKILL.md files with no references/ directory, meaning all content loads at activation regardless of what the user actually asked about.

Problem: scattered gotchas

The most valuable content — the pitfalls that prevent users from hitting common mistakes — was scattered across 4 files with no single source of truth. Per Anthropic's guidance: "The highest-value content in many skills is a list of gotchas."

What changed

assets/skills/ (the skill files)

Before	After
codebase-memory-exploring/SKILL.md (90 lines)	codebase-memory/references/exploring.md (61 lines)
codebase-memory-tracing/SKILL.md (125 lines)	codebase-memory/references/tracing.md (99 lines)
codebase-memory-quality/SKILL.md (101 lines)	codebase-memory/references/quality.md (85 lines)
codebase-memory-reference/SKILL.md (154 lines)	codebase-memory/references/tool-reference.md (118 lines)
(no unified entry point)	codebase-memory/SKILL.md (54 lines) — decision matrix + gotchas

The new SKILL.md is 54 lines and contains:

1. A quick decision matrix — "what do you want to do?" → which tool call
2. A routing table — points to the right reference file based on the task
3. A consolidated gotchas section — the 7 most common mistakes in one place

Reference files are loaded only when the agent needs them for the specific task.

src/cli/cli.c (embedded skill content)

The 4 embedded C string constants are replaced by 1 self-contained skill that includes the decision matrix, all workflows, tool listing, edge types, Cypher examples, and gotchas. This embedded version is a fallback for the CLI installer — the full skill with references/ directory is in assets/skills/.

src/cli/cli.h

CBM_SKILL_COUNT changed from 4 to 1.

tests/test_cli.c

Updated to test the single consolidated skill. Verifies that all capabilities from all 4 former skills are present (search_graph, trace_call_path, detect_changes, max_degree, exclude_entry_points, query_graph, Cypher, 14 MCP Tools) plus the new gotchas section.

Migration

Users who have the old skills installed in ~/.claude/skills/ should:

1. Delete the 4 old directories: codebase-memory-exploring, codebase-memory-tracing, codebase-memory-quality, codebase-memory-reference
2. The new single codebase-memory skill will be installed automatically on next run

No functionality is lost — all content is preserved in the reference files.

Test plan

• CBM_SKILL_COUNT compiles correctly as 1
• test_cli.c passes — consolidated skill contains all capabilities
• Skill installs as single codebase-memory/ directory with references/ subdirectory
• Agent correctly routes to reference files based on user task
• All trigger phrases from the 4 old descriptions work with the new consolidated description

🤖 Generated with Claude Code