Author(s): Aditya Kumar Puri

Originally published on Towards AI.

The Next Programming Language Might Be a Folder of Skills

I used to think programming an agent meant two things:

1. Write code the model can call.
2. Keep rewriting the system prompt until it behaves.

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.

A skill is a package, not a prompt paste

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

Progressive disclosure is the clever part

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]:

1. Catalog: Load only each skill’s name and description.
2. Instructions: Read the full SKILL.md when a task matches.
3. Resources: Open linked files or run scripts only when needed.

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 loading on demand Source: Image by the author, based on Anthropic’s Agent Skills explanation.

The folder has three jobs

A useful skill usually combines three kinds of material:

1. Selection metadata: The name and description tell the agent when this skill applies.
2. Procedure: The Markdown body describes steps, constraints, examples, and failure conditions.
3. Deterministic help: Scripts handle work that code can do more reliably than generated prose.

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.

Skills, MCP, and subagents solve different problems

These three ideas keep getting thrown into the same comparison, but they sit at different layers:

• Skills teach a repeatable procedure.
• MCP and other tool connections give the agent access to data or actions.
• Subagents create separate contexts for isolated or parallel work.

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:

1. Need a method? Use a skill.
2. Need access to an external system? Add a tool or MCP server.
3. Need a separate worker? Use a subagent.

Hand-drawn three-column guide showing skills for procedure, MCP for access, and subagents for isolation

Skills can be cheaper than a team of agents

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

Treat third-party skills like software

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:

1. What makes it trigger?
2. Which files and commands can it use?
3. Does it fetch anything from the network?
4. Are long references loaded only when needed?
5. Is there another installed skill with an almost identical description?

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

What I would put in a first skill

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-review
description: Review a completed code diff for correctness, security, and API contract changes. Do not edit files.
---

Then I would add:

1. The exact steps the review should follow.
2. What is out of scope.
3. The expected output format.
4. One reference file for the long checklist.
5. A script only where deterministic output helps.

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.

Conclusion

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.

References

[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

Join thousands of data leaders on the AI newsletter. Join over 80,000 subscribers and keep up to date with the latest developments in AI. From research to projects and ideas. If you are building an AI startup, an AI-related product, or a service, we invite you to consider becoming a sponsor.

Published via Towards AI