| name | os-guide |
| description | OS reference manual — for fork users in their first 30 days AND for Claude Code self-correcting mid-session on an OS-shaped mistake. Routes the question to its canonical source file, reads at runtime, answers with file:line citations. Topics — PARA, Configuration tokens, memory model, contacts schema, tools, lifecycle, design system, locked decisions, capability index, trigger-phrase map, Operating Principles. **Claude SHOULD consult this skill** before answering questions involving OS configuration values, workspace paths, or canonical skill behavior — especially before writing file paths into responses or scaffolding new files. Read-only by default; `/os-guide --sync` is the sole mutation mode and is gated behind explicit user approval. PRECEDENCE — `/bootstrap` for first-run setup; `/find` for topic search across user content; `/contact` for people; `/os-guide` for the OS itself. |
| allowed-tools | Read Bash Glob Grep AskUserQuestion Edit |
os-guide
Runtime-read librarian over the second-brain OS's canonical source files. Answers "how does X work in this OS?" without ever embedding facts that could drift. Every response carries file:line citations.
Before you begin: read the Configuration section in root CLAUDE.md (starts ~line 50; locate via grep -n "^## Configuration" — it moves as sections are added). Path tokens like <workspace.root>, <workspace.projects>, <assistant.name> resolve from there — don't hardcode them in answers.
⚠️ Meta-instruction (for Claude reading this skill)
If you are about to give an OS-shaped answer from memory rather than reading the canonical source — STOP and invoke this skill instead. That includes any answer that contains:
- A workspace path (e.g.,
<workspace.root>/...)
- A Configuration token value (
workspace.projects, user.email, assistant.name, etc.)
- A claim about a skill's behavior or scope
- A claim that a tool is or isn't installed
- A schema field (contacts, design systems, project frontmatter)
- A locked design decision (if your fork maintains a design-log file)
Memory drifts. Canonical files don't. This skill exists to make the latter cheap to consult.
This rule mirrors the contact-no-fabrication discipline in the user's auto-memory (feedback_contact_scaffolding.md).
Why this exists
The OS has seven+ canonical sources (CLAUDE.md, README.md, SOUL.md, USER.md, IDENTITY.md, TOOLS.md, contacts/README.md, plus individual SKILL.md files — and your own design log if you keep one). Without /os-guide, answering "where does X live?" or "what's the rule about Y?" is a manual ritual of grep + cat + remembering which file owns which topic.
The naive alternative — encoding the answers in a tutorial-style skill body — fails the moment any canonical source drifts. The core principle this skill enforces: explainer skills MUST be runtime-read librarians, not textbooks. Reference, don't reproduce (per SOUL.md Operating Principles).
Two audiences:
- Claude Code, self-correcting mid-session (primary) — about to write a path, a config value, or a skill claim; pauses to verify.
- Fork users in their first 30 days (secondary) — figuring out PARA, the Configuration pattern, how to connect a tool, what skills exist.
Designed for the harder Claude-shaped constraint ("cannot hallucinate"); fork users get served as a free side-effect.
When to use
Trigger phrases (broad — the pattern is "OS-shaped explanatory question", not a literal command):
- "what is PARA in this OS?" / "how is PARA set up here?"
- "how do I connect a new tool?" / "how do I add an MCP?" / "how do I connect Slack?"
- "where do briefings go?" / "where does X live?" / "what's the path for Y?"
- "what is
workspace.projects?" / "what are the Configuration tokens?" / "what does <workspace.resources> resolve to?"
- "what skills do I have?" / "what does this OS do?" / "what's the capability index?"
- "which skill creates a project?" / "how do I ask for X?" / "what's the trigger phrase for Y?"
- "how does memory work here?" / "Folder A vs Folder B?"
- "what does the contacts schema look like?" / "what fields does a contact need?"
- "what's the locked decision on X?" / "what did this OS decide about Y?"
- "what are the Operating Principles?" / "what's the rule about duplicate projects?"
- "/os-guide " / "/os-guide" (interactive prompt for topic)
- "explain the OS" / "remind me how X works here"
Trigger Claude-self-consult specifically when the response Claude is about to give includes:
- a path (workspace/project/skill/canonical-source path),
- a Configuration value,
- a claim about a skill,
- a claim about a tool's connection state,
- a schema field.
Do NOT trigger for
- Topic-keyed recall over user content ("do I have anything on Anthropic?", "what did I save about Q1 planning?") — that's
/find. /find searches Resources/Projects/Archive/memory for content the user authored. /os-guide does NOT.
- Entity-keyed recall about a person ("who is Alex?", "context on Michele") — that's
/contact.
- First-run interactive setup on a fresh fork ("I just cloned this, set me up") — that's
/bootstrap. /os-guide is the post-bootstrap steady-state reference.
- Action requests ("create a project", "archive this", "log my interaction with X") — those are the mutation skills (
/new-project, /archive-project, /contact-log).
- Generic theory (Tiago Forte's PARA framework as a concept, Claude Code as a product, generic productivity systems) — out of scope; refer to external sources.
/os-guide only answers the in-this-OS-specifically version.
- Live workspace state ("what projects are active right now?") — that's
project-query.sh. The skill can point at it but doesn't run it.
- CLI install instructions (
brew install <tool>, org-internal installer flows) — out of scope; point at the appropriate installer.
Precedence vs neighbor skills
When multiple skills could match the user's phrasing, the priority is:
| Skill | Owns | When this skill wins | When it defers |
|---|
/bootstrap | First-run interactive setup, persona regeneration, Configuration writes | Fresh fork before setup_completed: is filled in | After fork is configured |
/find | Topic-keyed recall over user content (Resources, Projects, Archive, memory) | "do I have anything on X" / "find my notes on Y" | OS structural questions ("how does X work in this OS") |
/contact | Per-person entity recall | "who is X" / "context on Y" where X/Y is a name | Anything not-a-person |
/os-guide | OS-meta — config, paths, schema, capability index, locked decisions, trigger-phrase map | "how does X work here" / "what is X in this OS" / "where does X live (structurally)" | User content (defer to /find); people (defer to /contact); first-run (defer to /bootstrap) |
Composition rule: /os-guide MUST NOT call /find recursively for OS-knowledge questions (its canonical source list is hardcoded — see Routing Table below). /bootstrap SHOULD reference /os-guide in its closing for ongoing-manual discovery. /find MAY route OS-shaped queries here (one-way; the reverse would loop).
Routing Table — topic → canonical source
This is the librarian's shelves. Every answer this skill gives MUST cite a row from this table. If a question doesn't map to any row, the skill responds with the no-canonical-source fallback (see Read Protocol Step 7), never improvises.
Workspace layout & PARA
| Topic | Canonical source(s) | Notes |
|---|
| PARA layout (6-folder workspace) | README.md §"Project Map" + §"What is PARA in this OS" | The 6-folder this-OS implementation (2-Areas re-added 2026-06-18) |
| Mac Desktop PARA (6-folder, distinct) | USER.md §"Mac Desktop Layout (PARA)" | Separate system — disambiguate from workspace PARA |
| What does NOT belong at root | README.md §"What does NOT belong at root" | Explicit anti-pattern list |
| Outputs location (briefings/meeting-prep/etc.) | README.md §"Outputs" + CLAUDE.md §"Briefing & report outputs" | CLAUDE.md adds <assistant.name>-specific deltas |
Configuration tokens
| Topic | Canonical source(s) | Notes |
|---|
All Configuration tokens (workspace.*, user.*, assistant.*, etc.) | CLAUDE.md §"Configuration — source of truth for skills" | Auto-loaded every session. Re-read at every invocation; never cache. |
| Forking the workspace | CLAUDE.md §"Forking note" + README.md §"Forking this repo" + EXAMPLE-CONFIG.md | Three sources, intentional redundancy |
setup_completed lifecycle marker | CLAUDE.md §"lifecycle" subsection of Configuration | Used by /bootstrap as re-run gate |
Identity & voice
| Topic | Canonical source(s) | Notes |
|---|
| Assistant persona / voice / boundaries | SOUL.md (whole file) | Includes the Operating Principles |
| Operating Principles | SOUL.md §"Operating Principles" | 7 principles: Connect-before-create, Revive-before-scaffold, Eliminate-before-automate, Consolidate-before-duplicate, Reference-don't-reproduce, Capture-before-commit, File-before-finish — plus the Boring-is-beautiful default |
| User profile | USER.md (whole file) | Fork users edit per their own role/team |
| Assistant identity | IDENTITY.md | Name, version, origin |
Memory
| Topic | Canonical source(s) | Notes |
|---|
| Memory model (Folder A vs Folder B) | README.md §"Memory — dual-folder model" | Two memory folders, distinct roles |
| Daily journal location | memory/YYYY-MM-DD.md (append-only) | Cited from README.md |
| Writing-style profile | memory/writing-style.md | Optional — present if the user has authored one |
| Learned preferences | memory/learned-preferences.md | Optional — durable cross-session preferences |
Tools & MCPs
| Topic | Canonical source(s) | Notes |
|---|
| Tool inventory (live state) | TOOLS.md (root, auto-loaded) | The ONLY canonical tool source — regenerated by /bootstrap from live probes. |
| How to add a new tool (MCP or CLI) | TOOLS.md §"How to add a tool" | Step-by-step procedure for both paths |
| Declared MCPs | .mcp.json at repo root | mcpServers block |
| Social media publishing (posting to X / LinkedIn / Slack, publish queue, scheduling) | TOOLS.md §"Social media publishing" | x-cli patched fork, li-post.py, Slack native scheduling, course-social-publisher runner. Hard boundary: never post without explicit "send it". |
Contacts & relationships
| Topic | Canonical source(s) | Notes |
|---|
| Contacts schema (frontmatter + body sections) | <workspace.root>/<workspace.resources>/contacts/README.md | Reference, don't reproduce — read live, don't restate. |
| Contact location | <workspace.root>/<workspace.resources>/contacts/<slug>.md | Per-file flat layout |
WikiLinks [[topic]] convention | CLAUDE.md §"Cross-references — WikiLinks convention" | Manual convention; /find follows [[X]] links |
Recall arms & ported rules (2026-06-12)
| Topic | Canonical source(s) | Notes |
|---|
| Friction protocol (logging tooling friction) | CLAUDE.md §"Friction log + cost-consent" | One-line entries in daily memory note; no infra |
| Cost-consent rule (before enabling paid things) | CLAUDE.md §"Friction log + cost-consent" | Per-decision consent; precedents #23 |
Lifecycle skills
| Topic | Canonical source(s) | Notes |
|---|
| How to create a new project | .claude/skills/new-project/SKILL.md + README.md Quick Reference | The skill body is the authoritative procedure |
| How to archive a project | .claude/skills/archive-project/SKILL.md | |
| How to import / migrate existing work into the workspace | .claude/skills/migrate-work/SKILL.md | Reads past Cowork sessions; copy-never-move; offered at the /bootstrap close, re-invokable anytime |
| How to prune stale projects | .claude/skills/prune-projects/SKILL.md | Friday-batch staleness review |
| How to triage Inbox | .claude/skills/inbox-process/SKILL.md + Operating Principle "Capture before commit" | Drives the Inbox-to-home pipeline |
| How to save a resource | .claude/skills/save-resource/SKILL.md | |
| How to find existing knowledge | .claude/skills/find/SKILL.md | The unified recall surface |
Capability index (dynamic — globbed at invocation)
| Topic | Discovery method | Notes |
|---|
| All available skills | find .claude/skills -maxdepth 2 -name SKILL.md then read each frontmatter description: line | DO NOT hardcode the list — glob at invocation time |
| All design-system brands | find <workspace.resources>/design-systems -name DESIGN.md | Plus the README.md in that directory |
| All contacts (count, not enumeration) | ls <workspace.resources>/contacts/*.md | grep -v README | wc -l | Enumeration deferred to /contact |
| All reference micro-docs | ls <workspace.resources>/reference/*.md | Top-level only; subdirs are domain-specific |
| Active projects (live status) | run <scripts.project_query> | Defer to the script; don't enumerate inline |
Design system
| Topic | Canonical source(s) | Notes |
|---|
| Active design brand | Root DESIGN.md | Read by all design-* skills |
| Design brand library | <workspace.root>/<workspace.resources>/design-systems/<brand>/DESIGN.md | Plus the README catalog in that dir |
| How to swap brand | /use-design (plugin-scope skill — not under project .claude/skills/) | /use-design <brand> |
Hooks & harness
| Topic | Canonical source(s) | Notes |
|---|
| Hook wiring | .claude/settings.json (the wiring) + .claude/hooks/ (the source) + CLAUDE.md §"Bundled harness layout" | No single explainer doc — surface as a gap if asked |
| Recurring work primitives | README.md §"Recurring Work" | CronCreate, /schedule, /loop, hooks |
| CCv4 bundle map | CLAUDE.md §"Bundled harness layout" + TOOLS.md §"Native skill bundles" | 9 CCv4 skills bundled in-repo since 2026-05-11 |
First-run setup
| Topic | Canonical source(s) | Notes |
|---|
/bootstrap procedure | .claude/skills/bootstrap/SKILL.md | The skill IS the source of truth on its own procedure |
Re-running /bootstrap | bootstrap/SKILL.md Tiger invariants (T1-T4) | T2 refuses re-run on configured fork |
Gaps (no canonical source — surface honestly)
The following are commonly asked but have no canonical source today. The skill MUST surface this honestly rather than improvise:
| Topic | Status | Workaround |
|---|
| Why these 5 MCPs (gemini-vision/exa/slack/atlassian/figma) and not others | MISSING | Point at TOOLS.md + .mcp.json _notes block for partial rationale; full rationale lives in your fork's design log if you keep one |
| How hooks work end-to-end | MISSING | Point at .claude/hooks/ source files + CLAUDE.md §"Bundled harness layout" |
| How to author a new skill (procedural) | PARTIAL | Point at /skill-creator SKILL.md — it teaches conversationally |
| Configuration-token resolution under the hood | MISSING | Point at CLAUDE.md §"Configuration" for the what; explain that skills substitute tokens at read-time |
When asked about a gap topic, respond per Read Protocol Step 7. Do NOT fill the gap with inline content.
Read Protocol
When invoked with a question (or auto-routing match), execute these steps in order:
Step 1 — Classify the query
Map the user's question to a row in the Routing Table. Multi-topic queries fan out to multiple rows. If no row matches, jump to Step 7.
Also detect the invocation mode:
- Narrative mode (default) — if the query is natural language from a user-facing prompt
- Structured mode — if the invocation includes a structured args payload (e.g.,
args="token:workspace.projects" or args="topic:contacts-schema") typical of Claude self-consult
Step 2 — Resolve Configuration tokens
Read CLAUDE.md lines containing the ## Configuration section. Extract every <token> value referenced in the routing-table entries you matched. This step is MANDATORY and runs every invocation — never cache token values between calls.
If Configuration is empty or contains placeholder values (e.g., setup_completed: is missing or unfilled), short-circuit immediately with:
"Cannot answer — Configuration section in root CLAUDE.md is unfilled or placeholder. This usually means /bootstrap hasn't run yet, or the fork was set up manually and Configuration was skipped. Run /bootstrap first, then re-ask."
Never improvise an answer in this state.
Step 3 — Read the canonical source(s)
Use the Read tool. For section-specific lookups, use offset/limit to fetch only the relevant lines. If section anchors don't match (e.g., the heading moved), fall back to reading the whole file.
For dynamic-glob entries (capability index, brands, contacts count, reference docs):
- Use
Glob or Bash (find/ls) at invocation time
- Read SKILL.md frontmatter description lines via
Grep + Read
- NEVER hardcode the list in the skill body
Step 4 — Compose the answer
For narrative mode:
- Lead with the answer (no "Great question!" — see voice rules)
- Quote canonical content verbatim where useful; paraphrase only when length demands
- Every factual claim ends with
*(source: <relative-path>:<line-range>)*
- Resolve all
<workspace.*> and <user.*> tokens to actual values before quoting paths
- Optional one-line "next step" or "want me to…?" closer when appropriate
For structured mode:
- Zero prose padding
- Output key:value:source triples in YAML-ish format:
key: <token or topic name>
value: <literal value or canonical answer>
source: <relative-path>:<line-range>
resolved_path: <if applicable, fully-resolved path with Configuration substitutions>
related_tokens:
- <if relevant>
canonical_files:
- <list of source files consulted>
last_verified: <date if available, e.g. from setup_completed>
Step 5 — Surface disagreements explicitly
If two canonical sources contradict each other (e.g., README.md says X about a topic but a SKILL.md or design log says Y), never silently pick one. Surface both with citations and explain the hierarchy:
"Sources disagree on this:
- README.md (line N) says X
- <other-file> (line P) says Y
When conflicts arise, locked design decisions win over README. Recommend updating README to match. The current locked answer is Y."
This discipline mirrors /find's contradiction-surfacing rule at find/SKILL.md:155.
Step 6 — Distinguish similar-shaped topics
Some queries are ambiguous between this-OS-specific and generic. Default to the this-OS-specific answer; explicitly reject the generic version.
Example — "what is PARA?":
- Generic answer: Tiago Forte's framework → REJECT with one-line redirect to Wikipedia/Forte
- This-OS answer: the 6-folder workspace layout → THIS is what the skill answers
Some queries are ambiguous between disjoint scopes (e.g., "what is PARA?" could mean workspace PARA or Mac Desktop PARA, which are distinct). Ask one disambiguating question via AskUserQuestion if the answer differs:
"Which PARA — the <workspace.root>/ workspace or your Mac Desktop ~/Desktop/ layout (documented in USER.md)?" (Both are 6-folder now, so disambiguate by scope/root, not folder count.)
Step 7 — No-canonical-source fallback
If the query maps to a "Gaps" row OR no Routing Table row matches at all, respond:
"That topic exists in this OS conceptually, but there's no canonical source documenting it yet. Closest related:
- <file-path> covers
- <file-path> covers
If you decide what the canonical answer is, write it down at <workspace.root>/<workspace.resources>/reference/<topic>.md and re-ask — I'll pick it up next sync."
Never improvise. Never fill the gap with inline generated content. The gap surface IS the correct behavior.
Step 8 — Out-of-scope refusal
If the query is genuinely outside the skill's scope (asking about generic productivity theory, asking about Claude Code itself, asking for an action that's a mutation skill's job):
"Out of scope for /os-guide — that's not OS-shaped. Try:
- <other-skill> if you meant
- <external-resource> if you meant
If you meant something OS-specific and the phrasing came out generic, try rewording — like 'what is <workspace.projects> in this OS' instead of 'what is PARA in general'."
Citation format
Mandatory on every factual claim in narrative mode. Format: *(source: <relative-path>:<line-range>)*
Examples:
*(source: CLAUDE.md:24)**(source: README.md:32-39)**(source: <workspace.root>/<workspace.resources>/contacts/README.md)* (whole-file citation when section-specific isn't appropriate)
Relative path is from repo root. If a token-substituted path is more readable, use both:
*(source: <workspace.resources>/contacts/README.md — resolves to your configured workspace.root)*
In structured mode, citations live in the source: key, not as inline text.
Voice & answer-shaping
Voice per SOUL.md Operating Principles. Lead with the answer. No filler.
Phrases to use (from SOUL.md):
- "Here's what matters..."
- "Worth noting..."
- "From what I'm seeing..."
- "My take on this..."
- "Want me to...?"
Phrases to never produce:
- "Great question!" / "I'd be happy to help!" / "Sure!" — performatively helpful
- "Per your request..." / "Please be advised..." / "FYI..." — corporate fluff
- "Actionable items include..." — corporate-action phrasing
- "As an AI..." or any self-referential meta-narration
Length discipline:
- Definitional questions: 2-5 sentences plus citation
- Procedural questions: numbered steps, prereqs surfaced upfront
- "Where is X" lookups: one sentence, the path + citation
- Capability-index questions: structured list, grouped by category, with one-line descriptions from each skill's frontmatter
No emojis unless the user explicitly invites them — per USER.md formatting preferences.
Failure modes
| # | Failure | Mitigation |
|---|
| 1 | Stale embedded fact in skill body | This skill body MUST NOT embed facts — Routing Table only. Enforce at edit time. |
| 2 | Renamed canonical file | Step 3 Read fails cleanly; skill surfaces "Routing table points at <path> but file is missing — has it been renamed? Run /os-guide --sync to refresh." Never improvises. |
| 3 | Topic has no canonical source | Step 7 — surface the gap honestly with closest-related pointers; suggest writing it down. Never improvises. |
| 4 | Configuration drift (fork renamed workspace.root) | Step 2 re-reads Configuration every invocation; substitutes tokens dynamically. Path-shape answers are always correct for the fork's actual layout. |
| 5 | Canonical source itself is wrong | Skill is a faithful repeater. File:line citation lets user/Claude verify and notice. Correctness is pushed to canonical-source maintenance (where the project invests effort). |
| 6 | Recursive self-call / loop | Skill MUST NOT call itself; MUST NOT call /find recursively for OS-knowledge. Canonical source list is hardcoded in Routing Table. |
| 7 | Out-of-scope question | Step 8 — graceful refusal with redirects. |
| 8 | Description over-triggers (steals routing from /find//bootstrap) | Description claims explicit scope + names neighbors. Eval cases include explicit deferral tests. |
| 9 | Skill body drifts (someone adds prose answers) | The core rule: routing entries only, never content. Pre-commit grep MAY enforce in future. |
| 10 | Two canonical sources disagree | Step 5 — surface both with citations, explain hierarchy. Never silently pick. |
| 11 | User asks for live workspace state (e.g., "what projects are active?") | Point at <scripts.project_query> (project-query.sh); don't run it inline. This skill is structural, not state-querying. |
| 12 | Claude self-consults but the user's question wasn't OS-shaped | Skill should still produce a useful answer if possible, but if the question maps to no row, fall to Step 7 (no-canonical-source) gracefully. |
Boundaries
This skill is read-only by default. The single exception is --sync mode (see --sync section below), which edits the Routing Table only, gated by explicit user approval.
The skill MUST NOT:
- Modify any canonical source file (CLAUDE.md, README.md, SOUL.md, TOOLS.md, contacts/README.md, etc.) — those are owned by their respective edit paths (the user,
/bootstrap, lifecycle skills)
- Auto-install tools, run
/mcp, modify .mcp.json
- Run
git add or git commit — surface commands as text only
- Modify any user content (Resources, Projects, Archive, memory)
- Call itself recursively
- Call
/find recursively for OS-knowledge questions (canonical source list is hardcoded)
- Fabricate content for gap topics
- Embed facts in its own body — only routing entries, protocol, voice, boundaries
If asked to do any of the above, defer to the appropriate skill (/bootstrap for setup, /new-project for scaffolding, etc.) — do not silently invoke them.
--sync mode (self-update)
/os-guide --sync is the sole mutation mode — it detects what changed in the OS (new skills, MCPs, design brands, locked decisions) and proposes Routing-Table updates without ever auto-applying them. Gated by explicit user approval; never auto-runs.
Full --sync spec — trigger surfaces, five-phase behavior, report templates, state-file schema, tiger invariants, scope limits, and when-to-run guidance — lives in references/sync-spec.md. Load it on demand only when actually running --sync; normal read-only lookups never need it.
Output formats
Narrative mode — markdown response with citations on every factual claim. Optional closing question or next-step pointer.
Structured mode — YAML-ish key:value:source block. Zero prose. Designed for Claude self-consult parsing.
No-canonical-source mode — gap-surfacing response per Step 7 with closest-related pointers.
Out-of-scope mode — refusal + redirects per Step 8.
Disagreement mode — explicit "Sources disagree" block per Step 5, citing both, explaining hierarchy.
These five formats are stable. Downstream skills (Layer 3 chief-of-staff) MAY compose /os-guide for path/config lookups and parse the structured-mode output specifically.
