Agents, Skills, and Markdown Files: What They Actually Are
I keep ending up in the same conversation. Someone asks me how to "do AI" at their company, I start talking about skills and markdown files, and they stop me to ask what an agent is. Or I say something about a knowledge base, and they assume I mean Notion. Or I say "skill," and they assume I mean prompt.
The words are running together. People use the same three terms (agent, skill, markdown) for three completely different things, and the confusion is making it harder to figure out what they should actually do this week.
So here's the simplest version I've landed on after enough of these conversations.
A markdown file is plain text. A skill is a markdown file with instructions on how to do a specific job. An agent is a skill on a schedule. That's it.
The reason this matters is the assumption most people walk in with. They think an agent is some autonomous AI system that's getting close to AGI. It's not. It's a markdown doc with instructions running on a timer. Once you see it that way, the whole stack stops feeling intimidating.
Markdown is the substrate
Markdown is the simplest file format on the internet. A .md file with normal text and a few characters that make headers and bullets. No code. No special software. You can open one in any text editor.
LLMs read markdown perfectly. When you give Claude or ChatGPT a markdown file, the model knows how to read it without you explaining anything. Headers signal sections. Bullets signal lists. The model uses the structure the way a human would.
This is why every serious AI workflow eventually ends up in markdown. Notion exports to it. Cursor and Claude Code use it natively. When you want to give an LLM persistent context about your business, the answer is almost always: write it down in a markdown file.
If your team has personas, sales playbooks, brand guidelines, or onboarding docs sitting in Google Docs and PDFs, you don't have a knowledge base for AI yet. You have documents. Converting them to markdown is the first move.
A skill is a markdown file with a job
A skill is a markdown file with a specific structure: a short header that tells the model when to use the skill, followed by the instructions for how to do the work.
The header is the part most people get wrong. It's a few lines describing what the skill does and when to apply it. Claude reads that header on every conversation and decides whether the rest of the file is relevant. If the header is vague, Claude never loads the skill, and the work you put into the instructions just sits there.
The body is where the real work lives. "When writing in Warren's voice, don't use em dashes. Write peer-to-peer. Replace punchy phrases with specific details from real experience." That kind of thing. Five lines or five hundred, depending on the job.
I have skills for every recurring thing I do in Claude. Writing in my voice. Drafting newsletter sections. Auditing the Topiq website against our personas. Building cold call scripts. I don't re-explain any of it anymore. Claude reads the right skill at the right moment and goes.
If you find yourself typing the same instructions into Claude over and over, that's a skill waiting to be written.
An agent is a skill on a schedule
This is the one people overcomplicate.
The clearest definition comes from Anthropic: an agent is an LLM that directs its own work. It picks the tool, executes the task, checks the result, adjusts. But that definition is more intimidating than the thing actually is.
In practice, an agent is a skill running on a schedule, with permission to use tools. Same markdown file. Same instructions. The only difference is nobody has to open a chat window for the work to happen.
The SEO agent I run on Topiq's site is a good example. Every month it pulls SEMrush data, looks at what's ranking on Google and in AI search, identifies which pages have slipped, rewrites them, and updates the site. The instructions live in a markdown file. The schedule is a cron job. The tools are SEMrush, the codebase, and the deploy pipeline. There's no AGI. It's a skill plus a clock plus a few connected tools.
The reason agents feel like a different category is that the output looks autonomous. Work shows up that nobody asked for. But the work showing up is just the same work the skill would have done in chat, triggered by time instead of by a person.
Once you see it that way, the question stops being "how do I build an agent" and starts being "what work do I want to happen automatically, and what skill needs to exist for that work to be any good?"
Where most people get stuck
Most people I talk to want to start with agents. They've read about them, they want to build one, they want the autonomous-work feeling. So they stand up an agent with no skill and no markdown underneath, and the output is generic and wandering. Then they decide AI doesn't really work for their business.
The order is backwards. The teams that get real value start by writing things down (markdown), then codifying their process (skills), then turning the schedule on (agents). Each layer makes the next one work.
If you're not doing anything yet: open a markdown file and write down your personas, your value prop, and the way you talk about your product. Drop it in a Claude Project. You'll feel the difference within a week, before you build a single skill.
If you're already using markdown: notice what you re-explain to AI all the time. Voice, formatting, process steps. Each one is a skill waiting to be written.
If you're already running skills: pick one that you'd want running on a schedule and turn it into an agent. Start with something boring. SEO updates. Weekly competitive intel. Pipeline list refreshes. The agent will earn its keep on the work that consumes hours, not on the work that requires judgment.
The whole thing is less mysterious than it sounds. AI gets to know your business through the documents you've written, the procedures you've codified, and the work you've trusted it to do. If your AI feels generic, it's because nothing underneath is yours yet. Fix that and the rest takes care of itself.