LoopWorkbench
intermediatepractical-guidesloop-engineeringskillsskill-mdintent-debt

Chapter 4 of 8

Skills: Codifying Project Knowledge

How SKILL.md files stop you re-explaining your project every session — the single biggest lever for making a loop compound instead of re-derive.

Skills: Codifying Project Knowledge

A skill is how you stop re-explaining the same project context every session like a goldfish.

What a skill is

Both Claude Code and Codex use the same format: a folder with a SKILL.md inside holding instructions and metadata, plus optional scripts, references, and assets.

.claude/skills/
└── deploy-checklist/
    ├── SKILL.md          # instructions + metadata
    ├── verify.sh          # optional script
    └── rollback.md        # optional reference

---
name: deploy-checklist
description: Pre-deploy verification for the payments service. Run before any deploy to prod.
---

# Deploy Checklist

1. Run `npm run test:integration` — all green required
2. Confirm the migration in `migrations/` is backward-compatible
3. Check that feature flags for this release are ON in staging
4. Never deploy during the 9am-10am traffic spike (we learned this the hard way)

How skills get invoked

  • Explicitly: call $skill-name or /skills deploy-checklist
  • Implicitly: the agent runs the skill on its own when your task matches the skill's description — which is why a tight, boring description beats a clever one.

Write the description for the matcher, not the reader

The skill description is read by the model to decide whether to invoke the skill. A vague description ("helps with deploys") gets invoked at the wrong times. A specific one ("Pre-deploy verification for the payments service, run before any prod deploy") fires exactly when it should.

Why skills matter inside a loop specifically

An agent starts every session cold and will fill any hole in your intent with a confident guess. A skill is that intent written down on the outside — the conventions, the build steps, the "we don't do it like this because of that one incident" — written one time where the agent reads it every run.

Without skills, the loop re-derives your whole project from zero every cycle. With skills, it compounds.

This is the cure for what Osmani calls intent debt: the cost of re-stating what you want, paid over and over, every single run.

Skill vs. plugin — keep them straight

  • The skill is the authoring format (a folder with SKILL.md).
  • The plugin is how you ship it.

When you want to share a skill across repos, or bundle several together for a teammate to install in one go, you package them as a plugin. True in Codex, true in Claude Code.

Skills don't replace verification

A skill encodes what the project knows. It does not encode what's actually true right now. A skill that says "tests must pass" doesn't make tests pass — the loop still has to run them. Skills make the loop competent; they don't make it correct.

What this block contributes to the loop

Skills are how a loop gets good at your specific project without you standing over it. The first time the loop runs, it reads the skills and knows the build steps, the gotchas, the rollback procedure. The hundredth time, it still knows — because the knowledge lives on disk, not in a conversation you'd have to repeat.

Next: Connectors & MCP — plugging the loop into your actual environment so it can act, not just advise.

Prerequisites