Build Transformative AI Assistants with Claude Code Workspaces

A Game Changer for Knowledge Workers

My Experience

I’ve been using Claude Code workspaces for about 6 months. They are one of the reasons I’m positive about AI. They’re like auxiliary brains, opening so many doors of opportunity.

I built a workspace for preparing for job interviews. It had MCP tools which researched the interviewer’s LinkedIn, company website, and the role description, and then synthesized the information. It had commands that generated practice questions based on the interviewers’ roles and the position. I used my resume and the job application as grounding references. I had a skill which gave me ideas for what to say for my intro - tailored to the company’s needs.

I’ve never found a good website for homework questions for my son. They’re always full of ads and often inappropriate content. So I built a workspace for it. It knows his interests and customises learning projects based on them and his level. It generates a set of questions on various subjects when requested. Over time I have tweaked it to improve the questions. When the question is complex, we’re able to ask in-depth follow up questions.

I built a workspace for managing my study for a Microsoft exam. It researches the current literature on Microsoft Learn and creates a weekly learning schedule.

I’ve built workspaces for brainstorming, deep research, planning, code generation, code evaluation and more. The opportunities workspaces present are endless. The output they create has been a game changer.

Building a Claude Code Workspace That Actually Works

The problem with basic chat is that it often gets things wrong, but one of the best ways to improve this is to give it grounded information as a baseline. A collection of hardwired instructions, consistent context, and a limited working space.

A workspace is a structured environment that gives Claude persistent context, repeatable skills it executes consistently, hooks that enforce rules it can’t override, and a clear design for what gets loaded when. Once you’ve built one, going back to ad-hoc prompts feels like going back to using a search engine. Oh the horror!

This post walks you through the pattern using a consulting operations workspace as the concrete example: client intake, proposals, status reports. The structure applies to anything repeatable: content pipelines, research workflows, team operations.

First: Get Claude Code Running

Before any of the workspace stuff matters, you need Claude Code installed and running. Here’s how.

Step 1: Install Claude Code

The easiest option is the desktop app. Download it from code.claude.com/docs/en/desktop and run the installer. The desktop app installs everything including the claude terminal command, so Steps 3 and 4 below will work straight after.

If you’re a developer and prefer the CLI directly:

npm install -g @anthropic-ai/claude-code

You’ll need Node.js installed first if you go that route.

Step 2: Open your workspace folder in VS Code

Create a folder somewhere sensible (e.g. my-workspace), then open it in VS Code. File > Open Folder.

Step 3: Open the terminal in VS Code

Press Ctrl+` (backtick, the key above Tab) or go to Terminal > New Terminal. A terminal panel opens at the bottom of the screen. My recommendation - grab the top border and make it take up at least half the screen. :)

Step 4: Run Claude

Type claude and press Enter. Claude Code starts in your terminal, reads your workspace folder, and you can start talking to it.

Everything you build in the workspace - the CLAUDE.md, the context files, the skills - is picked up automatically. Claude reads the folder it was opened in.

One more thing: VS Code also has a Claude Code extension in the marketplace. Same result, slightly friendlier interface. Either works.

The Folder Structure

my-workspace/
├── CLAUDE.md                     # Session constitution, keep it lean
├── .claude/
│   ├── commands/                 # Simple slash commands
│   ├── skills/                   # Rich workflows with bundled assets
│   │   ├── new-client/
│   │   │   └── SKILL.md
│   │   ├── proposal/
│   │   │   ├── SKILL.md
│   │   │   └── proposal-template.md
│   │   └── status-report/
│   │       └── SKILL.md
│   ├── agents/                   # Specialist subagents
│   │   └── research-agent.md
│   └── settings.json             # Hooks
├── context/                      # Always-loaded session context
│   ├── personal-info.md
│   ├── strategy.md
│   └── current-data.md
├── reference/                    # On-demand only, loaded by skills
│   └── client-templates/
└── outputs/
    ├── clients/
    ├── proposals/
    └── reports/

Two things drive every design decision here: the context window and the session lifecycle.

The Design Decision That Matters Most

Every file Claude reads at session start consumes context window permanently for that session. Blow your context budget upfront and you have a sluggish, forgetful Claude by the time you’re halfway through a real task.

The fix is a hard split between what gets loaded every session and what gets loaded on demand:

• Always-loaded (CLAUDE.md + context/): who you are, what you’re optimising for, operational rules. Lean. If removing a line wouldn’t cause Claude to make a mistake, cut it.

• On-demand (reference/, skill assets): style guides, client templates, source link libraries. Loaded only when a specific command needs them.

A 200-line style guide loaded every session costs you context whether you’re drafting or just asking a quick question. Loaded only when /draft-post fires, it costs nothing on sessions where it’s not required.

Most workspace guides tell you to put everything in CLAUDE.md. That is completely wrong. The loaded-vs-on-demand split is the design decision that separates a working harness from one that slowly stops working as your workspace grows.

CLAUDE.md: Should be Lean

CLAUDE.md is auto-loaded every session. Treat it like a constitution, not a knowledge base.

What belongs here:

• Rules that apply to every task (“always respond in British English”, “never commit without running tests”, “never use em dashes”)

• Workspace structure: what the folders are for and how to navigate them

• @context/personal-info.md style imports that pull in context files without embedding them

• Commands available and what they do

What doesn’t:

• Detailed style guides (they go in reference/, loaded by skills)

• Anything that only applies to one type of task

• Information Claude can infer by reading the files

Anthropic’s test is blunt: “Would removing this line cause Claude to make a mistake?” If no, cut it. A bloated CLAUDE.md causes Claude to gradually deprioritise your rules as the session progresses. Not because it ignores them. Because they get buried under more recent context. The rules don’t disappear. They just lose.

Keep CLAUDE.md under 200 lines. Use @path/to/file imports to pull in section-level context rather than embedding everything directly.

Memory: What Claude Learns Automatically

CLAUDE.md is what you write deliberately, upfront. Memory is what Claude writes as it works with you.

Claude’s auto memory system lives outside the repo in its config directory. As sessions progress, it captures things you’d otherwise repeat across sessions: preferences you’ve stated, corrections you’ve made, project context it has learned. Next session, those facts are already there.

What belongs in memory:

• Preferences learned through use (“prefers bullet lists over tables: pushed back on this in post 7”)

• Corrections and feedback (“never use em dashes: corrected twice, now a standing rule”)

• Project context that isn’t in the code (“AI-103 exam target is early June 2026”)

What doesn’t:

• Rules you’ve decided upfront - those go in CLAUDE.md

• Anything that needs to be shared with teammates or version-controlled - memory is private to your Claude config, not in the repo

The distinction: CLAUDE.md is designed. Memory is learned.

One gotcha: memory entries go stale. If a project priority shifts or a preference changes, Claude may still act on an old memory. Audit memories periodically the same way you audit CLAUDE.md.

Context: What Claude Always Knows

The context/ folder is small by design. Three files, not thirty. Claude reads them at the start of every session: who you are, what you’re currently working toward, and the live numbers that inform decisions. Keep them small!

A typical setup - your situation may vary:

• personal-info.md: role, background, relevant expertise

• strategy.md: current priorities and what success looks like

• current-data.md: live numbers, updated weekly

Everything here pays a context window tax on every session. If a piece of information only matters for one type of task, it belongs in reference/, not here.

References and On-Demand RAG

Nothing in reference/ loads unless a skill requests it. That’s the rule.

It’s effectively RAG (Retrieval Augmented Generation - “a technique used to improve the accuracy of Large Language Models (LLMs) like ChatGPT or Gemini by fetching facts from an external, trusted database before generating a response, rather than relying solely on the AI’s internal training memory.”) for your workspace. An exam guide, sample homework questions, your client proposal template, your list of research sources: none of it costs context window unless it’s actually needed. A skill that creates a client proposal loads reference/client-templates/. A skill that researches a topic loads reference/brainstorm/. A plain coding question loads nothing from reference/ at all.

If you’re tempted to put a file in context/ because “Claude might need it,” ask whether it’s needed every session or just on specific tasks. If specific tasks, it belongs in reference/.

Outputs: Where the Work Lives

The outputs/ folder is where Claude writes its deliverables. Structure it by workflow type, not file type:

outputs/
├── casestudies/
│   ├── drafts/
│   └── research/
├── clients/
├── proposals/
└── reports/

In some scenarios, you might need Claude to read items from these folders as inputs to another. This is why separating them logically is important.

Skills: Repeatable Workflows with Bundled Assets

A skill is a markdown file in .claude/skills/<name>/SKILL.md that defines a repeatable workflow. Invoke it explicitly with /skill-name, or let Claude auto-trigger it when it judges the description matches your task.

Anthropic created skills. Read their guide before working with them.

Here’s the client intake skill for the consulting workspace:

---
name: new-client
description: Create a new client project brief from intake information.
             Invoke when setting up a new client or project.
disable-model-invocation: true
---

Parse the following client intake and create a project brief
in `outputs/clients/{client-name}/brief.md`.

Extract:
1. Client name and contact
2. Problem statement  
3. Scope and deliverables
4. Timeline and budget constraints
5. Success criteria

Confirm the brief was created and ask whether to draft a proposal.

Input: $ARGUMENTS

disable-model-invocation: true prevents auto-triggering. Use it on any skill that creates files or has side effects. You want explicit invocation for anything with consequences. Leave it off for knowledge skills Claude should apply automatically, like coding conventions or tone guidelines.

The description matters more than people expect. It’s how Claude decides whether to auto-load the skill. Vague descriptions cause wrong skills to fire. “Handles client work” will trigger on things you didn’t intend. “Create a new client project brief from intake information” will not. Be specific about the exact scenario.

Skills can carry sibling files (templates, reference docs, examples, tools) that load alongside the instructions. The proposal skill carries proposal-template.md. The logic lives in SKILL.md; the reference material sits next to it. Nothing leaks into CLAUDE.md.

Commands: Lightweight Slash Shortcuts

Commands are markdown files in .claude/commands/. You invoke them with /command-name and they run immediately. No sibling assets, no auto-trigger logic. Simple, explicit shortcuts for bounded tasks.

# Image Prompt

Generate a sumi-e style blog header image prompt for post $ARGUMENTS.
Read the brief or draft, identify the central concept and key metaphors,
then output a ready-to-paste prompt for DALL-E, Midjourney, or similar.
Style rules are in `reference/image-style.md`.

Use commands for things you trigger manually on demand: /prime to initialise a session, /research "topic" to kick off an investigation.

/create-plan is worth calling out separately. Before any multi-file change or new feature, it writes a structured implementation plan and waits for your sign-off before touching anything. Claude confirms the right approach first, rather than confidently building the wrong thing. Add it to every workspace that involves code or complex deliverables.

Skills are the right choice when a workflow needs sibling assets, when the logic is long enough to warrant structure, or when you want auto-trigger behaviour. For everything else, a command is faster to write and easier to maintain.

Hooks: Rules Claude Can’t Override

CLAUDE.md instructions are advisory. Claude reads them, weighs them against everything else in context, and may deprioritise them in a long session. Hooks are different. They’re shell commands that run deterministically at specific lifecycle events. Claude can’t reason its way around them. If you don’t know how to script, simply ask Claude to write it.

Configure them in .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"$(date): modified $FILE_PATH\" >> outputs/ledger.md"
          }
        ]
      }
    ]
  }
}

This logs every file write to an audit ledger automatically. No prompting required. Claude can’t skip it.

Use hooks for things that must happen every time with zero exceptions: formatting after file edits, blocking writes to protected directories, logging outputs, running lint before a commit. If it’s important enough that “Claude forgetting” is unacceptable, it belongs in a hook, not CLAUDE.md.

One gotcha: don’t let hooks block mid-edit. Hooks that interrupt Claude while it’s reasoning through a multi-file change break the reasoning chain. Block at the end of a task, not mid-stream.

MCP Servers: External Tool Integration

Model Context Protocol connects Claude to external services: file systems, GitHub, Google Drive, Slack, databases, web search. Each MCP server exposes a set of tools Claude can call directly within a session.

Configure them in .claude/settings.json:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    }
  }
}

With this in place, Claude can read and create PRs, check CI status, and search your repository without you copying anything into the chat. Add web search and Claude can pull current documentation. Add a database MCP and Claude can query your schema directly.

MCP servers run as local processes. Each one consumes resources. Don’t add servers you won’t use. Vet community servers before depending on them: check the last commit date and the issue tracker. Official integrations (GitHub, Google Drive, Slack) are stable. Community servers vary significantly and can be dangerous.

Sub Agents: Specialist Workers

The .claude/agents/ folder holds specialist agent definitions. Each is a markdown file describing a narrow-purpose assistant Claude can spin up for specific tasks.

---
name: research-agent
description: Research agent for web searches and source collection.
             Invoke for background research that shouldn't consume main session context.
---

You are a focused research assistant. Given a topic, search for:
1. Official documentation and release notes
2. Community tutorials and real-world usage examples
3. Known issues or limitations

Return a structured summary with links. Research only: no code, no recommendations.

The main value is context isolation. Hand a task to a sub agent and it runs in its own context window. A research sweep that reads twenty web pages stays in the agent’s context, not yours. Your main session stays clean.

Use sub agents for tasks that are parallel, independent, or context-heavy: background research, specialist review, parallel file analysis. Don’t use them for tasks that need your session’s context. The agent starts fresh. It won’t know what you’ve been doing.

The /prime Session Initialisation Pattern

Every session should start with explicit initialisation. Don’t trust Claude to figure out context from the project root. Depending on what you ask first, it may or may not read the right files.

A /prime skill handles this:

---
name: prime
description: Initialise a new session with full context.
             Run at the start of every session.
---

1. Read CLAUDE.md and context/personal-info.md, context/strategy.md,
   context/current-data.md
2. Summarise your understanding: who I am, what this workspace is for,
   current priorities
3. Confirm readiness to assist

Type /prime. Claude reads the files, summarises back, and you can verify immediately if anything’s missing. Thirty seconds max. Prevents the most common workspace failure: a session where Claude lacks context and you don’t notice until you’ve wasted twenty minutes on outputs that miss the point.

Workspaces vs Claude Cowork

Claude Cowork is Anthropic’s other desktop product, and it’s worth understanding the difference before you commit to building a workspace.

Cowork is designed for autonomous, goal-driven tasks. You give it an outcome (“prepare a briefing document from these three reports”) and it handles the steps: opening files, synthesising information, producing the deliverable. No programming required. It’s aimed at researchers, analysts, and knowledge workers who need Claude to operate on their local files without any setup.

A Claude Code workspace is the opposite philosophy. You define the structure, the context, the rules, and the repeatable workflows. Claude follows them consistently across every session.

Claude Cowork is the right choice when:

• The task is one-off or hard to predict in advance

• The user isn’t technical and won’t be configuring anything

• You want autonomous execution with minimal setup

A Claude Code workspace is the right choice when:

• You run the same workflows repeatedly and want consistent results

• You need hooks that enforce rules Claude can’t reason around

• You want context that persists and compounds across sessions

• You’re a developer who wants programmatic control over how Claude operates

Most technical people will end up using both. Cowork for ad-hoc heavy lifting. A workspace for the repeatable stuff that needs to work the same way every time.

Gotchas

CLAUDE.md bloat kills rule adherence. Past ~200 lines, rules start getting quietly ignored. Claude doesn’t warn you. Audit your CLAUDE.md periodically and prune anything that doesn’t pass the mistake test. If you’ve added something since day one that Claude was already doing correctly, delete it.

Skill descriptions consume context on every tool call: roughly 2% of your context window per skill, even if the skill isn’t active. Keep descriptions to 2-3 lines. Don’t write essays in the frontmatter; you’re paying for that space in every session.

The on-demand split requires discipline. The moment you put detailed reference material in context/ instead of reference/, you’ve broken the pattern. Strict rule: if a piece of information only matters for one type of task, it doesn’t go in context/.

Session context drifts in long sessions. /clear between unrelated tasks is not optional. It’s how you maintain output quality. Mixing research, drafting, and code review in one session produces mediocre results across all three. The instructions are still there. The signal-to-noise ratio isn’t.

MCP server quality varies significantly. Before depending on a community MCP server, check the last commit date. The ecosystem has a long tail of abandoned projects. Official integrations (Google Drive, GitHub, Slack) are stable; community servers need vetting before you build workflows on top of them.

What to Build First

Start small. Don’t wire up MCP on day one or write six skills before you’ve tested one.

1. Create the folder structure: directories only, no content yet

2. Write CLAUDE.md: twenty lines maximum, workspace structure and core rules

3. Add context/personal-info.md: who you are and what this workspace is for

4. Write one skill: pick the task you do most often, document its steps

5. Add a /prime skill: one invocation that confirms Claude has context

6. Add one hook: start with an output ledger, low-risk and immediately useful

The workspace pattern compounds. A working harness with three skills beats an over-engineered one with twelve half-tested ones.

You’ll find that the demands grow as you use your workspace. You’ll consistently create new commands, plugins and skills for various things as they come up. But start with a basic workflow.

Tell Claude to Improve Its Own Workspace

Here’s something I’ve found really useful: ask Claude to modify the workspace itself.

If you find yourself typing the same instruction at the start of every session, tell Claude to add it to CLAUDE.md. If a task you do repeatedly doesn’t have a command yet, ask Claude to build one. The workspace doesn’t have to be designed upfront. It can grow from usage.

Some examples of what this looks like in practice:

• “I keep having to tell you to check the briefs file before drafting. Add that as a rule in CLAUDE.md.”

• “Build me a command called /weekly-review that reads context/current-data.md and outputs a summary of progress against my targets.”

• “I want a skill that generates LinkedIn posts from a blog draft. Look at how /draft-post works and create something similar.”

Claude writes the markdown, creates the file, and confirms what it did. You review it, ask for tweaks, and move on. No separate design session required.

The best workspaces I’ve built weren’t architected in one sitting. They accumulated through use. Every time friction showed up, I turned it into a command or a rule.

Optimising Your Workspace

A workspace that worked well at week one will have friction by week eight if you don’t maintain it. Three areas to audit regularly.

CLAUDE.md: Run the mistake test on every line. “If I removed this, would Claude make a mistake?” Anything that doesn’t survive the test is noise. Also check for rules Claude was already following correctly before you wrote them down. You’re paying context window for instructions you don’t need.

Skills and commands: Vague descriptions cause wrong skills to fire. If a skill is auto-triggering on tasks you didn’t intend, tighten the description. If you have skills you haven’t used in a month, archive them. Description overhead accumulates even for idle skills.

Hooks: Review what’s actually firing. The audit ledger is your ground truth. If a hook isn’t appearing when it should, the matcher is wrong. If it’s appearing on tasks where it’s irrelevant, the matcher is too broad.

Beyond maintenance, the fastest way to level up a workspace is to use a skill like claude-code-mastery. Add it to your skills folder and call it with /claude-code-mastery and it will assess your workspace. The last time I ran this it found a few optimisations that dropped my initial context from 10000 to 100 tokens. For real! Highly recommended.

The other signal is your own session transcripts. If you’re repeatedly typing the same instructions at the start of a session, that’s missing context file info or missing MEMORY. If you’re correcting Claude on the same point every few sessions, that’s a hook or rule that needs to be written. Let your friction tell you what to build next.

The Pattern Scales

The same structure works whether you’re running a content pipeline, a learning workspace, an interview preparation tool, a team operation, or a solo research workflow. The skills change. The context files change. The design decisions don’t.

CLAUDE.md is the constitution.

context/ is the always-loaded minimum.

reference/ is the on-demand library.

Skills are repeatable procedures.

Hooks are non-negotiable rules.

/prime is the session handshake.

Build it once. Adjust the skills for your domain. Spin it up for each project or client as a template.

Now you’re using AI properly.

---

Building your own Claude Code workspace? I’d like to hear what use case you’re targeting and what benefits you’ve found. Drop a comment at LinkedIn.