Research-backed structure, as of June 29, 2026

Canonical Claude File Structure for Knowledge Work

A Windows-first layout for turning Claude into a chief of staff and second brain across multiple clients, while keeping context precise, auditable, and safely separated.

View the hierarchy Read sample files Design ingestion

The operating principles

The important move is not "put everything in CLAUDE.md." The best structure puts each kind of knowledge where Claude will see it at the right time and only at the right time.

1 Keep always-loaded context short

CLAUDE.md should hold facts and durable instructions Claude needs in every session. Target under 200 lines. Procedures, checklists, and large references belong in skills or path-scoped rules.

2 Separate global, client, and project scope

Your user-level files should describe how you work. Client files should describe the client. Project files should describe the current workstream. Mixing these is how context leakage starts.

3 Use skills for repeated workflows

If you paste the same prompt, checklist, or procedure more than twice, make it a skill. Skills are loaded only when relevant, so they are ideal for ingestion, meeting prep, weekly review, and client brief generation.

4 Use subagents for clean context

Research, code review, meeting synthesis, privacy review, and indexing should run in focused subagents so their long file reading does not pollute the main conversation.

5 Use MCP for live systems

Google Workspace, Notion, GitHub, Fireflies, calendars, and task systems should be connectors or MCP servers. Store source pointers and summaries locally, not credential-bearing exports.

6 Use hooks for hard guarantees

CLAUDE.md guides behavior; it does not enforce it. Use hooks and permission rules for "never read another client's folder," "block destructive commands," and "log ingestion writes."

The recommended hierarchy

This layout assumes Windows throughout, high Claude plan capabilities, and connections to Google Workspace, Notion, Fireflies, GitHub, and client-specific repositories.

Canonical Claude Structure - File Explorer

C:\Users\Sean.ai

Name Type Purpose

Ready Use this as the mental model for your ClaudeOS folders.

What belongs where

A practical routing table for deciding whether something is a memory, rule, skill, subagent, MCP config, hook, or vault note.

Need	Put it here	Why	Example
Always-on personal preferences	`%USERPROFILE%\.claude\CLAUDE.md`	Loaded into every Claude Code session.	Writing tone, default meeting outputs, your source citation expectations.
Always-on project/client context	`...\project\CLAUDE.md`	Shared with collaborators and scoped to a workstream.	Client goals, current deliverables, source-of-truth docs, review rituals.
Private project preferences	`CLAUDE.local.md`	Loaded after project instructions, but not committed.	Your sandbox folders, private reminders, local export locations.
Path-specific instructions	`.claude\rules\*.md`	Loads only when matching files are relevant if you add `paths` frontmatter.	Rules for meeting transcripts, contracts, financial models, or GitHub PR work.
Repeatable multi-step workflow	`.claude\skills\name\SKILL.md`	On-demand context with optional scripts and references.	Ingest raw input, prepare board brief, convert meeting to decisions and tasks.
Specialist worker	`.claude\agents\name.md`	Separate context, model, tools, memory, and MCP access.	Librarian, privacy reviewer, Fireflies meeting synthesizer, GitHub maintainer.
External apps and data sources	`.mcp.json` or Claude app connectors	MCP and connectors let Claude query live systems instead of relying on stale pasted exports.	Notion, GitHub, Google Drive, Gmail, Calendar, Fireflies API wrapper.
Hard safety or quality gates	`settings.json` hooks and permissions	Instructions are guidance; hooks and permissions can block, log, or require approval.	Deny reading other client folders; log writes to index files; block secret files.
Canonical second-brain knowledge	`%USERPROFILE%\ClaudeOS\...`	Stable, tool-independent, reviewable knowledge base.	Client context, stakeholder maps, decisions, open loops, source registry.

Sample contents

These are intentionally opinionated starter files. Replace the bracketed values with your actual clients, tools, and retention rules.

# Sean's Claude Operating Context

## Role
Act as my chief of staff, research partner, and second-brain operator. Help me turn scattered inputs into decisions, plans, briefs, and durable knowledge.

## Global working rules
- Be source-grounded. Distinguish facts, assumptions, and recommendations.
- Prefer concise executive outputs unless I ask for exhaustive detail.
- Preserve client boundaries. Do not mix facts from one client into another client's work unless I explicitly ask for cross-client synthesis.
- When using connected tools, cite the source system and item title or URL whenever practical.
- When a task creates reusable process knowledge, suggest whether it belongs in a skill, rule, or client note.

## Canonical local knowledge root
- My second-brain vault lives at `C:\Users\Sean.ai\ClaudeOS`.
- Raw inputs go to `00-inbox\raw` before normalization.
- Client-specific knowledge goes under `03-clients\<ClientName>`.
- Shared frameworks and reusable thinking go under `04-library`.

## Preferred outputs
- Meeting prep: context, likely agenda, stakeholder notes, unresolved questions, recommended asks.
- Meeting synthesis: decisions, action items with owners, open loops, risks, source links.
- Client briefs: answer first, evidence, risks, recommended next moves.
- Weekly review: commitments made, commitments received, blocked items, decisions needed, stale items.

## Memory hygiene
- Add durable personal workflow preferences to user memory only when they apply across projects.
- Add client facts to the relevant client vault, not global memory.
- If a memory may be sensitive, ask before saving it.
- If two instructions conflict, prefer the project/client instruction over this user-level file.

## Integrations
- Google Workspace: use for Gmail, Calendar, Docs, Sheets, Slides, and Drive context.
- Notion: use for tasks, project specs, operating docs, and client workspaces.
- Fireflies: use for meeting transcripts, speaker notes, and action item extraction.
- GitHub: use for issues, PRs, engineering delivery, and code review context.

# Acme Co - 2026 Market Entry Project

## Client boundary
This folder is only for Acme Co. Do not use facts from other clients unless the user explicitly asks for cross-client pattern analysis.

## Objective
Help Acme decide whether to enter the US mid-market healthcare segment in Q4 2026, and prepare the board-ready recommendation.

## Sources of truth
- Client context: `..\..\client.md`
- Stakeholders: `..\..\stakeholders.md`
- Decisions: `..\..\decisions.md`
- Open loops: `..\..\open-loops.md`
- Source registry: `..\..\source-map.yaml`
- Notion workspace: Acme Co / Market Entry
- Google Drive folder: Acme Co / 2026 Market Entry
- Fireflies tag: `acme-market-entry`
- GitHub org: `acme-co`

## Work products
- Executive memo in `deliverables\board-memo.md`
- Market map in `deliverables\market-map.xlsx`
- Risk register in `deliverables\risk-register.md`
- Weekly decision log updates in `..\..\decisions.md`

## Operating rules
- Start by checking `open-loops.md` and the latest meeting notes.
- Use citations for all claims that came from docs, email, meetings, or web research.
- Mark inferred claims as `Inference`.
- Never write secrets, access tokens, private email addresses, or payment details into durable markdown.
- Before finalizing a deliverable, run the `source-audit` skill and update `source-map.yaml`.

## Completion standard
A task is done when the relevant deliverable is updated, the decision or open loop file is current, and any follow-up actions are captured with owner and due date.

# Local Acme Notes

This file is private to my machine and should be listed in `.gitignore`.

## Local paths
- Fireflies exports land in `C:\Users\Sean.ai\Downloads\Fireflies\Acme`
- Temporary analysis files may be written to `C:\Users\Sean.ai\ClaudeOS\00-inbox\raw\acme-temp`

## Private reminders
- Ask before sending any outbound messages.
- Prefer drafts for email and Slack unless I explicitly say to send.
- When preparing for Acme meetings, check my calendar for adjacent meetings and leave prep notes concise.

## Do not store here
- API keys
- OAuth tokens
- Client confidential documents that belong in Drive, Notion, or the client vault
- Long-term facts that should be promoted to `client.md`, `context.md`, or `decisions.md`

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "autoMemoryEnabled": true,
  "autoMemoryDirectory": "C:\\Users\\Sean.ai\\ClaudeOS\\03-clients\\Acme-Co\\projects\\2026-market-entry\\.claude-memory",
  "permissions": {
    "allow": [
      "Read(C:\\Users\\Sean.ai\\ClaudeOS\\03-clients\\Acme-Co\\**)",
      "Read(C:\\Users\\Sean.ai\\.claude\\**)",
      "Write(C:\\Users\\Sean.ai\\ClaudeOS\\03-clients\\Acme-Co\\**)",
      "Bash(git status)",
      "Bash(git diff *)"
    ],
    "deny": [
      "Read(C:\\Users\\Sean.ai\\ClaudeOS\\03-clients\\Other-Client\\**)",
      "Read(**\\.env)",
      "Read(**\\.env.*)",
      "Read(**\\secrets\\**)",
      "Bash(rm -rf *)"
    ]
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "powershell.exe -ExecutionPolicy Bypass -File .claude\\hooks\\log-knowledge-write.ps1"
          }
        ]
      }
    ]
  },
  "skillOverrides": {
    "legacy-context": "off",
    "source-audit": "on"
  }
}

{
  "mcpServers": {
    "notion-acme": {
      "type": "http",
      "url": "https://mcp.notion.com/mcp"
    },
    "github-acme": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "fireflies-acme": {
      "type": "stdio",
      "command": "node",
      "args": [
        "C:\\Users\\Sean.ai\\ClaudeOS\\04-library\\mcp-servers\\fireflies\\server.js",
        "--client",
        "Acme-Co"
      ],
      "env": {
        "FIREFLIES_API_KEY": "${FIREFLIES_API_KEY}"
      }
    }
  }
}

---
paths:
  - "meetings/**/*.md"
  - "meetings/**/*.json"
---

# Meeting Transcript Rules

- Preserve the original transcript as a source. Do not overwrite raw exports.
- Extract decisions separately from action items.
- Every action item must include owner, due date if stated, source meeting, and confidence.
- If a speaker is ambiguous, mark owner as `Unassigned` and add an open question.
- Promote durable facts to `context.md` only after they appear in a reliable source.
- Add or update `source-map.yaml` whenever a meeting note informs a deliverable.

---
name: librarian
description: Maintains the client knowledge vault, indexes raw inputs, finds stale or conflicting notes, and updates source maps. Use for ingestion, organization, retrieval, and knowledge hygiene.
tools: Read, Write, Grep, Glob, Bash
model: inherit
memory: project
skills:
  - ingest-raw-input
  - source-audit
---

You are the knowledge librarian for this client workspace.

When invoked:
1. Identify the client and project boundary from the current folder.
2. Read the relevant `client.md`, `source-map.yaml`, and `open-loops.md`.
3. Normalize new inputs before updating canonical notes.
4. Never merge facts across clients unless explicitly instructed.
5. Preserve source links and mark uncertainty.
6. Update index files after canonical files change.

Output:
- What changed
- Sources touched
- Open questions created
- Follow-up actions for the user

---
source_id: acme-fireflies-2026-06-28-product-council
client: Acme-Co
project: 2026-market-entry
source_type: meeting_transcript
source_system: Fireflies
source_url: https://app.fireflies.ai/view/...
captured_at: 2026-06-28T15:42:00-04:00
meeting_date: 2026-06-27
confidentiality: client-confidential
retention: client-policy
status: normalized
---

# Product Council - Market Entry Discussion

## Summary
The team aligned that the initial market-entry recommendation should compare direct sales, channel partnership, and wait-and-learn options.

## Decisions
- Decision: Keep channel partnership as a live option for board review.
  - Owner: Maya Chen
  - Source: Fireflies transcript, 00:18:22
  - Confidence: high

## Action items
- Action: Sean to draft comparison table for the three options.
  - Owner: Sean
  - Due: 2026-07-02
  - Source: Fireflies transcript, 00:41:08

## Open questions
- Which partner economics are confirmed versus assumed?
- Can legal approve use of de-identified case studies in the board deck?

## Canonical updates proposed
- Add channel partnership option to `context.md`.
- Add partner economics uncertainty to `open-loops.md`.
- Link this source in `source-map.yaml` under `market-entry-options`.

Ingestion, organization, and indexing

The second brain works when raw inputs become source-backed, client-scoped knowledge. Treat ingestion as a pipeline, not a paste pile.

Capture raw source

Save the original item or stable pointer in 00-inbox\raw. Examples: Fireflies transcript export, Google Doc URL, email thread permalink, Notion page URL, GitHub issue URL, PDF, CSV, or handwritten note photo. Do not edit this copy.

Normalize with metadata

Create a markdown or JSON note in 00-inbox\normalized with frontmatter: client, project, source system, URL, timestamp, confidentiality, retention, people, topics, and status.

Classify and route

Assign the item to one client, one primary project, and any reusable areas. If it touches multiple clients, keep separate notes and add a cross-client synthesis only when explicitly allowed.

Extract structured facts

Pull out decisions, action items, promises, risks, dates, stakeholders, constraints, terms, source claims, and open questions. Mark confidence and separate direct quotes from inference.

Promote to canonical files

Update the smallest correct file: decisions.md for decisions, open-loops.md for unresolved items, stakeholders.md for people, timeline.md for events, and context.md for durable project facts.

Update indexes

Append to source-map.yaml, source-registry.yaml, and any topic index. Include source IDs so every claim in a deliverable can be traced back.

Review and prune

Run a weekly review skill to find stale facts, duplicate sources, unresolved open loops, and unpromoted normalized notes. Archive closed projects, but keep source registries.

Minimum viable indexes

source-registry.yaml tracks every source globally. client-map.yaml maps clients to folders, repositories, Notion spaces, Drive folders, Fireflies tags, and GitHub orgs. source-map.yaml inside each client maps specific source IDs to claims, decisions, deliverables, and open loops.

Retrieval rule

Claude should answer from canonical client files first, then source registry, then live connectors, then web. If those disagree, it should show the conflict instead of silently picking the most recent-looking item.

How to write a great skill

The best skills are small doors into larger expertise. Claude sees the name and description first, then loads the body and supporting files only when needed.

Skill design checklist

Use a specific name that maps to a real workflow, such as meeting-to-actions.
Write a trigger description with "use when" language and negative boundaries.
Put only the essential workflow in SKILL.md.
Move long taxonomies, examples, and schemas into references\.
Put deterministic cleanup, parsing, or export work in scripts.
Use disable-model-invocation: true for workflows with side effects that should be manual.
Use context: fork for research-heavy skills that should not clutter the main session.
Evaluate skills from fresh sessions with realistic prompts.

`ingest-raw-input\SKILL.md`

---
name: ingest-raw-input
description: Ingests raw knowledge inputs into the client vault. Use when the user provides meeting transcripts, emails, Google Docs, Notion pages, PDFs, GitHub issues, or notes that should become organized second-brain knowledge.
allowed-tools: Read, Write, Grep, Glob, Bash
---

## Goal
Turn raw inputs into source-backed, client-scoped knowledge without losing provenance.

## Workflow
1. Identify source type, client, project, confidentiality, and source URL or file path.
2. Save or reference the raw source. Do not overwrite raw inputs.
3. Create a normalized note with frontmatter from `references/metadata-schema.md`.
4. Extract decisions, action items, open loops, risks, dates, people, and claims.
5. Propose canonical file updates before writing them if the source is ambiguous.
6. Update `source-map.yaml` and `99-logs/ingestion-log.md`.
7. Report what changed, what remains uncertain, and what should be reviewed by the user.

## Guardrails
- Never mix clients.
- Never store credentials, secrets, personal contact details, or payment details.
- If a source contains sensitive personal data, summarize minimally and point back to the source system.
- If the source conflicts with existing notes, create an open question instead of silently overwriting.

Key idea: put durable facts in CLAUDE.md, procedures in skills, specialist roles in agents, live data access in MCP/connectors, and hard guarantees in hooks or permissions.

Recommended agent team

For chief of staff work, agents should mirror jobs you would give a trusted operator: gather, synthesize, audit, and prepare. Keep their tools narrow.

Chief of Staff

Coordinates calendar, open loops, priorities, and outbound drafts. Should ask before sending messages or modifying external systems.

Tools Google Workspace, Notion, Fireflies summaries, Write drafts.

Librarian

Maintains client vaults, source maps, taxonomies, stale-context flags, and ingestion logs.

Tools Read, Write, Grep, Glob, ingestion and source-audit skills.

Meeting Synthesizer

Turns Fireflies transcripts and calendar context into decisions, actions, risks, and prep notes.

Tools Fireflies MCP, Calendar, Drive read, project vault write.

Privacy Reviewer

Checks whether a task risks crossing client boundaries, storing sensitive data, or exposing credentials.

Tools Read-only access plus hooks for blocking writes if needed.

Research Analyst

Runs web and document research, keeps claims cited, and separates facts from inference.

Tools Web research, Drive, Notion, source registry read/write.

GitHub Maintainer

Maps issues, PRs, client commitments, engineering notes, and delivery risks back to the client plan.

Tools GitHub MCP, repository read, PR review, issue updates with approval.

Permission note: high access is useful, but broad access is not the same as good context. Give each agent the minimum tools needed for its job and keep client folders as the boundary.

Integration pattern

Use Claude app connectors for broad work context and MCP for Claude Code workflows that need repeatable, project-scoped access.

System	Use it for	Recommended scope	Vault output
Google Workspace	Gmail, Calendar, Docs, Sheets, Slides, Drive, meeting prep, status reconstruction.	User connector for personal work context; Drive folders referenced per client.	Meeting briefs, source IDs, doc pointers, action items, decisions.
Notion	Tasks, specs, team docs, project databases, client operating pages.	Project MCP server when a client/project has its own Notion space.	Canonical links, task snapshots, decisions, open loops.
Fireflies	Transcripts, speaker labels, action items, meeting summaries.	Client-tagged API wrapper or trusted MCP server; avoid global transcript dumps.	Normalized meeting notes and source-map entries.
GitHub	Issues, PRs, repo state, engineering delivery, review context.	Project MCP for client repos; user MCP for personal/open-source repos.	Delivery risks, issue summaries, PR decisions, changelog notes.
Claude Projects / chats	High-level conversational work and artifact creation.	Mirror client boundaries: one project per client or major workstream.	Export durable outputs back to the vault; do not let chat history become the only source of truth.

Anti-patterns to avoid

Most Claude knowledge systems fail by becoming too broad, too stale, or too implicit.

Context bloat

Do not load every client, every preference, and every process into one global CLAUDE.md. Use scoped project files, path rules, and skills.

Skill leakage

Do not make one giant skill that does ingestion, client strategy, calendar triage, and GitHub review. One skill should do one workflow well.

Untraceable summaries

Never promote a summary into canonical knowledge without source IDs. Every durable claim should know where it came from.

Client bleed

Never run Claude from the root of all clients for normal work. Launch from the relevant client/project folder unless you are intentionally doing cross-client synthesis.

Build order

Start small enough that you will actually maintain it. Then let Claude help you refine the structure as repeated work appears.

Create the user layer

Write %USERPROFILE%\.claude\CLAUDE.md, one or two global rules, and a conservative settings.json with credential-file denies.

Create the vault skeleton

Create ClaudeOS with inbox, index, client, library, template, and log folders. Add one real client only.

Make one client project canonical

Add project CLAUDE.md, CLAUDE.local.md, project settings, and .mcp.json. Launch Claude from that folder.

Add three skills

Start with ingest-raw-input, meeting-to-actions, and weekly-review. Add references and scripts only when the workflow proves it needs them.

Add two agents

Start with librarian and privacy-reviewer. Expand to chief-of-staff and meeting-synthesizer after ingestion is reliable.

Run weekly memory hygiene

Audit auto memory, source maps, open loops, and stale claims. Promote useful lessons into rules or skills; delete noise.

Research basis

This guide is synthesized from Anthropic documentation and product posts, plus external research on agent manifests and knowledge modules.