How a one-person consulting and research practice uses Claude Code as a knowledge operating system. What is in it, why it is built this way, and what parts are worth copying.
The conventional frame for Claude Code is a developer's terminal assistant. Write functions, fix bugs, run tests, commit. Almost none of my five weeks of transcripts match that frame. The instrument has been bent toward a different job: running the apparatus of a one-person consulting and research practice. That means a body of intellectual property (a book, a set of frameworks, a methodology), a live publishing surface (a website with gated research products), a small sales pipeline (a set of target accounts I do custom research on), a library of process documentation, and a workshop business launching on top of all of it.
The signature of the work is knowledge work, not software engineering. Reading, writing, composing, checking, publishing. The tool stack I have converged on is closer to a research desk than a build pipeline. What follows is a description of that setup and the wiring that connects it, written for other Claude Code users who want to do something similar. There is no coding here worth the name. There is a lot of filesystem design, skill authoring, hook configuration, and memory discipline.
The document is organized in two parts. Part I is the setup: the things that sit at rest on disk and give the environment its shape. Part II is the wiring: the hooks, skills, and session rituals that connect those parts so the whole apparatus runs as one system. A short close at the end lists the principles I would copy if I were building this from scratch.
Six structural choices that together make Claude Code usable for knowledge work instead of software engineering.
Every design decision downstream of this one reflects it. The files I care about are markdown and HTML, not source code. The artifacts I produce are research briefs, framework documents, published web pages, and account plans. The friction I care about reducing is not compilation time or test coverage; it is the friction of knowledge work. Source sprawl. Context drift across long sessions. Losing track of which framework belongs to which chapter. Forgetting which target account said what in which quarter. Drafting the same idea three times because the first two drafts disappeared into an archive.
If you treat Claude Code as a developer's terminal, you end up wiring it for CI/CD, git workflows, and test runners. If you treat it as a knowledge operating system, you end up wiring it for context loading, voice enforcement, graph routing, and memory hygiene. The rest of this document is the second path.
The instrument follows the framing. Choose the framing first.
My Desktop has four hot folders. The important ones are color-tagged in Finder, and the tags are a type system, not decoration. Red means the Brain, the knowledge operating system. Structured, machine-readable, hand-curated. Claude queries these files. Do not reorganize casually. Green means the Site, the live deploy folder. Git repo wired to GitHub and Netlify. Push equals live in thirty seconds. Every other folder is uncolored, which means scratch, reference, archive, or legal. Color is the exception, not the category.
This matters more than it sounds. When Claude is asked to edit a file, it needs to know whether it is editing canonical published knowledge (a graph node in the Brain), deployable content (a page on the Site), a reference used only by me, or an archived copy. The filesystem does not encode that distinction natively. A PostToolUse linter can, and mine does: the qa-lint hook scopes its checks to the red and green folders, plus the Site Reference folder and Strategy. Everywhere else, it is silent. That scoping is only possible because the filesystem tells Claude which folders are which.
The generalizable principle: if you want Claude to treat different files differently, put them in different folders and wire your hooks to those paths. Do not try to teach Claude a policy. Teach the harness.
Early in this practice I tried the obvious thing: upload a 300-page manuscript, a slide deck, a prospect research file, and ask questions. It worked for about ten turns. Then attention drifted, the source of a quote became ambiguous, and I could not tell whether the framework I was seeing was my own or a paraphrase. The thread would dissolve into a kind of informed fog.
The workaround I built for this is a file format I now use for almost everything I want Claude to understand at a glance: a 5 to 15 kilobyte markdown file, structured as a graph. Nodes at the top (a list of entities with short labels), edges in the middle (the relationships between them), and attributes at the bottom (per-node detail). The header of the file is a loading instruction telling Claude how to read it. The body is the data. I call these knowledge graphs, not because they are Neo4j or any other graph database, but because they are shaped like graphs and read like graphs.
Six of these live in the Brain today. Each one is a small cluster of files with a predictable shape. The names below are just folder names; the content behind each is a handful of markdown files that collectively form one knowledge graph.
Every graph is under ~15 KB. Every graph loads in a single Read call. Every graph is hand-edited (no tooling to generate them, on purpose). Every graph has a predictable filename pattern so Claude knows what to expect. This is the invention I am proudest of, and the one I recommend most strongly to other knowledge workers using Claude Code. If you have a body of knowledge you reference constantly, shape it as a small dense markdown graph, not a folder of documents.
A graph you can load in one Read call becomes part of Claude's working memory for the whole session. A folder you have to walk becomes context Claude keeps losing. Size the unit to the Read call, not to the topic.
The reason I built the graphs is not so I could read them. I built them so I could compose against them. The combination is what I call the composition engine, and it has four inputs:
A real request looks like: "draft a short research brief for a target manufacturing account on operating debt and AI governance." Claude loads the relevant slice of the intellectual-property graph (the frameworks that apply to operating debt), the relevant account file (what I know about this buyer right now), the relevant product template (the published format and its rules), and the voice skill. It produces a draft that sounds like me, cites the right frameworks, addresses the right contact, and fits the published format. No prompt template. No retrieval pipeline. Just a filesystem with a loading convention and a set of skills that know how to compose against it.
I want to underline what this is: a workflow that does not exist in any consulting firm I know and cannot be produced by any off-the-shelf AI tool. The novel move lives in the orchestration: separating intellectual property from accounts from assets from voice, so each piece can be updated independently, and then letting Claude compose by routing to the right slice.
If you have intellectual property (frameworks, methodology, a book, a body of published work), target accounts (buyers you are trying to develop), a recognizable format you publish in, and a voice standard (something more specific than "my tone"), you can build this. It is not hard. The hard part is building the four inputs at a quality high enough that the composition is worth reading.
Skills are folders under ~/.claude/skills/, each containing a SKILL.md with frontmatter that tells Claude when to use them. The frontmatter has two fields that matter: name and description. The description is the routing logic. Claude reads every skill's description at session start and invokes the skill when a user prompt matches its trigger vocabulary.
This is the most important thing to understand about skills: you do not invoke them, the vocabulary does. If I write a skill called book-reference and its description lists every framework name from my book, then the skill fires automatically every time I mention any of those frameworks in a prompt. I never have to remember to load it. I never have to type a command. I just talk normally, and the skill recognizes the vocabulary and loads itself.
My skills cluster into three benches:
rbd-writing-voice (the voice standard), rbd-site-nav (navigation consistency), world-class-web-app (SPA UX patterns), book-reference (manuscript corpus), qa (two-layer quality review), retire (session close-out triage).update-config, keybindings-help, simplify, loop, schedule, claude-api.pdf, docx, xlsx, pptx, skill-creator.The design pattern I would copy from this: every custom skill should bundle its reference material in a references/ subdirectory and use the SKILL.md purely as a router. The router explains when to load which reference file. Keep the router small (under a page) and put the actual knowledge in the references. This way Claude does not have to read your whole skill to decide whether it applies; it just reads the description, and loads the references only when it needs them.
~/.claude/skills/book-reference/ ├── SKILL.md # router: when to load which reference └── references/ ├── frameworks.md # definitions + relationships (concept queries) ├── chapters.md # chapter → line ranges (location queries) └── book.txt # full extracted text (exact-quote queries)
Routing logic inside the SKILL.md tells Claude: concept questions load frameworks.md, location questions load chapters.md, exact quotes grep book.txt. The router is maybe 200 lines. The references are where the substance lives.
Claude Code has a memory system at ~/.claude/projects/<slug>/memory/. The default is a single file, MEMORY.md, that gets auto-loaded at every session start. I use a different shape: the MEMORY.md file is a registry, not the content. It contains short one-line pointers to individual memory files. The individual files sit in the same directory and are typed by filename prefix.
Four types, sharded by filename prefix:
The typing matters because it changes how each file decays. User facts decay slowly. Feedback rules should never decay (they are the accumulated judgment of the practice). Project files decay fast and need active pruning. Reference files decay only when the external system changes. Sharding by type lets me update the fast-moving ones without touching the stable ones, and lets Claude load only the relevant shards for a given session.
Why this beats a single big memory file: the single file ossifies. You stop editing it because any edit feels risky and any edit bloats it. A sharded registry is easier to update (you edit one small file, add one line to the registry) and easier for Claude to load (MEMORY.md is small and cheap to read every session; the individual files load only when referenced).
Eight mechanisms that turn the setup into a running system. Each one took a design decision that was not obvious, and each one is worth stealing.
Most Claude Code users I know run long sessions. They open a session in the morning, use it all day, close it at night. I do the opposite: I run short sessions and restart aggressively. Sometimes three or four restarts in a working afternoon. The short restarts are deliberate, a discipline I adopted on purpose, and load-bearing for the whole architecture.
The reason is memory hygiene. Long sessions drift. Context bloats, facts get restated inconsistently, and by hour three Claude is working off a slightly wrong version of what I told it in hour one. Short sessions force distillation: whatever I have learned or decided has to be crisp to survive the restart. Mush does not survive. Clarity does. Restart becomes a chance to tighten.
But short sessions only work if nothing worth keeping is lost between them. That requires two things: a clean loading handshake at session start, and a close-out ritual at session end. Those are what the rest of Part II describes.
SESSION START │ ├──▶ MEMORY.md auto-loads # Claude Code default └──▶ MANIFEST.md auto-injects # load-manifest SessionStart hook │ WORKING SESSION # kept short for memory hygiene │ ├──▶ qa-lint fires on every save # PostToolUse regex hook └──▶ skills route by vocabulary # book-reference, qa, rbd-writing-voice, ... │ /retire # triage and route nuggets to home files │ RESTART # clean context, updated memory │ ▼ SESSION START # the loop continues
The MANIFEST.md file at the root of the Brain is the closest thing I have to a table of contents for my knowledge system. It lists every use case I regularly work on (account outreach, product authoring, book research, workshop prep, revenue tracking) and for each one, the files to load. It is hand-curated because the intent lives in the curation. A rule like "when working on accounts, always load the four shared prospect-graph files together (topology, attributes, signals, and plays)" is a judgment call about what belongs together, not a fact the filesystem knows on its own. Nothing on the filesystem says those four files co-occur. I say they do.
Early in the design I assumed I would write a hook that pattern-matches the user prompt for keywords (account names, framework names, partner names) and only injects the MANIFEST when a keyword matched. I started listing the triggers. I got thirty in. Then I realized they would rot the moment I added a new partner or initiative. The trigger list would need to be updated every time the MANIFEST was. The maintenance burden of the trigger list was higher than the cost of always loading the file.
So I inverted the design. The hook now loads the MANIFEST unconditionally, at SessionStart, every session. No triggers, no regex, no pattern matching. It costs about 3.5 KB of context per session. It is basically nothing. And it eliminates an entire class of "I forgot to tell Claude to load the MANIFEST" friction.
The hook is short enough to show in full:
#!/bin/bash # load-manifest.sh · SessionStart hook # Unconditionally injects MANIFEST.md at every session start. # Loud failure if the file is missing. set -uo pipefail MANIFEST="$HOME/Desktop/RBD Brain/MANIFEST.md" if [ ! -f "$MANIFEST" ]; then echo "load-manifest ERROR: MANIFEST.md not found" >&2 exit 2 fi MTIME=$(stat -f '%Sm' -t '%Y-%m-%d %H:%M' "$MANIFEST") python3 - "$MANIFEST" "$MTIME" <<'PY' import json, sys path, mtime = sys.argv[1], sys.argv[2] content = open(path).read() wrapper = f"""# MANIFEST.md (auto-loaded by load-manifest hook) Source: {path} Last modified: {mtime} --- {content} """ print(json.dumps({ "hookSpecificOutput": { "hookEventName": "SessionStart", "additionalContext": wrapper, } })) PY
The generalizable principle: before you build a trigger list, ask whether you could just load the thing every session. Always-load beats conditional-load for small files, because it removes the maintenance burden of keeping triggers in sync with content.
The difference between a skill and a hook is a distinction worth understanding precisely. A skill is topic-routed: it fires when the vocabulary of your prompt matches its description. A hook is event-routed: it fires when Claude Code emits a specific lifecycle event (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop). Skills depend on Claude recognizing that a skill applies. Hooks do not depend on Claude at all: they are executed by the harness itself. This matters because memory is not load-bearing for hooks.
I have two hooks wired. The first, load-manifest, runs at SessionStart and is described above. The second, qa-lint, runs at PostToolUse on every Edit, Write, and MultiEdit call, and runs a regex linter against the file that was just modified. It is the enforcement arm of the RBD. voice standard and the QA process.
Three design decisions inside qa-lint are worth naming:
.md or .html. Everywhere else the hook exits silently. That is how a global linter avoids firing on unrelated work.<!-- qa-lint:ignore --> escape marker. Not built yet.The generalizable principle: if you want a rule enforced regardless of whether Claude happens to invoke the right skill, build it as a hook. Hooks are the harness. Skills are the working bench. Both are useful. They do different jobs.
Skill descriptions are where most people get skill authoring wrong, in my experience. The temptation is to write a description that explains what the skill does, in the voice of documentation. "This skill helps you write research briefs." That description will never match anything, because nobody types "I want to write a research brief" as a query. They type "draft a brief on operating debt for the manufacturing account" or "give me something on governance for the banking target." The description needs to match the vocabulary you actually use, not the vocabulary of the skill's description.
The pattern I use: the description is a list of trigger phrases and canonical terms, written in the same register I would type a prompt in. For the book-reference skill, the description lists every framework name from my book, so any mention of a framework in any prompt fires the skill. For the QA skill, it lists "qa this, run qa, quality check, score this, rubric this, ready to ship, production ready." For the retire skill, it lists "retire session, close out, wrap up, route session, end of session, memory writeback, what did we learn." The descriptions read like a search index, not a manual.
You write the description as if it were a search index for how you actually talk. Then the skill fires when you talk that way. No manual invocation. No remembering which skill applies. Just say the thing and the right bench of tools loads.
This is the single biggest quality-of-life improvement in the environment. Before I understood skill routing, I was manually saying "use the book-reference skill" at the start of every session that touched the book. After, I just talk about the book and the skill fires. The cumulative time savings is substantial. The cumulative friction reduction is larger.
The most recent addition to the setup is the book-reference skill. My book is 320 pages, and until today it had been sitting on my Desktop as a PDF. Every time I wanted Claude to quote from it or verify that I was using a framework name correctly, I had to attach the PDF to the session. Attention would drift, citations would become ambiguous, and by hour two of a session I could not tell whether a definition had come from the book or from Claude's memory. The book was not reliably available.
The fix was to stop treating it as a document and start treating it as a knowledge graph. I ran the PDF through a text extractor, wrote out the full 320 pages to a plain text file with page markers, scanned for chapter headings to compute chapter line ranges, pulled out the glossary definitions, and authored a skill file that routes queries to the right reference. Concept questions ("what is this framework?") load the definitions file. Location questions ("which chapter covers this topic?") load the chapter index. Exact-quote questions run a search against the full text.
The result is that the book is now a first-class citizen of the environment. It loads by skill description, not by manual attachment. Any mention of a framework name from the book fires the skill, and Claude has the canonical definition available without me doing anything. The citations are exact, because they come from a grep-able text file with line numbers. The skill also encodes a handful of definitional distinctions that used to drift in long sessions, so a concept on paper does not get confused with its computational implementation. Nothing drifts.
The generalizable pattern: if you have a long reference document you cite constantly (a book, a methodology, a contract, a regulatory text), do not attach it. Extract it. Turn it into a skill with a router and a references directory. One hour of work, infinite reuse afterward.
My QA process is defined in a canonical document called QA-PROCESS.md in the Site Reference folder. It has two layers: a compliance checklist (brand conformance, copy rules, source accuracy, structural rules) and a value rubric (seven dimensions scored 1 to 5). Both layers are supposed to run before any published research product is marked production-ready.
When I went to wire this into Claude Code, I realized the two layers have different shapes. The compliance checklist is mostly regex-checkable: banned war metaphors, exposed scaffold labels, placeholder href values, voice bans, em-dashes, logo/favicon swaps. These are patterns. A bash script can find them in under a second. The value rubric is not: rating a brief's "strategic depth" from 1 to 5 requires reading the whole thing and forming a judgment. A bash script cannot do that.
So I built two things:
The regex layer runs on every save automatically, catching cheap violations immediately so they never reach the deep pass. The judgment layer runs on demand, grounds every score in the canonical spec verbatim (no paraphrasing from memory), and refuses to hand out a SHIP verdict while any blocker is live.
The generalizable principle: when you are designing a QA system, separate the checks that can be regex from the checks that need judgment, and wire them as different artifacts. Put the regex checks in a hook that fires inline. Put the judgment checks in a skill that fires on demand. The combination catches more than either would alone, and costs less than doing it all by hand.
The close-out ritual at the end of every session is a skill called retire. Its job is to read the session, extract every reusable nugget, and route each one to its correct existing home in my knowledge architecture. Feedback rules go to memory/feedback_*.md. QA failures go to ERROR-LOG.md. Process improvements go to the nearest applicable RUNBOOK.md. New prospects go to the prospect graph. New partners or initiatives go to a Strategy subfolder. Ephemeral content gets dropped.
The important design decision is what retire does not do. It does not write a session dump. It does not create a dated file on the Desktop with everything that happened. Earlier in this build I proposed exactly that, and was correctly told it was wrong: a session dump is not loadable in a future session, so the knowledge never gets reused. The whole point of the close-out ritual is to make the knowledge loadable, which means routing it into files that are already part of the load path.
The second important design decision is that classification is driven by the live folder architecture, not a hardcoded taxonomy. Every invocation of retire starts by scanning the actual folders under the Brain and under Strategy to build a fresh routing map. If I added a new partner subfolder last week, retire discovers it. If I renamed a folder yesterday, retire uses the new name. There is no taxonomy file to update. The filesystem is the taxonomy, and the scan is how retire reads it.
This matters because taxonomies rot. The moment you hardcode a list of destination types, the list starts falling behind the reality. The fix is to not have a list: scan the reality every time and route against what you find. The classification logic is stable (feedback goes to memory, QA fails go to ERROR-LOG, new partners go to Strategy subfolders), but the specific destinations are always current.
Taxonomies cached in code rot. Taxonomies discovered from the filesystem do not. If you can scan, scan.
Retire works as a confirmable diff. It proposes a routing table with one row per nugget (nugget text, type, destination file, action) and waits for me to approve. Then it applies the approved routings, asking for a second confirm on any write to a file that has readers beyond my session (the prospect graph, ERROR-LOG, RUNBOOK, Strategy folders all have readers). Memory files it can write with a single confirm-all, since they are scoped to my context. At the end it writes a one-page breadcrumb manifest to ~/Desktop/Sessions/ showing what went where. The manifest is a pointer, not a copy.
Every few weeks I talk myself into the idea of turning my whole computer into a local NotebookLM: an 8-layer system that indexes every file, extracts entities, builds a graph layer, exposes a query UI, runs a daily freshness cron, and makes the whole machine queryable. I scoped this build multiple times. I even named it: Personal Knowledge Atlas.
I deliberately did not build it. The reasoning is worth stating because it is the sort of reasoning that applies to most ambitious tool builds.
First, the curated graphs already are what an Atlas would produce, lossily. The Brain is hand-built and hand-maintained. An indexer crawling it would produce a less precise copy of a thing I already have in high fidelity. That is wasted work. Second, the actual querying problem is already solved. Claude Code already reads any file I point it at, greps any directory, Globs any pattern. I do not need another query layer; I need better source selection, which is what the MANIFEST and the load-manifest hook now provide. Third, the unstructured material that actually could benefit from indexing (old PDFs in OTHER/, legal docs in Rare Bird Company/, IP filings in IP/, old archives) is a small slice of the Desktop and is queried rarely. A heavy 8-layer system for rare queries is bad return on investment.
The reframe I arrived at: the Atlas as originally scoped is wrong. A narrow indexer for only the unstructured dumping-ground folders, combined with a well-maintained MANIFEST and the load-manifest hook, captures 90% of the value at 10% of the work. Build that. Stop. Revisit the other seven layers only if a real friction appears that the narrow version cannot solve.
This is the most important meta-lesson from five weeks of building tooling around Claude Code. The impressive system is usually wrong. The two-hour thing that captures 90% of the value is usually right. Measure friction in the transcripts, not in the feature list, and build only what the friction tells you to build.
Build anti-Atlases. The small thing that works beats the big thing that impresses.
If you are building your own Claude Code environment for knowledge work, these are the decisions I would copy from this one. In rough order of payoff.
Finder tags encode semantic types that folder hierarchies do not. Red for canonical curated knowledge, green for live deploy, uncolored for everything else. Scope your hooks to colored folders. Claude treats different paths differently, and the harness is where you enforce that.
5 to 15 KB markdown files, structured as graphs, with predictable filename patterns. One Read call loads the whole thing. This pattern outperforms PDFs and document folders in long sessions by a wide margin. It is the single most important technique in this environment.
Long sessions drift. Short sessions force distillation. The cost of restart is only acceptable if you have a close-out ritual that routes reusable nuggets into your key files before you close. Build that ritual. Make it load-bearing.
Write skill descriptions as lists of trigger phrases in the same register you type your prompts in. Not documentation voice. Vocabulary voice. The skill will fire automatically when you talk that way, and you will stop manually invoking things.
If a rule matters enough that Claude forgetting it would be a problem, put the rule in a hook, not in memory. Hooks run by the harness, independent of Claude's context. Memory is load-bearing only when nothing else is.
Split your QA checks into pattern-checkable (hook, inline) and judgment-requiring (skill, on-demand). Both. Not one or the other. The regex layer catches the cheap violations before they reach the judgment layer, which is how you keep the judgment layer from drowning.
If the thing you want available is under 15 KB, load it unconditionally on SessionStart. Do not build a trigger list. Trigger lists rot; always-load does not. This one decision removes an entire category of maintenance debt.
Any skill that classifies things should discover its destinations from the live filesystem at every invocation, not from a hardcoded list. The filesystem changes. Hardcoded lists rot. Scanning is cheap and always current.
When you find yourself scoping an impressive multi-layer system, stop and ask whether the same value is available from two or three small pieces that can be built in an afternoon. The small pieces almost always win on maintenance, reliability, and actual delivered value.
A skill should be a router plus a references directory. The SKILL.md explains when to load which reference. The references hold the actual knowledge. This keeps the router small, makes the skill loadable without reading everything, and lets you version the reference material independently of the routing logic.