A personal OS with Claude Code
A folder of text files that works as memory and dashboard for Claude Code: an inbox, rules, agents and commands. A skill builds it with you, step by step.
What it is for and what it changes
A personal OS is a folder of plain text files (in Markdown, which any editor opens) where Claude Code files what you hand it, finds what was decided and prepares what comes next. Without memory, every conversation with Claude starts from zero. With this folder, the conversation is disposable and the folder becomes the memory: what matters is written in a file, and Claude rereads the files before answering.
What the folder contains
- inbox/
- The drop box. You slide raw material into it: a meeting transcript, notes, a copied email.
- CLAUDE.md
- The ingestion rules. Claude Code reads this file at the start of every session: it says who you are and how to handle new information.
- .claude/agents/
- Specialised agents. An agent is an assistant with its own instructions and its own permissions (for example, read but never write).
- .claude/commands/
- Commands. A command is a shortcut you type in Claude Code, such as /inbox.
- 05_scope/views/
- Generated views. These are tables produced by a small script from the topic sheets: you never edit them by hand.
Three concrete benefits
No decision gets lost
Every decision is recorded with its reason and its source. Three months later, you can find out why a choice was made without reopening the discussion.
You know what to do next
Every topic has an owner and a next action. The task board and the views update from your notes, with no copying.
Switching topics costs less
One sheet per topic, one fact in one file. You reopen a project in a few minutes, and a meeting is prepared from what was said last time.
What you need
01
Claude Code installed
The claude command answers in a terminal. If that is not done yet, the Claude Code guide covers the installation.
02
An empty folder
For example ~/brain. It is the only place where Claude writes for this project.
03
About 30 minutes
For the starting interview, the structure and a first try with a real note.
Optional: Python 3 to generate the views, and Git to be able to go back.
Install the skill
The personal-os skill leads the setup step by step. A skill is a folder of instructions that Claude reads when the task fits: here, it asks the questions, proposes the folders and writes the files once you agree.
The file comes from the latest release published on GitHub.
marcus-clay/design-skillsFor Claude Code
In a terminal:
curl -L -o personal-os.zip \
https://github.com/marcus-clay/design-skills/releases/latest/download/personal-os.zip
unzip -o personal-os.zip -d ~/.claude/skillsFor Codex
Same download, another folder:
curl -L -o personal-os.zip \
https://github.com/marcus-clay/design-skills/releases/latest/download/personal-os.zip
unzip -o personal-os.zip -d ~/.agents/skillsFor Claude.ai
Download the zip, then open Settings, Capabilities, Skills and upload the file.
Then start the setup
Open a terminal in your empty folder, run claude, then write:
What you tell Claude
Create my personal OS with the personal-os skill.
Build it step by step
Seven steps, in this order the first time. For each one you see what you tell Claude, what you get, and an excerpt from a file of the example brain at Acme Corp (a fictional company). The skill writes the files in the language you pick at question 6: the excerpts are shown here in the language of the page, and the folder names stay the same.
Step 1 / 7
The starting interview
Claude asks seven questions, one at a time, waiting for your answer to each. Short answers are enough. At the end it sums up what it understood in ten lines and waits for your approval.
What you tell Claude
Create my personal OS with the personal-os skill. Start with the starting interview.
What you get
- 1. Your role and your team, in one sentence: the "Who I am" section of CLAUDE.md.
- 2. Your three to five current projects: one topic sheet per project.
- 3. The people you work with most: the directory.
- 4. The material you receive (transcripts, emails, notes): the inbox sorting.
- 5. Where to carry over what you produce (wiki, ticket tool): CHANGELOG.md.
- 6. Your language and writing rules: the "Style" section.
- 7. The rhythm of your reviews: which commands and agents to install first.
Step 2 / 7
The structure
Claude proposes the folder tree, then creates it once you say yes. One principle guides everything: one file, one topic, a neutral name. No file carries a person’s name; what concerns a person goes in the directory.
What you tell Claude
Propose the folder tree from my answers. Create it only once I have said yes.
What you get
- The base folders, with the role of each: inbox/ and archive/ for raw material and where it goes once processed, 00_journal/ for the histories, 01_steering/ for the board, 04_decisions/ for the register, 05_scope/ for the sheets and views.
- The journal, register, board and sheet templates, filled in with your answers.
brain/ brain/ CLAUDE.md rules read by Claude Code at every session README.md index for humans CHANGELOG.md what to carry over to external tools inbox/ raw material to process archive/ processed originals (never edited) 00_journal/ journal.md dated journal (append only) timeline.md dated facts (append only) activity/ generated day-by-day views 01_steering/ board.md tasks by horizon 02_product/ one file per product or theme 03_team/ directory.md directory of people 04_decisions/ decision-register.md decisions and reasons (append only) 05_scope/ sheets/ one sheet per topic views/ generated tables (do not edit) 06_resources/ glossary.md glossary and names to reconfirm _to-decide/ what is waiting for an answer scripts/ build_views.py .claude/ agents/ one file per agent commands/ one file per commandStep 3 / 7
The CLAUDE.md file
CLAUDE.md is read automatically by Claude Code at every session. It holds the rules of the game: who you are, what Claude does when information arrives, the safety rules and the writing style. Keep it short (one to two pages): the detail lives in other files that Claude reads when needed.
What you tell Claude
Write the CLAUDE.md from my answers, in one to two pages. It must contain the ingestion protocol, the freshness rule, the append-only files and the safety rules.
What you get
- A CLAUDE.md that says who you are, how to handle new information, and what Claude never does without your approval.
- The list of names that transcription tools often garble, to complete over time.
CLAUDE.mdExcerpt from the Acme Corp brain (fictional) ## Who I am Sam leads a small team of designers on two products: Acme Portal (customer area) and Acme Insights (dashboards). Sam works with Dana (VP Product), Riley (CTO) and Morgan (product designer). ## When new information arrives 1. Add a dated entry to 00_journal/journal.md. Domain in brackets, → action, ? question, ! watch point, nothing in front of a plain fact. 2. Extract the actions and propose them for 01_steering/board.md, with their owner. Never set a deadline unless Dana, Riley or an official document gave it. 3. Route decisions to 04_decisions/decision-register.md (context, decision, reason, consequences; "reason not documented" if missing). 4. Never repeat a fact already written elsewhere: point to the file. ## Safety - Propose first, write after explicit approval. - Never invent a decision, an action or a deadline. - Never delete or move anything without approval, apart from the inbox to archive flow.Step 4 / 7
Agents and commands
An agent and a command are plain Markdown files in the .claude/ folder. Start small: the inbox-ingestion agent with the /inbox command to process what you drop, then the /journal command to log a quick note. The rest comes when the need appears.
What you tell Claude
Install the inbox-ingestion agent and the /inbox command, then the /journal command. Check that they show up in /agents.
What you get
- The files .claude/agents/inbox-ingestion.md and .claude/commands/inbox.md, then .claude/commands/journal.md.
- Five more agents available when you need them: board-review (board review), consistency-check (consistency, read only), deliverables-writer (writing), meeting-prep (meeting preparation, read only), decision-advisor (stress-testing a decision, read only).
- The /review-board, /prep-1to1 and /propagate commands for later.
.claude/agents/inbox-ingestion.mdExcerpt --- name: inbox-ingestion description: "Processes a file dropped in inbox/ (minutes, note, transcript). Separates decisions, actions, facts and open questions. Proposes everything, writes only after explicit approval." tools: Read, Grep, Glob, Edit, Write --- # Processing an inbox file Read CLAUDE.md, 03_team/directory.md and 06_resources/glossary.md first. ## Limits - No decision, action or deadline invented. An idea mentioned is an open question. - No deletion. No name corrected from memory. - A fact lives in one file only: the journal points to it, it does not copy it..claude/commands/inbox.mdExcerpt --- description: Process the files dropped in inbox/ argument-hint: [name of a file in inbox/, optional] --- Process what is dropped in inbox/. Use the inbox-ingestion agent. 1. List inbox/. If it is empty, say so and stop. 2. Read each file in full. Give one verdict per file. 3. Present the numbered list of changes (file, before, after, source, status). 4. Write nothing until I have written "approve all" or a list of numbers. 5. After approval: write, add the CHANGELOG.md entry, move the original to archive/.Step 5 / 7
The first try with the inbox
Write or paste a real note, even a short one, into inbox/ (for example inbox/2026-01-15_team-sync.txt), then type /inbox. Claude reads the file in full, spots doubtful passages, checks it against what exists and returns a numbered list of proposed changes. Nothing is written until you answer.
What you tell Claude
/inbox
What you get
- A numbered proposal: for each line, the file, the before, the after, the source and the status.
- A "possible, not retained" list for the actions Claude deduces on its own, and the points to reconfirm.
- You answer "approve 1, 2, 4" or "approve all". Claude writes, moves the original to archive/, adds a line to CHANGELOG.md and reruns the views script.
proposition de ClaudeExcerpt of the proposal (fictional) 1. 00_journal/journal.md, add the entry of 12 March 2026 [PROD] 2. 04_decisions/decision-register.md, add D-003 Decision: onboarding checklist v1 only shows for new accounts Reason: limit the technical load before summer (said by Riley) 3. 02_product/products.md, fix in place Before: saved-filters API planned for June 2026 After: planned for April 2026 (previous value: June 2026, before 12 March) 4. 01_steering/board.md, 3 actions with their owner Possible, not retained: measure the activation rate (deduced, not said) To reconfirm: "Dina" (Dana?), "postpone the filters" (idea or decision?)Step 6 / 7
The routines
A memory is only useful if you feed it at regular intervals. Four rhythms are enough to start. Ask Claude to write them in the README.md of the folder, where you will see them.
What you tell Claude
Write my four routines (daily, after a meeting, weekly, before a 1:1) in README.md, with the command for each.
What you get
- A "Routines" section in README.md, which the "Day to day" chapter below details.
README.mdExcerpt from the Acme Corp brain (fictional) ## Routines - Every day: drop into inbox/, type /inbox, approve. - Every week: /review-board, then the consistency-check agent. - Before a 1:1: /prep-1to1 Dana (or Riley, Morgan). Totals are not written here: scripts/build_views.py computes them.Step 7 / 7
Making it evolve
A new topic is created with a sheet in 05_scope/sheets/. The build_views.py script reads it and regenerates the tables: the sheets are the source, the views are derived. Before adding anything (a sheet, an agent, a view), ask yourself four questions: does it keep me from losing a decision and its reason? does it tell me the next action and its owner? does it reduce the effort of switching topics? does it leave a useful trace for my team? If the answer is no everywhere, do not add it.
What you tell Claude
Add a topic "Saved filters": create its sheet in 05_scope/sheets/ from the template, then rerun the views script.
What you get
- A sheet with its header (id, status, owner, next action, horizon, source).
- The views by status and by owner regenerated. You never edit them by hand.
05_scope/sheets/insights-filters.mdHeader of a sheet (fictional) --- id: INS-FLT title: Saved filters in Acme Insights status: waiting owner: Riley next_action: Confirm the API date in writing horizon: This week source: archive/2026-03-12_sync-portal.txt ---05_scope/views/by-status.mdView generated by the script ## waiting (1) | ID | Topic | Owner | Next action | Horizon | |---|---|---|---|---| | INS-FLT | Saved filters in Acme Insights | Riley | Confirm the API date in writing | This week |
Using it day to day
Four routines cover the essentials. None takes more than a few minutes: your effort is dropping the material, the rest is Claude’s proposal and your approval.
Every day
5 minutesDrop what arrived into inbox/, type /inbox and approve. At the end of the day, /journal for a free note.
/inbox/journalAfter a meeting
Right awayDrop the transcript or your notes, type /inbox. Check the decisions and their reason first, then the actions and their owner.
/inboxEvery week
15 minutesType /review-board, then ask the consistency-check agent to check dates, statuses and names. Rerun the views script.
/review-boardconsistency-checkBefore a 1:1
5 minutesThe meeting-prep agent gathers what was said, what is pending and the open questions, with the source of each line.
/prep-1to1 Dana
Use cases
Seven situations, with the people and products of Acme Corp (fictional). For each: the situation, what you ask, what Claude does.
01
Everyday product design
- The situation
- Morgan, a product designer, goes through three meetings in a day. By evening her notes are scattered and she no longer knows which decision was made on which screen.
- What you ask
- She drops her three note files into inbox/ and types /inbox.
- What Claude does
- Claude processes the files one by one, separates decisions, actions, facts and open questions, flags a doubtful name, then writes and archives after approval. The next day, /review-board gives her five actions for the week with their sources.
02
The head of design who sets strategy and steers the activity
- The situation
- Sam has to present to Dana how the team is split across three topics, and find out where the activity is blocked.
- What you ask
- "Run the views script, then give me the waiting topics and what blocks them, by owner. Then ask the decision-advisor agent to stress-test the idea of adding one more person on the Insights filters."
- What Claude does
- Claude reads the views by status and by owner, then lists the waiting topics with their next action. The agent rereads the register and returns its unverified assumptions, two alternatives and three questions to ask Dana.
03
Designing a user journey
- The situation
- Morgan has to design the arrival journey in Acme Portal for new accounts.
- What you ask
- "Gather everything the brain says about onboarding new accounts: decisions, technical constraints, open questions. Then propose a step-by-step description of the journey, with states and edge cases."
- What Claude does
- Claude reads the topic sheet, the register (D-003 limits the checklist to new accounts) and the archived minutes. It returns a draft with the steps, the business rules, the edge cases and a "To confirm" section for everything undocumented.
04
Designing with an MCP (Figma) backed by the brain
- The situation
- An MCP is a connector that gives Claude Code access to an external tool, here a mockup tool. Morgan plugged it in so Claude can read and create screens.
- What you ask
- "Create the onboarding checklist screens in the mockup file, from the topic sheet and the approved journey. Only do what the sheet justifies."
- What Claude does
- Claude rereads the sheet and the journey, lists the screens to produce and asks for your approval before touching the file. It flags what goes beyond the sheet, deletes nothing without confirmation, and adds a line to CHANGELOG.md. The mockups follow the text, not the other way round.
05
Shipping prototypes
- The situation
- Riley, the CTO, wants to test the checklist with five customers before summer. Morgan has to provide a clickable prototype.
- What you ask
- "From the approved onboarding journey, build a clickable prototype in the ~/prototypes/portal-onboarding folder. Write nothing in the brain."
- What Claude does
- Claude announces what it will produce (screens, interactions, what is simulated), builds the prototype in the given folder and notes the gaps with the journey. Test feedback then goes through /inbox and becomes sourced facts, decisions and actions.
06
Preparing presentations
- The situation
- Sam presents the state of the design scope to the product committee, in front of people who are not designers.
- What you ask
- "Use the deliverables-writer agent for an eight-slide presentation plan: where we stand, what is decided, what blocks us, what we ask for. Readers: the product committee, no design vocabulary."
- What Claude does
- The agent reads the views, the register and the board, then proposes a plan with one message per slide and the sources in a note. It separates what is decided from what is only considered, and commits Sam to nothing.
07
Updating the memory of every content after a change
- The situation
- Dana announces that the Acme Insights launch moves from September to October. That date appears in the topic sheet, the product file, the board, two external pages and a presentation.
- What you ask
- /propagate Acme Insights launch moved from September to October 2026, announced by Dana on 12 March.
- What Claude does
- Claude searches for the date across the folder, picks one source file where the value is fixed (the old one stays in parentheses), proposes pointing to it in the other files, lists in CHANGELOG.md the external pages to update, then has consistency-check reread the result. One place holds the new date, and nothing is forgotten because the list comes from a search.
A step-by-step example at Acme Corp
Acme Corp is a fictional company, and so are Sam, Dana, Riley and Morgan. Sam, head of design, drops the transcript of a 25-minute meeting into inbox/ and types /inbox. Here are the raw note, what Claude spots before proposing, then what gets written in each file after "approve all".
The raw note
Automatic transcript, weekly Portal and Insights meeting, Thursday 12 March 2026.
Present: Sam, Dana, Riley, Morgan.
[03:30] Riley: On the tech side, the banner list is doable before summer. For existing accounts,
we would have to migrate profile data, and we have no capacity before July.
[05:00] Dana: Then let's go with that: checklist v1 for new accounts only.
Existing accounts will be v2.
[06:00] Morgan: Yes, I'll prepare the three variants for next week.
[09:00] Riley: The saved-filters API will be available in April, not June anymore.
[09:45] Dina: I would need that in writing, with the date, before next Friday, for the committee.
[13:15] Dana: Honestly, we could maybe push the filters to the summer. We'll see.What Claude spots before proposing
- "Dina" speaks at 09:45, but the directory has no Dina and Dana is present. Likely a transcription slip: Claude writes "Dana (to reconfirm)" and creates no person.
- "We could maybe push the filters to the summer" is not a decision: it is an open question.
- "Before next Friday", said on a Thursday, can mean the 13th or the 20th of March. Claude picks the 20th, flags it and says so in the board.
What gets written, before and after
The journal (append only)
A dated entry is added at the end, with the symbols → (action), ? (question) and ! (watch point). Facts are not copied: the entry points to the files where they live.
Before · 00_journal/journal.md ## 2026-02-10, Design review ritual [PIL] Sam sets up a fixed meeting for the design team. Decision: a weekly design review on Tuesday (see D-002, reason not documented).After · 00_journal/journal.md (10 February entry unchanged) ## 2026-03-12, Weekly Portal and Insights meeting [PROD] 25-minute meeting with Dana, Riley and Morgan. Decision: scope of the first version of the onboarding checklist (see D-003). New date for the saved-filters API, see 02_product/products.md. → Morgan: prepare three variants of the checklist → Riley: confirm the API date in writing ? Can the filters be pushed to the summer? Raised by Dana, not settled. ! "Dina" is probably Dana (see 06_resources/glossary.md). ! "Next Friday" can mean 13 or 20 March. Source: archive/2026-03-12_sync-portal.txtThe decision register (append only)
The decision is added with its four fields. The reason matters most: without it, the decision gets rediscussed in three months.
Before · 04_decisions/decision-register.md ## D-001: one mockup file per product ## D-002: weekly design review on TuesdayAfter · 04_decisions/decision-register.md ## D-001: one mockup file per product ## D-002: weekly design review on Tuesday ## D-003: onboarding checklist v1 for new accounts only - Date: 2026-03-12 - Decided by: Dana (VP Product) - Context: support receives many tickets from people lost at their first login to Acme Portal. - Decision: the first version only shows for new accounts. Existing accounts will get the checklist in a version 2. - Reason: migrating profile data for existing accounts needs technical capacity the team does not have before July (said by Riley). - Consequences: the final form is still to settle after Morgan's three variants. - Source: archive/2026-03-12_sync-portal.txt, from 03:30 to 05:00The task board
Every action has an owner and a source. A deadline is set only when someone else gave it, here Dana. What Claude deduces on its own goes into "possible, not retained".
Before · 01_steering/board.md ## This week (none of these tasks)After · 01_steering/board.md ## This week - [?] Confirm the saved-filters API date in writing (owner: Riley; deadline: Friday 20 March, requested by Dana, to reconfirm) ## Next week - [~] Prepare three variants of the onboarding checklist (owner: Morgan) ## Possible, not retained - Measure the activation rate after v1 (deduced by Claude, not said)The topic sheet
The sheet header changes in place (status, owner, next action), and a line is added to the history. The script then regenerates the views.
Before · 05_scope/sheets/portal-onboarding.md status: open owner: Sam next_action: To be defined horizon: LaterAfter · 05_scope/sheets/portal-onboarding.md status: committed owner: Morgan next_action: Prepare three variants of the checklist (banner, guided window, dedicated page) horizon: Next week ## Update history - 2026-03-12: v1 scope decided, owner Morgan (source: archive/2026-03-12_sync-portal.txt)A lasting fact, fixed in place
Riley announces a new date. The freshness rule applies: the most recent and most official value replaces the old one, which stays in parentheses with its date.
Before · 02_product/products.md - Saved-filters API: availability planned for June 2026.After · 02_product/products.md - Saved-filters API: availability planned for April 2026 (previous value: June 2026, before 12 March 2026). Source: archive/2026-03-12_sync-portal.txt, 09:00, announced by Riley.The changelog
It says, page by page, what to carry over to external tools: "add" means paste at the end, "replace" means replace an identified paragraph. External tools are views of the brain, the source stays in the folder.
Before · CHANGELOG.md ## 2026-02-10, design review ritual - Wiki "Design team rituals" add · end of page "Design review every Tuesday, 45 minutes." [x]After · CHANGELOG.md ## 2026-03-12, weekly Portal and Insights meeting - Wiki "Acme Portal, onboarding checklist" replace · paragraph "v1 scope" "The first version only shows for new accounts." [ ] - Wiki "Acme Insights, roadmap" replace · line "Saved-filters API" "Planned availability: April 2026 (awaiting written confirmation)." [ ] - Wiki "Design team decisions" add · end of page "12 March 2026, D-003: checklist v1 for new accounts only." [ ] ## 2026-02-10, design review ritual (unchanged)
To finish, Claude moves the original to archive/, reruns python3 scripts/build_views.py and lists what was done. Claude leaves Sam three points to settle: confirm that "Dina" is Dana, confirm the 20 March deadline, take or drop the "possible, not retained" lines.
The safety rules
These rules are copied into CLAUDE.md and apply to every agent.
01
Claude proposes, you approve, then it writes
Claude first presents what it intends to change. It writes only after your explicit approval ("approve all" or a list of numbers).
02
Claude never invents a decision
A decision, an action or a deadline that is not in the text is not created. If the reason is missing, it writes "reason not documented".
03
Claude flags doubts
An ambiguous passage, a date without a year or a name that looks like a transcription slip leads to a question, never to a silent choice.
04
Nothing is deleted without approval
No file is deleted or moved outside the planned flow (inbox to archive) unless you asked.
05
A fact, an idea and a commitment stay distinct
What is done, what you promised someone and what you are considering are three statuses. A suggestion from Claude is never presented as a commitment.
06
Every line keeps its source
Every important fact points to its original file and date, never to a summary produced from the brain.
Frequently asked questions
- Do my notes stay private?
- The files stay on your machine. However, Claude Code reads their content to answer, so what it reads is sent to the model during the session. Avoid putting passwords or needless personal data in it.
- Do I need to know how to code?
- No. Everything is plain text files that Claude writes for you. Only the views script needs Python 3, and it is optional.
- What if Claude gets it wrong?
- Nothing is written without your approval, every line has its source and the original is archived untouched. With Git you can also go back to the folder’s previous state.
- Does it work with Codex or Claude.ai?
- The skill also installs in Codex and in Claude.ai, and it guides you through the structure and the rules. Agents and commands such as /inbox are files in the .claude/ folder, read by Claude Code.
