Ask HN: I still don't understand why AI agents need "skills"
14 points - yesterday at 12:09 AM
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.
Comments
infotainmentyesterday at 12:19 AM
> 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.
watchdog408today at 9:28 AM
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.
toplinesoftsysyesterday at 6:50 AM
Skill is a document that AI agent ignores, distorts and forgets immediately after reading it :)
qserayesterday at 8:18 AM
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..
alexhansyesterday at 7:53 AM
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:
Don't underestimate the value of "Skill builder" skills too. Great UX
bad_usernameyesterday at 6:27 AM
Skills is just lazy loading of well-organized Markdown docs. The "lazy" part is the core part.
nijaveyesterday at 1:07 AM
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
shartsyesterday at 8:20 AM
Skills are lazy loaded. AGENTS.md is not. It’s stupid regardless.
bediger4000yesterday at 2:23 AM
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.