I’ve been there. You stare at the docs, read the same explanation, and think: ‘This is just a markdown file in a folder. Why the hype?’ That frustration is real. But it’s also a sign you’re looking at the wrong thing.
The HN post that sparked this – where someone asked why frameworks like Claude Code or Codex don’t just use AGENTS.md – gets at a valid point. Yes, the content of a skill is often a well-organized markdown file. Yes, you could theoretically dump instructions into a folder and tell the agent to read them. But that’s like saying a car is just a metal box with wheels. You’re missing the engine.
The real innovation isn’t the markdown – it’s the agent’s ability to query, prioritize, and load the right instructions at the right time, like a dynamic file system for human knowledge.
Think of it this way: a computer’s PATH variable doesn’t care about the contents of each executable. It’s a protocol for discovery. When you type python, the system searches directories in order, finds the right binary, and runs it. Skills work the same way for AI agents. Instead of a human manually saying ‘read this file before doing X,’ the agent can automatically discover which skills are relevant to a given task, load them into context, and apply them.
That’s the architectural shift. The markdown is the payload. The protocol – the ability to index, search, and inject context dynamically – is the real value. And that’s why we see frameworks investing in skill registries, metadata, and versioning. It’s not about the format; it’s about the interface.
Calling skills ‘just markdown’ is like calling a database ‘just a CSV file.’
Take a concrete example. In Claude Code, a skill might contain instructions for a specific coding task – say, ‘how to structure a React component following project conventions.’ Without a skill system, you’d have to manually copy those instructions into every prompt, or rely on the agent’s training data. With a skill, the agent can proactively say: ‘I see you’re starting a new component. Let me load the relevant skill.’ That’s not a minor convenience. It’s a fundamental shift from manual context injection to autonomous context retrieval.
And here’s the kicker: the skeptics are right about the triviality of the format. But they’re dead wrong about the mechanism. This is a genuine architectural shift that will define how we interact with AI agents going forward. The moment you stop seeing skills as markdown files and start seeing them as a protocol – a discoverable, versioned, queryable interface for agent behavior – you’ll understand why the hype is real.
So next time you see a ‘skills’ folder, don’t see markdown. See a protocol. See a future where agents self-organize their knowledge. That’s the real story.
FAQ
Q: So skills are just markdown files? Why not just use a folder of markdown and point the agent to it?
A: You can – and that's exactly what many people do. But the difference is that a proper skill system includes a discovery mechanism: the agent can autonomously find relevant skills based on the task, load them into context, and even prioritize them. It's like having a search engine for your instructions instead of a manual file manager.
Q: What's the practical implication for someone building an AI agent today?
A: If you're building an agent, don't treat skills as just documentation. Design them as a queryable, versioned registry. The agent should be able to ask 'what skills apply to this task?' and get a ranked list. This enables modular, scalable behavior without hardcoding instructions. The skill system becomes the operating system of your agent.
Q: Isn't this just overengineering? Why not just prompt engineer the agent to know everything?
A: Because agents have limited context windows and need to dynamically adapt to new tasks. Prompt engineering everything into a single system prompt is brittle and doesn't scale. Skills allow you to decouple knowledge from the agent's core logic, making it easy to update, share, and reuse instructions across different agents and tasks. It's not overengineering – it's modularity.