Detailed content
🧩 Three layers, one order
This module covers all three layers of capacity: Skills (layer 4), Tools (layer 5), and Agents (layer 6). The next takes you through them in this sequence, and the sequence is no accident: an agent only makes sense when there are skills for it to orchestrate, and skills only make sense when there’s a substrate for them to read.
🌱 New here?
Skill (in PT: skill) is a repeatable task written as a recipe, so it runs the same way every time. Tool is a wire that connects the OS to a real data source (a database, a calendar, a spreadsheet). Agent is a “worker” with a role who decides which skills to use and in what order — and reviews before anything goes out.
How to read: capability grows from left to right. The agent (amber box) contains the skills it orchestrates and a review gate. That’s why it comes last: without skills inside, it has nothing to coordinate.
Why learn
Because the #1 mistake people make when they’re excited is jumping straight to agents—the “fun” part—and building an agent with no skills to use. Knowing the order saves you from building the roof before the walls. You gain real capability, layer by layer, instead of an empty shell.
Key concepts
🛠️ Skill = Earned Verb (Most Repeated First)
The coach analogy: a skill is a recipe card. The first few times, you cook “by eye”; later, you write down the recipe so anyone can repeat it the same way. That's why you achievement a skill — do the work manually a few times, and only then capture the steps. The coach starts with ONE skill: your most repeated task.
The questions it asks
What task do you repeat?
"...and you’d like it to run the same way every time?" That’s a candidate for your first skill.
How do you do it by hand?
"Show me the step-by-step." That’s where the recipe steps come from.
How do you know it’s good?
Becomes the line “what a good result looks like” — the skill’s quality criterion.
⚠️ The common mistake
Trying to write ten skills at once, or writing a skill for something you never done by hand. Earn it first: do the actual work a few times, then capture it. A skill is a snapshot of a process that already works, not a guess.
Why learn
Because starting with the most repeated task gives you the biggest return with the lowest risk. It’s the task you know by heart, so the recipe comes out precise, and it saves you the most time later. And the coach reminds you: a skill is never “done”—you’ll improve the recipe with every use.
Key concepts
📂 Anatomy of skills/<nome>/SKILL.md
When you answer, the coach creates the folder skills/ and, inside it, a subfolder for each skill with a SKILL.md simple. It captures three things: when to use, the steps e what a good result looks like. No jargon—this is your recipe, written so you can repeat it.
Illustrative recreation — skills/checar-prazos/SKILL.md
# Check deadlines ## When to use Every morning, or when I ask "what's due?". ## Steps 1. Read the tracker in substrate/compendium.md. 2. Calculate the deadlines from each date. 3. List what is due in 10 days and what is already overdue. ## What a good result looks like A short list, with dates and days remaining, with no deadlines forgotten.
🌱 New here?
In Claude Code, a skill usually becomes a slash command — a shortcut you invoke by typing /algo. O SKILL.md is the text file that describes this skill: the harness reads it and learns how to execute that recipe when you invoke it.
Why learn
Because the layer’s done-check is exactly this: a real, recurring task, written as a skill, with clear steps and a "good result" line. Seeing the anatomy helps you recognize when a skill is complete — and when it's still just a loose idea.
Key concepts
🔌 Tools: the read-only wire
Layer 5 connects the OS to real data sources. The coach analogy is powerful: a tool is a window the OS looks through, not a key to the whole house. By default, it’s read-only (read-only): it can read, but it can’t make changes. And no secrets (passwords, keys) go in the folder.
🌱 New here?
Read-only (read-only) means the connection can see the data but can’t change nothing. API is a service’s official "outlet" for programs to communicate with it; CLI is a terminal command you run; MCP is a ready-made connector between the AI and a tool. The coach helps you choose the simplest path for each source.
Illustrative recreation — tools.md
# Tools # Cada fonte: pra quê, e nível de acesso. - Calendário — ler datas de entrega — só-leitura - Planilha — ler bookings — só-leitura - E-mail — rascunhar (não enviar) — só-leitura # Segredos (senhas/chaves) ficam FORA desta pasta.
✓ Safe default
- ✓Read-only by default.
- ✓Secrets outside the folder.
- ✓Writing only where it's truly necessary.
✗ The common mistake
- ✗Give write access to everything "just in case."
- ✗Store the password inside the OS folder.
- ✗Connect sources the goal doesn’t call for.
Why learn
Because writing everywhere is the shortest path to irreversible damage. Read-only is the “looking through the window” version: the OS gives you answers based on real data without risking a mess in the source. The done-check is straightforward—every source the goal needs is listed with its access level, and no secrets are stored in the folder.
Key concepts
🤖 Agent: Role with Judgment + Review Gate
The analogy that ties it all together: skills are the kitchen tools; the agent is the chef that knows which one to pick and tastes the dish before it goes out. An agent is a role with judgment: it decides which skills to use and in what order, and runs a required check before anything goes out. The coach only builds an agent for a routine that you already does by hand today.
How to read: the task comes in, the chef chains skills, but nothing gets out without going through the review gate. That gate is what makes delegation safe—the agent doesn't decide on its own what to publish.
Illustrative recreation — agents/<nome>/AGENT.md
# Gerente de entregas ## Papel Cuidar pra nenhuma entrega de cliente atrasar. ## Skills que orquestra - checar-prazos - rascunhar-aviso ## Portão de revisão (obrigatório) Nada vai a um cliente sem você ler e aprovar primeiro.
✓ An agent
- ✓Has ONE clear role.
- ✓Orchestrates existing skills.
- ✓Has a mandatory review gate.
✗ “Do-it-all” agent
- ✗Wants to handle ten roles at once.
- ✗It's built before a skill exists.
- ✗Let work go out without review.
Why learn
Because the review gate is what separates “automation that helps” from “automation that scares you.” Without it, an agent could send something wrong to a customer. With it, you delegate coordination while keeping the final say. The done-check: a real, orchestrated routine with a clear review gate.
Key concepts
🚦 Don’t Skip Steps (and the Honest “not started”)
Two safeguards guide this module. First: never an agent before the skills it would orchestrate exist — you’re not pushed to build the chef before you have the pans. Second: if a layer doesn’t apply to your goal yet, the coach marks it as not started with a one-line reason, instead of inventing pointless work.
🧭 When to mark “not started”
- Tools — Does your goal still only read local files? With no external source, mark it not started: "no external source needed yet".
- Agents — Do you have only one skill? There’s nothing to orchestrate. Not started: "come back when there are 2–3 skills you can chain together".
- The sign of honesty: one line explaining why > an empty folder pretending to show work.
💡 Practical tip
"An empty layer" isn’t a failure. An honest OS with 3 solid layers and 3 marked not started is worth more than an OS with 6 half-baked layers. The coach prefers the truth — and so does the 4.6 audit.
Why learn
Because the temptation to jump to agents is mistake number one—and an honest “not started” is the antidote to the opposite mistake: filling the OS with fake layers to make it look complete. Together, these two guardrails keep your system real: it contains only what serves the goal, in the order that can support the next step.
Key concepts
✅ Done-checks + copy-run
Each of the three layers has its own done-check. You run /os-coach next once per layer, and the coach builds the artifact and marks the status in memory.md.
The three done checks
- ✓Skills: a real, recurring task became a skill with clear steps and a "good result" line.
- ✓Tools: every source the goal needs is listed with its access level, and there are no secrets in the folder.
- ✓Agents: a real, orchestrated routine with a clear review gate.
Objective: go through the three layers of capability, one at a time, letting the coach build each artifact.
1) Open the Skills layer:
/os-coach next
Answer (replace these with your own):
Tarefa que repito: <ex.: checar quais entregas vencem> À mão eu faço assim: <passo 1; passo 2; passo 3> Fica bom quando: <ex.: nenhuma data passa batida>
2) Run it again for Tools; answer which sources and access:
/os-coach next
Fontes: <ex.: calendário e planilha de bookings> → só-leitura
3) Run it again for Agents (only if you already have chainable skills):
/os-coach next Rotina que encadeio à mão: <ex.: checar prazos e rascunhar o aviso> Revisão antes de sair: <ex.: eu aprovo todo aviso a cliente>
How to verify: make sure they exist skills/<nome>/SKILL.md e tools.md, and that the tools.md says “read-only.” Run /os-coach status: unused layers appear as not started with a reason, not as an error.
Why learn
Because by the end of this module your OS has real capability: at least one skill that runs the same way every time, read-only connections to the data it needs, and, if it makes sense, an agent with a review gate. This is the right time to stop and score everything against the objective — what you do in Module 4.6 with the audit.
Key concepts
✅ Module summary
Next module:
4.6 — audit: score against the objective 📊