Ask HN: I still don't understand why AI agents need "skills"
I’ve asked AI a few times and I still don’t get it.
Why do frameworks like Claude Code or Codex have the concept of “skills” instead of just using well-organized Markdown docs?
Couldn’t I just have an AGENTS.md that points to folders of .md files and tells the agent when to read them? That feels functionally equivalent to me.
What am I missing? Is there a real architectural benefit, or is it mostly a standardization/convenience thing?
I doubt we’d create so much hype about skills if they’d just be a md file that’s in a skills folder. So I feel I’m missing something.
> Why do frameworks like Claude Code or Codex have the concept of “skills” instead of just using well-organized Markdown docs?
"Well-organized markdown docs" are exactly what skills are.
More specifically, they are well-organized markdown docs that explain how to do some particular thing.
This. Skills are exactly that, well structured markdown documents. Its the same with AI agents. You define the structure, what it can and can't do, setup rules and guidelines and then the AI sticks to that exact model. I sell skills on marketplace because sometimes, crafting the perfect prompt can be hard - you want something specific and very particular and don't know how to ask AI to do that. This is where skills come in. You can create your own skills or get them from someone else. They're great.
How do you sell them - do you give a preview or how else do you protect it from just being copy/pasted?
how much do you make selling skills on marketplace, just curious? It seems like it'd be impossible to vet a skill without reading it, so the entire concept mystifies me just a little bit.
Usually only charge a few bucks because honestly, anyone can make them but those that buy get them because they don't want to spend the time on making them. You can sell them for $10 or $15, maybe more depending on the skill. Not always a lot but if you have a ton of them, you can make some serious cash.
Where are you selling them?
From the research, it does seem like skills increase performance though it varies quite a lot by domain and whether they were written by ai or humans https://www.skillsbench.ai
But whether they would do better than just markdown on its own isn't really settled. Would be interesting to see a comparison of same tasks, same agent, same context budget, skill vs the same content pasted into AGENTS.md.
Skill is a document that AI agent ignores, distorts and forgets immediately after reading it :)
If you add all those .md files to your AGENTS.md, your harness will likely load all those files into context. This will create context pollution for you.
Context, similar to your computer's memory, is limited.
Additionally, the more things the AI has in context, the worse it performs.
Skills helps you to quickly add more context for doing things, without polluting your context window.
I think you need to learn about AI, there isn't anything hype there. It's just an easier way of giving more context to the AI.
This can be helpful, for example, if you have an internal API that does XYZ, and you want the AI to know that API, you can save that API, its endpoints and authenticaiton methods to a skill, and invoke it when you want your harness (CC, Codex) to know about the existance of that API, to make requests, make tests etc.
Aren't "skills" just some words and syntax that tokenize in a fashion that gets an instance of an LLM primed for (you hope) the right thing statistically?
After that, I think "skill" is just a good name. It sounds more "AI" than a "spell" or "incantation", which would sound magical and esoteric.
It is just marketing speak to evoke some similarity to Sci-fi movies show AI robots learning stuff by quickly going books.
Nothing of the sort happens here though...
So you are not missing anything. What you think is exactly what it is. Just some prefix for preloading the LLM context with..
A skill is more like a packaging convention around instructions, with the difference that the runtime knows it's a reusable unit. That lets it expose only the skill's name/description initially and load the full instructions (and sometimes bundled scripts or other resources) only when needed. Truth is that if you implemented the same lazy behavior with AGENTS.md and a bunch of Markdown files you'd end up with something that is functionally very close to a skills system.
Something like instructions in Projects? Or how? Could you please describe the pros and cons of each and when to use each?
That'd be truly helpful!
The goal is more or less the same, to give the agent the ability to do things it doesn’t know by default. The difference when explaining this new thing to the agent using a skill is that it will only learn how to do it when it needs to, not all the time in all conversations (as the AGENTS.md file is read at the start of every new conversation). Furthermore, giving a model a new capability might require more than just a couple of Markdown files, and that’s where skills come in since they’re only read when needed, rather than at the start of every conversation, so they don’t waste tokens unnecessarily on something that could be very resource-intensive. Plus, decoupling them from an AGENTS.md file makes them easier to deploy.
An example of a skill I use a lot is draw-io skill (https://github.com/Agents365-ai/drawio-skill), it enables the agent to generate Draw.io diagrams. As you can see, there are a lot of Markdown files, but also Python scripts that the model must run to gather what it needs. If this was defined in an AGENTS.md file for a single project it wouldn’t be so bad, but if you have to maintain five skills of this size in your agent (or simply want to share them), you can’t include them in the AGENTS.md file, because they’ll consume all the context, even in a conversation where the agent won’t use any of them. It's like writing reusable and callable functions instead of writing all code in the main() method.
Skills represent a pattern many of us converged to before it was named as such (very useful for comms): Progressive disclosure, determistic scripts bundled (not just markdowns). See past comment:
https://news.ycombinator.com/item?id=48132477
Don't underestimate the value of "Skill builder" skills too. Great UX
Skills is just lazy loading of well-organized Markdown docs. The "lazy" part is the core part.
To add to what the other person said, they're also loaded differently than arbitrary docs.
They're presented as a list of titles and descriptions to the LLM and it can pick which ones seem relevant and load them.
Markdown docs the LLM needs to make a tool call to read the files and potentially multiple tool calls to discover data if there's a hierarchy. Additionally, it now has to decide if it should read the entire file or cherry pick parts of it.
Skills organize that in an atomic and composable way.
I think ChatGPT and Claude skills will also package arbitrary artifacts like scripts as well. Not sure if that's standard or not
Skills are lazy loaded. AGENTS.md is not. It’s stupid regardless.