The markdown is the message

What changed

If that is not how you work yet, look at how other good engineers write their markdown files: their skills, their tests, their rules. Every developer getting good results with AI agents has the same thing going on. They are building markdown systems, not writing better prompts. Skills, mainly. We love skills.

Markdown engineering: the practice of building and maintaining the markdown systems that control how AI agents write your software.

For decades, the artifact was code. You wrote it, reviewed it, shipped it. That changed fast.

Andrej Karpathy named the pattern in early 2025: vibe coding. Prompt the AI, accept the output. A year later he called it passé. What replaced it was agentic engineering, where you orchestrate agents instead of writing code yourself.

Everyone asked how to orchestrate agents better. Almost nobody asked what medium they were orchestrating in. The medium is markdown: structured text files that tell agents how to behave.

McLuhan saw this decades ago in a different context. People fixate on content and miss the medium reshaping everything around them. The generated code is the content everyone stares at. The markdown is the medium running the show. Change one line in CLAUDE.md and every future agent session changes. Add a guardrail to a skill and every invocation after that inherits it.

That is the whole thesis. The code is generated; the markdown is engineered.

Not prompt engineering

People mix these up constantly, so let me be specific.

Prompt engineering is disposable. You write a message, get a response, and that context evaporates. Next session, you are starting from scratch. There is no git history and no way to figure out what broke last Tuesday.

Markdown engineering is the opposite. The files stick around. They live in version control. You can diff them, blame them, review them in a pull request. Anyone who clones the repo gets everything you wrote. You make a decision once and it carries forward into every session after that.

The layers

It is more than one file. The set will grow and change, but these are the layers as I see them today, each depending on the ones below it: primitives at the bottom, then models, tools, MCPs, skills, and the harness on top.

┌─────────────────────────────┐
│  HARNESS                    │
│  Claude Code, Codex, Pi     │
├─────────────────────────────┤
│  SKILLS                     │
│  Composed behaviours        │
├─────────────────────────────┤
│  MCPs                       │
│  External connections       │
├─────────────────────────────┤
│  TOOLS                      │
│  Built-in capabilities      │
├─────────────────────────────┤
│  MODELS                     │
│  Claude, GPT, Gemini        │
├─────────────────────────────┤
│  PRIMITIVES                 │
│  Markdown, CLI, Bash, Git   │
└─────────────────────────────┘

Primitives

Four things sit underneath everything.

Markdown is structured text: headers, bullets, code blocks. You write it like English, but machines can parse it too, which is why it became the default format for talking to agents.

The command line is a text interface where you drive the computer by typing commands instead of clicking buttons.

Bash is the scripting language that runs those commands. To be honest, this is most of what an agent needs to become powerful.

Git is version control. It tracks every change to every file, with full history, so when something breaks you can see exactly what changed and roll it back. It is not strictly necessary for working with coding agents, but if you do not know git, please learn it.

Models

The AI: Claude, GPT, Gemini. The thing reading your instructions and writing code. Which model you pick matters far less than the markdown you feed it. Pick any frontier model; they all behave well these days.

Tools

Capabilities the agent ships with: reading files, editing them, running commands, searching code. Local, always on, nothing to configure.

MCPs

The Model Context Protocol is a standard way to plug agents into external services, such as your database, your deployment pipeline, or a search engine. If tools are what the agent can do locally, MCPs are how it reaches everything else. I wrote up where skills stop and tools begin separately, because confusing the two is the most common design mistake I see.

Skills

A skill is a markdown file that tells the agent how to do something: name, steps, guardrails, expected output. You write it once and it works across every project.

The skill that runs my git workflow is the example I reach for. It knows the steps, and more importantly it knows what not to do: no force pushing, no committing secrets, no skipping hooks. I wrote that judgment once. Now it runs in every project.

I have over a hundred of these. They chain into workflows, and the system gets better as I add more. Getting them into every agent I use turned out to be its own problem, which is why I maintain a package manager for skills.

Harness

A model can think, but it cannot do anything on its own. It cannot read your files, run your tests, or push to git. The harness is what wraps around the model and lets it act. Claude Code is a harness. Codex is a harness.

It handles tool calls, file access, permissions, progress across sessions, and recovery from errors. A bad harness lets the model try to do everything at once, lose context, and fall apart. A good harness keeps it focused, working incrementally, testing as it goes. What the good ones have in common is the subject of a longer piece.

Why it compounds

Skills and rules persist between sessions, so day 90 is better than day 1, and not because I got smarter: the markdown layer remembered and compounded what I learned. Skills build on rules and workflows, rules reference conventions, workflows chain skills together. It ends up modular without anyone planning it that way.

It is also measurable, which surprised me. First-run success rate, reprompts per workflow. When the markdown is tight, those numbers go down. When it drifts, they point to exactly where.

The code is generated. The markdown is engineered.