Text has been our way to transmit knowledge for five millennia. A simple text file is also the best way to tell an AI agent what to do. Some things don't need reinventing.
That's because text has properties almost nothing else can match: it's searchable, versionable, editable, shareable, and costs almost nothing to store. Text has outlasted every competing medium, and most formats eventually get converted back to it.
Of all the ways to write plain text, one format has emerged as the sweet spot between human-readable and machine-readable: markdown.
Markdown is plain text with a few simple symbols for formatting. Anyone can write it without learning a programming language, yet it's structured enough that machines can parse it reliably. Of all text formats, it's the one that works equally well for both.
You're actually reading it right now. This post was written in a markdown file inside Obsidian and rendered into the webpage in front of you. Adding a new post is as simple as pushing a markdown file to my GitHub repository. The rest happens automatically.
That simplicity is the whole point.
Markdown has been part of code repositories for years. Every codebase has a README.md, a plain text file that explains how the code works, written for humans but read just as easily by machines.
Models trained on all that code absorbed all the markdown too. In the end it's all just text, and text is what language models are built to understand.
Code, markdown, JSON, PDFs. It's all just text. And at its core, all a language model does is recognise patterns and predict what comes next.
The best way to give an agent instructions is through text. The problem is that normally all you have is a system prompt. And as that prompt gets bloated with more and more instructions, it's like someone yelling five different tasks at you all at once. Every single time, even if only one task is needed. No wonder agents struggle to execute cleanly.
Just in time knowledge
The natural progression is to keep the system prompt lean. Just the high level instructions: who the agent is and what its boundaries are. Then you give the agent access to a folder of text files and let it discover them on demand.
Anthropic calls this progressive disclosure. The agent gets access to a folder of skill files, each with a short description. It reads only what it needs, deciding on its own whether to go deeper into any given file.
Think of how you glanced at the title of this article before deciding to read further. Agents do the same thing with skill files.
What's actually in a skill file? Just a markdown file with instructions. It might describe how to handle a customer complaint or how to fetch data from your latest marketing campaign. It captures decision logic, business context and the kind of knowledge that usually lives only inside someone's head.
This is what makes skill files composable. You can chain them together into a workflow. An agent handling a customer refund might pull from a skill file for tone and policy, another for checking order status, and another for drafting the response. Each file stays focused, but together they handle something complex.
A skill file embeds just in time knowledge directly into the agent's context window. The agent itself stays generic. Its actions become specific.
Every major AI tool now converges on the same idea. A text file in markdown tells the agent what to do, what it knows and how it should behave. Markdown has quietly become one of the most important interfaces between humans and AI agents. That convergence is now official. The open standard lives at agentskills.io, governed by the Agentic AI Foundation under the Linux Foundation.
From one brain to an entire organization
What makes this approach powerful is that it scales. At the simplest level it's one person writing down how they work, encoding their own knowledge into a folder of files. But the same principle applies to an entire organization.
Processes that live in someone's head, workflows buried in onboarding documents, business logic scattered across emails and wikis. A skill file is the new home for all of it. You write down what you know, put it in a text file, and every interaction with the agent is shaped by it from that point forward.
Like this piece? Join the newsletter.
Writing your own
So what does that actually look like in practice? Here's how I approach it.
The first way is to write them yourself. Yes, like a caveman. No AI or agents involved.
It's worth doing at least once. Going through the process manually forces you to articulate exactly how you do something, step by step. Most people discover they don't know their own workflows as well as they thought. The writing is the thinking.
The second way is to use the skill creator, a skill that Anthropic built and published on GitHub. Drop it into Claude Code, Cursor, or any agent that supports the standard. It interviews you about your workflow, asks the right questions, and writes the skill file for you. It even runs test cases to verify the output before you ship it.
The third way is my personal favorite. During sessions with an agent, every interaction leaves a trace on your computer. For Claude Code those live in ~/.claude/, for Codex in ~/.codex/.
Point your agent at that folder and ask it to review what you've been doing together. If a workflow has repeated itself a few times, it can write the skill file itself. You didn't sit down to document anything. You just did the work.
The knowledge was always there. It just needed somewhere to live. Turns out a text file was enough. The oldest interface turned out to be the right one all along. A folder of markdown files. Some things really don't need reinventing.
Get the next bite sized AI insight inside your inbox.
