~/posts/Building a Personal Command System for Claude Code

The problem

Claude Code supports custom skills: directories under ~/.claude/skills/ with a SKILL.md that tells Claude how to handle a specific command. You type /skillname and Claude follows the instructions in that file.

After a few months of building these one at a time, I had about 15 skills with inconsistent names, no grouping and no way to remember what existed. Some had scripts, some were prompt-only. Finding the right one meant scanning a flat directory listing.

I came across the naming problem when I typed /review intending the vulnerability review skill and got the code review skill instead. Both existed. Neither name said which was which. At that point I had accumulated enough skills that the flat namespace was creating collisions, not just inconvenience. I needed a way to group them that didn't require memorizing every name.

The solution: dot-prefixed categories

I reorganized everything into namespaced categories using dot separators:

kb.*        Knowledge vault operations
ext.*       External service integrations
tool.*      Utility tools, scripts, and domain-specific calculators
session.*   Session management
(standalone) Things that don't need a namespace

The dot separator works well because: - Tab completion still works (/kb.<tab> shows all vault commands) - ls sorts them into visual groups - The prefix tells you what kind of thing it is before you read the description

What's in the box

32 skills total. Here's the breakdown.

kb.* — Knowledge Vault (21 skills)

The largest group. These operate on my personal knowledge base: a collection of markdown files I call samhita.

Introspection — tools that analyze the vault itself: - kb.emerge — surface recurring themes across notes - kb.connect — find unexpected links between topic groups - kb.contradict — spot conflicting positions in my own notes - kb.backlinks — detect missing cross-references - kb.map — text-based topology of the vault (clusters, orphans, activity) - kb.trace — track how my thinking on a topic evolved over time - kb.compound — answer a question from early-vault vs current-vault perspective

Lifecycle — moving knowledge through stages: - kb.review — interactive reading sessions from ingested articles - kb.graduate — promote raw reading notes into permanent knowledge - kb.tidy — archive, dedup, rebuild indexes - kb.index — list all available skills

Planning and Reflection: - kb.today — daily priorities from active items - kb.weekly — weekly synthesis - kb.close — end-of-day capture - kb.learned — distill recent learning into a writeup - kb.drift — find commitments I made but haven't followed up on

Thinking Tools: - kb.challenge — steelman the counter-argument to a belief - kb.ghost — draft text in my voice - kb.stranger — what would an outsider conclude from reading the vault? - kb.ideas — generate possibilities by cross-referencing interests and projects - kb.context — load project context at session start

ext.* — External Integrations (4 skills)

These reach outside the local filesystem: - ext.instapaper — CLI wrapper for the Instapaper API - ext.youtube — extract transcripts from YouTube videos via yt-dlp - ext.last30days — research community discussions across Reddit, HN, Stack Overflow, Dev.to, Lobsters - ext.xingest — ingest X/Twitter bookmarks via playwright (experimental, not yet working)

tool.* — Utilities & Domain Tools (4 skills)

These wrap specific tools or domain-specific calculators: - tool.qmd — BM25 + vector search across markdown collections - tool.humanize — detect and fix AI writing patterns - tool.panchanga — Hindu calendar calculations (tithi, nakshatra, muhurta, etc.) - tool.chakra — visual mandala/chart generation from panchanga data

session.* — Session Management (2 skills)

• session.handover — generate context document when ending a session
• session.resume — reload context when starting a new one

Standalone (1 skill)

• gcp — git commit and push in one flow

Design decisions

Prompt-only skills. Most kb.* skills have no scripts: just a SKILL.md with instructions. Claude already has file reading, searching and writing tools built in. The skill just tells it what to do and in what order. This means zero dependencies and instant creation.

Scripts only when needed. ext. and tool. skills have actual scripts because they call external APIs, run specialized algorithms, or wrap domain-specific CLI tools that Claude can't replicate with its built-in tools.

Filesystem-based everything. No databases. Dedup uses filenames. State lives in markdown frontmatter. This makes everything inspectable with ls and grep.

Separate raw from curated. Ingested content lands in reading/articles/. Only after review does knowledge graduate into the permanent vault directories. This prevents the knowledge base from filling up with unvetted material.

What I learned

The skill system is a way to give an LLM reusable procedures. Each SKILL.md is a runbook: "when the user says X, do Y in this order with these constraints." The interesting part is that most of the value comes from the constraints, not the capabilities. Claude can already search files and write markdown. The skill's job is to say "search these files, in this order and present results in this format."

It's the same principle behind good shell scripts: the tool already exists, you're just encoding the workflow.

What's next

• Battle-testing the introspection skills (connect, contradict, emerge) on real queries
• Better discoverability — /kb.index now exists but could show usage stats
• Figuring out a less fragile approach to X/Twitter ingestion than scraping with playwright
• Adding description: frontmatter to all skills so index output is useful

The 32-skill count is already a bit much to hold in memory. The namespacing helped, but at some point the index skill becomes essential rather than nice to have. That's probably the next problem worth solving.

The full setup lives in ~/.claude/ — skills, hooks, statusline, keybindings. It's version-controlled and portable across machines.