Building Block 3 - Skills
Write your project's knowledge down once, so the agent reads it on every run instead of guessing - and guessing wrong
The Goldfish Problem
Here's an annoying fact about AI agents: they have no long-term memory between sessions. Every time a loop runs, the agent wakes up like a goldfish - it has forgotten everything about your project. It doesn't remember your naming rules, your build steps, or the painful outage that taught your team "never touch that file directly."
So what does it do with the gaps? It guesses - confidently. And a confident wrong guess, repeated on every loop run, is expensive and dangerous.
What a Skill Actually Is
A Skill is just a folder with a file called SKILL.md inside it (plus any helper scripts or notes it needs). The SKILL.md holds plain-English instructions and a short description of when to use it. Both Claude Code and the Codex app use this exact same format.
my-project/
.claude/ (or .codex/)
skills/
ci-triage/
SKILL.md ← the instructions the agent reads
helpers/ ← optional scripts, references, examplesWhat Goes Inside a SKILL.md
A good Skill captures the stuff an agent would otherwise guess. For a CI-triage loop:
# CI Triage Skill ## How to classify a failing test - env: missing secret or infrastructure → escalate to a human - flake: passes on a clean retry, no code change → file a report - bug: fails the same way every time, tied to a recent commit → draft a fix ## Fix patterns (where to look first) - Auth tests → check src/auth/middleware first - Database tests → check whether recent migrations ran in CI ## Never do - Never disable a failing test just to make the build pass - escalate instead. - Never touch code inside src/payments/ or src/billing/.
See the three parts? How to think about the task, where to lookbased on hard-won experience, and hard rules it must never break. That last section - the "never do" list - is often the most valuable, because it encodes the mistakes your team already paid for.
Why Skills Make Loops Cheaper AND Better
Two wins, and they compound over time:
Without a Skill, the loop re-derives your whole project from scratch every cycle - reading tons of code, burning tokens, to re-learn what you already know. With a Skill, it reads a short doc instead. Less wasted thinking = lower cost.
Your conventions and your "don't do this because of that outage" notes are applied every run, consistently. Intent stops leaking. The loop's output starts to actually look like your team wrote it.
One Clarification: Skill vs. Plugin
People mix these up. A Skill is the authoring format - the knowledge itself. A plugin is how you ship it - how you bundle one or more Skills (and connectors, coming next lesson) so a teammate can install your whole setup in one go instead of rebuilding it from memory.
Hands-On: Draft Your First SKILL.md
SKILL.md in a plain text file. Include the three sections from above: (1) how to think about the task, (2) where to look / fix patterns, and (3) a "never do" list of at least 3 hard rules. Pay special attention to #3 - write down the things you'd be nervous about an eager junior doing unsupervised. That nervousness is exactly the knowledge worth encoding. You'll reuse this file in the capstone.Agents forget everything between runs and fill the gaps with confident guesses
Project knowledge written once in a SKILL.md file that the agent reads on every run
How to think about the task + where to look (fix patterns) + a "never do" list of hard rules
Skills cut wasted re-learning (cost) and apply your conventions consistently (quality)
A tight, plain description makes the agent reach for the Skill at the right time
You write a Skill (the knowledge); you ship it as a plugin (the bundle)