Claude Workspace

Dotfiles for Claude — scaffold a structured AI workspace into any project with one command.

Claude Workspace sets up everything you need to work effectively with Claude: a Markdown knowledge vault, curated skills (promptable playbooks), document templates, and a ready-to-use CLAUDE.example.md. It's idempotent, profile-based, and designed for teams and solo builders alike.

---

Installation

npx (no install needed)

Run commands directly with npx:

npx @maggit/claude-workspace init
npx @maggit/claude-workspace doctor
npx @maggit/claude-workspace add-skill prd

Global install (gives you the cws command)

npm install -g @maggit/claude-workspace

Once installed globally, you can use the shorter cws command:

cws init
cws doctor
cws add-skill prd

From source

git clone https://github.com/maggit/claude-workspace.git
cd claude-workspace
pnpm install && pnpm build
node packages/cli/dist/bin.js init --dir ~/my-project

Note: The rest of this README uses cws for brevity. If you haven't installed globally, replace cws with npx @maggit/claude-workspace.

---

Quick Start

# With npx
npx @maggit/claude-workspace init

# Or, if installed globally
cws init

You'll be prompted to pick a profile and vault name, and your workspace is ready.

For non-interactive setup:

cws init --profile engineering-exec --yes

What You Get

your-project/
├── CLAUDE.example.md              # Workspace instructions for Claude (rename to CLAUDE.md)
├── .claude/
│   ├── config.json                # Workspace configuration
│   ├── skills/                    # Promptable mini-playbooks
│   │   ├── prd/SKILL.md
│   │   ├── eng-spec/SKILL.md
│   │   └── ...
│   ├── templates/                 # Document templates
│   │   ├── PRD_TEMPLATE.md
│   │   ├── ENG_SPEC_TEMPLATE.md
│   │   └── ...
│   ├── snippets/                  # Your snippets (empty)
│   ├── logs/                      # Your logs (empty)
│   └── profiles/
│       └── active.json            # Tracks installed files for idempotency
└── ContextDB/                     # Markdown knowledge vault
    ├── README.md
    ├── _index.md
    ├── 00_inbox/
    ├── 01_specs/
    ├── 02_architecture/
    ├── 03_decisions/
    ├── 04_knowledge/
    ├── 05_prompts/
    ├── 06_agents/
    ├── 07_diagrams/
    └── 08_todos/

Setting Up CLAUDE.md

Claude Workspace never touches your CLAUDE.md. It writes CLAUDE.example.md so you stay in control.

New project — rename it:

mv CLAUDE.example.md CLAUDE.md

Existing project with a CLAUDE.md — open CLAUDE.example.md and merge the parts you want (vault references, skill instructions, conventions) into your existing file.

Profiles

Profiles determine which skills and templates get installed:

Profile	Skills	Best for
default	All 9 skills, all 5 templates	Full workspace — everything included
engineering-exec	PRD, eng-spec, requirements, todo, release-plan	Engineering leads and architects
indie-maker	PRD, todo, summary, release-plan	Solo builders shipping fast
marketing	PRD, SEO brief, landing page copy, summary, meeting notes	Content and growth teams

# Use a specific profile
cws init --profile marketing

Skills

Skills are Markdown playbooks that teach Claude how to produce specific document types. They live in .claude/skills/ and are referenced by name:

Skill	Produces
prd.md	Product Requirements Documents
eng-spec.md	Engineering Specifications
requirements.md	Structured Requirements
todo.md	Task Breakdowns
summary.md	Summaries and Recaps
meeting-notes.md	Meeting Notes
release-plan.md	Release Plans
seo-brief.md	SEO Content Briefs
landing-page-copy.md	Landing Page Copy

Commands

init

Scaffold a workspace. Safe to run multiple times — existing files are preserved, unchanged managed files are skipped.

cws init [options]

Option	Description	Default
-d, --dir <path>	Target directory	.
-p, --profile <name>	Profile	default
--vault <name>	Vault folder name	ContextDB
--force	Overwrite user-modified managed files (backs up first)	false
--dry-run	Preview what would happen	false
-y, --yes	Skip prompts, use defaults	false

doctor

Check that your workspace is healthy:

cws doctor

PASS  .claude/ directory exists
PASS  config.json valid (profile: default)
PASS  All 9 skill files present
PASS  All 5 template files present
PASS  Vault directory exists: ContextDB/
PASS  All 9 vault subfolders present
PASS  CLAUDE.md present

add-skill

Install a single skill without running a full init:

cws add-skill prd
cws add-skill --list

Option	Description	Default
-d, --dir <path>	Target directory	.
--force	Overwrite existing skill (backs up first)	false
--dry-run	Preview what would happen	false
-l, --list	List all available skills	false

print-claude-md

Preview the CLAUDE.md content for a profile without writing any files:

cws print-claude-md --profile indie-maker

Idempotency

Running init again is always safe:

• Managed files (skills, templates) are tracked by SHA-256 hash. If the file hasn't changed, it's skipped.
• User-modified files are detected and preserved. Use --force to overwrite (a .bak backup is created first).
• Unmanaged files (existing skills not tracked by the CLI) are skipped with a warning. Use --force to overwrite, or delete them and re-run.
• CLAUDE.example.md is regenerated on each run — it's the reference file, not your working file.
• Vault folders are created if missing, never deleted.

Customization

See docs/customization.md for:

• Creating custom profiles
• Writing new skills
• Adding templates
• Changing vault structure
• Custom CLAUDE.md templates

ContextLoom

Claude Workspace is designed to work with ContextLoom, a Markdown editor for managing project context. The vault taxonomy and file conventions are fully compatible. See docs/contextloom.md for details.

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines on:

• Setting up the development environment
• Adding skills, templates, and profiles
• Code style and testing expectations
• Pull request process

Development

pnpm install        # Install dependencies
pnpm build          # Build (copies assets + compiles TypeScript)
pnpm test           # Run all tests

License

MIT