⚙️ Step by step with /os-coach

Installing means copying the folder os-coach for ~/.claude/skills/. One command, no build, no dependencies.

It’s the only prerequisite. Without it, the /os-coach doesn’t exist on your machine.

cp -r · skills folder · zero dependencies.

A copilot that does the technical work for you. It asks, you decide; it creates the files.

You don’t need to know how to code — assume you’ve never opened a terminal.

Does it for you · one layer at a time · you decide.

Six verbs: start (begins), next (next layer), layer (skip to one), status (map), audit (scores), help (explains).

It’s the entire keyboard you’ll use on this learning path. Memorizing these six is enough.

start · next · layer · status · audit · help.

A file that stores the goal, current layer, and decisions. Read first and updated last on every turn.

It’s what lets you stop halfway and come back days later without losing your place.

Persistent state · resume later · always up to date.

Talk like a human, one step at a time, the skill does the building, never generic, always persistent, end the turn the same way, no em dashes, protect sensitive information.

Knowing the rules tells you what to expect—and when the coach is going off script.

8 rules · grounded in reality · protect data.

Checks that prevent errors: run next without having start, overwrite an OS, invent a 7th layer.

Understanding the guards explains why the coach sometimes stops and asks instead of acting.

No memory → ask to start · don't overwrite · don't make things up.

The engine: ask, build, persist, advance, audit. All reading and writing to the same memory.md.

It’s the rhythm of the entire learning path. Your first hands-on action: run /os-coach help.

Ask · Build · Persist · Next · Audit.

The command that creates a new OS in the current folder and captures your goal in your own words.

Everything afterward is anchored to that goal—starting well prevents a generic OS.

start · goal in your own words · folder = OS.

Who is the OS for, what would you like to simply ask it to do, and one thing it should always do and one it should never do.

Three short answers already give you almost all of the Identity. It's fast by design.

Who it’s for · what to ask · always / never.

The coach checks what you’ve already said and reuses it. It never asks “who’s this for?” twice.

Shows that the goal + the start answers already cover almost all of Identity.

Reuse · no repetition · only the question that’s missing.

A short file: who the OS is, whom it serves, the goal, 2-3 defaults, and 2-3 hard refusals.

It’s the first file the OS reads. Lean is better — cut until it hurts.

< 30 lines · defaults · hard refusals.

If you mark a field as private, the coach records an identifier (“Client A”), never the real value.

Protects names, emails, and values from the first layer, without you having to police them.

Handle · real value outside · no leaks.

A stranger reads the CLAUDE.md and correctly describes what the OS is for and one thing it refuses.

It’s the green light for Identity. Pass the test, and the layer is solid.

Stranger test · solid · one clear refusal.

Your first real build: run the start with your goal, inside a new folder.

Move from concept to creating the first files: memory.md + CLAUDE.md.

Hands-on · concrete goal · verify the files.

O next read the memory.md and opens the next unfinished layer. After Identity, you move to Substrate.

It’s the command you repeat most. It follows the right order for you.

next · build order · one layer at a time.

sources.md list where the material comes from; compendium.md is the distilled reference the OS actually reads.

These are the two canonical files. The audit looks for them by these names.

sources · compendium · distilled > raw pile.

When distilling, names and values marked as sensitive become handles. Never create a file that says “I excluded X” and lists X.

The substrate is where accidental leaks are most likely—it’s where real data enters.

Stable handle · no contradictions · ask first.

If you already have the material, the coach offers to gather and distill it on the spot; otherwise, it notes what’s missing in the memory.md.

You make progress even without everything in hand — the gap is recorded, not forgotten.

Gather · distill · record what’s missing.

If the tough question has two parts (“what’s winning AND what’s already overdue”) and a piece of data is missing, the layer is in progress, not solid.

The coach is honest about what it still can’t answer—and tells you what data would resolve it.

Multi-part · honesty · which input is missing.

Throw everything in raw into compendium.md. A small, clean compendium beats a giant, messy one.

Dirty substrate clogs context. Distilling is the real work of this layer.

Distill > dump · small and clean.

Run /os-coach next in the same folder for the coach to open and build the Substrate.

Create the folder substrate/ with the canonical files, anchored to your goal.

next · substrate/ · check the compendium.

The folder rules/ with always.md (what to always follow) and never.md (hard stops).

Written rules become reliable behavior — they don’t depend on you remembering.

always · never · rules/.

"What’s the worst mistake this OS could make?" The answer becomes a clear never-rule.

Turns your biggest fear into a black-and-white fence.

Worst mistake · concrete never-rule · black-and-white.

A hook is a locked door: a reminder, check, or backup that happens every time without anyone having to remember.

A rule is a “no entry” sign; a hook is stronger because it can’t be ignored.

Hook > rule · automatic · locked door.

If there’s private data in the folder, add a never rule: “never upload or share this folder publicly.”

A leak can't be undone. This rule is usually the audit's #1 action.

Public never · irreversible · high priority.

"Be careful" isn’t a rule. "Never mix numbers from two clients" is — you can test it.

A vague rule protects nothing. Concrete and testable is the default.

Concrete · testable · no vagueness.

The layer is ready when the worst mistake has become a clear never-rule and at least one automatic reflex has been identified.

Sets an objective target for “Rules ready” instead of an endless list.

Never written · 1 reflex · clear target.

Run /os-coach next again so the coach can open the Rules and write always.md + never.md.

Reinforces that next is the same command for every layer—the order is automatic.

next · rules/ · same verb.

A folder skills/ with ONE SKILL.md: when to use it, the steps, and how to tell whether it worked well.

Start with the task you repeat most often. One good skill beats ten half-finished ones.

One skill · the most repeated · SKILL.md.

You cook by feel a few times, then write down the recipe. A skill is a verb you earn.

Writing a skill for something you've never done by hand produces the wrong recipe.

Manual first · capture later · earned verb.

One tools.md that lists every connection, what it's for, and whether it's read-only or write-enabled. Never keep secrets in the folder.

The read-only pattern is the security hack: the OS looks, but doesn't touch.

Read-only · no secrets · only where writing is needed.

One AGENT.md for the first role worth promoting: what it does, which skills it orchestrates, and the review gate before it goes out.

Only promote a routine to an agent if you already do it manually today — and there are skills for it to orchestrate.

AGENT.md · orchestrates skills · review gate.

Skills before Tools before Agents. The coach blocks building an agent without skills for it to orchestrate.

Going to Agents too early is the most common mistake. The order protects you from it.

Order · skills first · agents last.

If a layer doesn’t yet apply to your goal, the coach marks it not started with a one-line reason and moves on.

Honesty is better than inventing work. You're not pushed toward an unnecessary agent.

not started · reason in 1 line · no busywork.

Three next in sequence cover Skills, Tools, and Agents—each when it's ready.

You build the three capability layers of your OS, in the safe order.

next ×3 · skills/ · tools.md · agents/.

Read the memory.md, opens the actual folder and scores each layer against your goal.

It’s the command that honestly tells you where your OS really stands.

audit · against the objective · scans the folder.

A file with the scorecard, the next 3 steps, and what already works—written for you to keep.

Because it can be saved, it must never contain leaked sensitive data.

Scorecard · savable · no leaks.

Missing (doesn't exist), Started (thin), Solid (passes the done check), Compounding (improves on its own over time).

It's the honest yardstick. Most new OSs are Missing or Started — and that's okay.

4 levels · honest · start small.

Instead of a huge list, three actions in order, each tied to the goal and a real file.

Focus. You leave the audit knowing exactly what to do next.

3 moves · by leverage · real file.

Every line in the audit must fail if pasted into a stranger's audit. It cites real goals, gaps, and file names.

A generic audit is a failed audit. This test ensures advice that works for YOU.

Specific · cites files · no boilerplate.

Urgent/irreversible hard rules come first; otherwise, a substrate gap takes priority; skills only with substrate; agents last.

Explains why the audit sometimes ignores the “fun part” and tells you to fix the foundation.

Precedence · foundation before capability · agents last.

The audit rewrites the status block in the memory.md and note the date — then the next next already starts from there.

Close the loop: auditing isn’t a dead report; it’s fuel for the next step.

Feedback · rewrites status · feeds the next.

A real run, condensed: from the start ("never miss a deadline again") to audit, with handles “Couple A/B”.

Ties the whole track to a single case — you watch the OS take shape and get scored.

End-to-end example · handles · real scorecard.