I used to think programming an agent meant two things:
Now the interesting unit is often a folder.
Inside it: a SKILL.md, a few instructions, maybe a script, maybe some references. The agent discovers the folder, reads just enough to decide whether it matters, then loads the rest only when the task calls for it.
Anthropic calls these Agent Skills [1]. The format became an open standard in December 2025 [2]. Claude Code and Codex now support skills built around that portable shape [3][4].
No, folders are not replacing Python. Put the pitchfork down.
The point is that we are gaining a new way to program how an agent works, not only what software it produces.
At minimum, an Agent Skill is a directory with one required file: SKILL.md. That file starts with YAML metadata and continues with the instructions the agent should follow [1][2].
It can also contain scripts, templates, examples, and longer reference material:
pr-review/├── SKILL.md├── references/│ └── review-checklist.md└── scripts/ └── summarize-diff.sh
That shape changes the relationship with the instructions. A pasted prompt disappears into chat history. A folder can live in git. I can diff it, review it, pin it, share it with a team, or delete it when it starts doing something strange.
In Claude Code, personal skills live under ~/.claude/skills/, while project skills live under .claude/skills/ and can travel with the repository [4].
Hand-drawn anatomy of a skill folder with SKILL.md, references, scripts, and assets
If an agent loaded every installed skill in full at startup, a large library would eat the context window before I typed “hello.”
Skills avoid that with progressive disclosure [1][2]:
Think of it as a menu. The agent sees “PR review,” not the entire cookbook. If I ask it to review a patch, it opens that recipe. If the skill points to a security checklist, it reads the checklist at that moment.
This is why a skill feels different from another section in CLAUDE.md. Always-on instructions belong in the project context. A long workflow that matters twice a month belongs behind a skill name [4].
Hand-drawn three-step flow showing metadata, SKILL.md, and linked resources on demand Source: Image by the author, based on Anthropic’s Agent Skills explanation*.*
A useful skill usually combines three kinds of material:
That third part matters. If the task is “sort these records,” the agent does not need to role-play a sorting algorithm one token at a time. It can run a script.
The folder becomes a bridge between fuzzy reasoning and boring code. Boring code is underrated. It tends to arrive at work on time.
These three ideas keep getting thrown into the same comparison, but they sit at different layers:
Anthropic describes skills as complementary to MCP. A tool connection might let an agent read an issue tracker. A skill can teach the agent how your team triages those issues [1].
Claude Code’s own guidance makes a similar distinction: use a skill for a reusable workflow in the main context; use a subagent when the work needs isolation, different tools, or a clean context window [5].
My shortcut:
Hand-drawn three-column guide showing skills for procedure, MCP for access, and subagents for isolation
A January 2026 paper asked whether some multi-agent workflows could be compiled into a single agent with a library of skills [6].
On its controlled reasoning benchmarks, the skill-based setup used about 54% fewer tokens and had about 50% lower latency on average while keeping comparable task accuracy [6]. Those figures belong to the paper’s selected benchmarks and GPT-4o-mini setup. They are not a promise for every coding project.
Still, the design makes sense. If three agents only pass instructions to one another in sequence, a single agent may be able to load those behaviors as skills without paying for three separate conversations.
There is a catch.
The paper found that skill selection could fall sharply as libraries grew, especially when descriptions were semantically similar [6]. A folder full of api-helper, api-helper-pro, and better-api-helper-final is not a library. It is a cry for help.
The authors found hierarchical routing useful: choose a category first, then choose a skill inside it. Good naming and deletion matter too.
Hand-drawn comparison of a confusing flat skill list and a hierarchically routed skill library
Skills can contain scripts and instructions that use tools or reach the network. Installing one is closer to adding a package than bookmarking a prompt.
Anthropic recommends using trusted sources and auditing a skill’s files, code, and external dependencies before use [1]. The open Agent Skills specification also gives us something valuable: a predictable directory to inspect [2].
Before I trust a skill, I want to know:
The scary skill is not always the obvious malware sample. Sometimes it is a cheerful 900-line SKILL.md that triggers on the word “code.”
I would not start with a catalog of 100.
Pick one procedure you already repeat, such as PR review, and make the first version painfully small:
---name: pr-reviewdescription: Review a completed code diff for correctness, security, and API contract changes. Do not edit files.---
Then I would add:
Finally, I would watch whether the agent loads it at the right time. A skill that never triggers is documentation. A skill that always triggers is a system prompt wearing a fake mustache.
The next programming language is not literally a directory tree.
But the folder is becoming a real unit of agent programming: metadata for discovery, Markdown for procedure, code for deterministic work, and references loaded only when needed.
That gives agent behavior some software-like properties we were missing. Skills can be versioned, reviewed, composed, shared, and audited. They can also conflict, bloat, and execute unsafe code, which is another very software-like property.
So I am done treating skills as fancy prompt snippets.
The model is the processor. The folder is starting to look like the program.
[1] B. Zhang, K. Lazuka, and M. Murag, “Equipping agents for the real world with Agent Skills,” Anthropic Engineering, October 16, 2025. https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
[2] Agent Skills, “Specification.” https://agentskills.io/specification
[3] OpenAI, “Skills in ChatGPT,” OpenAI Help Center, updated July 2026. https://help.openai.com/en/articles/20001066
[4] Anthropic, “Extend Claude with skills,” Claude Code documentation. https://code.claude.com/docs/en/skills
[5] Anthropic, “Create custom subagents,” Claude Code documentation. https://code.claude.com/docs/en/sub-agents
[6] X. Li, “When Single-Agent with Skills Replace Multi-Agent Systems and When They Fail,” arXiv:2601.04748, 2026. https://arxiv.org/abs/2601.04748
The Next Programming Language Might Be a Folder of Skills was originally published in Towards AI on Medium, where people are continuing the conversation by highlighting and responding to this story.