I spend more time on markdown files than I do writing functions. Maybe we all do these days. If you don’t, I really suggest you look at how other good engineers write their markdown files (skills, tests, rules, etc).
Any function I used to write by hand, the agent writes now. Whether I trust what it writes depends on the markdown I maintain. Rules, skills, tests. Those files are the actual engineering.
The code is generated. The markdown is engineered.
The line between “agentic engineering” and “vibe coding” is this: every developer getting good results with AI agents has the same thing going on. They’re not writing better prompts. They’re building markdown systems. Skills, mainly. We love skills.
Markdown Engineering: the practice of building and maintaining the markdown systems that control how AI agents write your software.
What changed
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 passe. 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.
The code is generated. The markdown is engineered.
That line is the whole thesis behind Markdown Engineering.
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’re starting from scratch. There’s no git history. 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 PR. 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
This isn’t one file. This might grow and change over time but these are some of the fundamental layers each depending on the ones below: primitives at the top, then models, tools, MCPs, skills, and the harness at the bottom.
┌─────────────────────────────┐
│ HARNESS │
│ Claude Code, Codex, Pi │
├─────────────────────────────┤
│ SKILLS │
│ Composed behaviors │
├─────────────────────────────┤
│ MCPs │
│ External connections │
├─────────────────────────────┤
│ TOOLS │
│ Built-in capabilities │
├─────────────────────────────┤
│ MODELS │
│ Claude, GPT, Gemini │
├─────────────────────────────┤
│ PRIMITIVES │
│ Markdown, CLI, Bash, Git │
└─────────────────────────────┘Primitives
Four things 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.
CLI (Command Line Interface) is a text-based interface where you interact with your computer by typing commands instead of clicking buttons.
Bash (Bourne Again Shell) is the scripting language that runs those commands. To be honest, this is mostly all an agent needs to become pretty powerful.
Git is version control. It tracks every change to every file, with full history. When something breaks, you can see exactly what changed and roll it back. It’s not strictly necessary for working with coding agents, but if you don’t know git, please learn it.
Models
The AI. Claude, GPT, Gemini. The thing reading your instructions and writing code. Which model you pick matters way 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
Model Context Protocol. A standard way to plug agents into external services, like your database, deployment pipeline, or search engine. If tools are what the agent can do locally, MCPs are how it reaches everything else.
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.
My /push skill handles my entire git workflow. But 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.
Harness
A model can think but it can’t do anything on its own. Can’t read your files, can’t run tests, can’t push to git. The harness is what wraps around the model and lets it actually act. Claude Code is a harness. Codex is a harness.
It handles tool calls, file access, permissions, keeping track of progress across sessions, recovering 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.
Why it compounds
Skills and rules persist between sessions. So day 90 is genuinely better than day 1, not because I got smarter, but because 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’s 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.
This site will be a collection of the systems, concepts, and tools that are core to Markdown Engineering.