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.
"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.
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
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.