How “agent skills” quietly became a standard, and why portable single-file prompts won

Two years ago there was no such thing as an “agent skill.” Claude Code shipped with a ~/.claude/skills/ directory in late 2024. Cursor and Windsurf adopted similar conventions within months. By Q1 2026 a portable, single-file markdown format had become the de-facto standard across most CLI-native AI agents. Not by formal specification, but by convergent evolution. The story of how that happened says something useful about how infrastructure standards actually emerge in the AI tooling space.

What an agent skill actually is

An agent skill is a single markdown file with YAML frontmatter and a structured prompt body. It defines a role (“you are a creative director who turns ideas into pitch decks”), the inputs the user will provide (idea, slide count, voice), the API endpoints to call, and the workflow the agent should follow.

The agent reads the skill into its context when activated. There is no runtime, no daemon, no compiled artifact. The whole skill is the markdown file. Installation is one shell command:

curl -sL https://gathos.com/skills/idea-to-presentation.md > ~/.claude/skills/idea-to-presentation.md

Where the convention came from

Three forces converged in 2024 and 2025. Claude Code shipped with the skills directory and a small starter set, demonstrating the pattern at scale. Cursor’s .cursorrules file, a single project-level prompt, proved the appetite for one-file, no-dependency extension. And the OpenAI custom GPTs format (essentially JSON schema plus system prompt plus actions) showed what users didn’t want: a marketplace, an approval queue, and platform lock-in.

By mid-2025 most CLI-native agents had converged on the same conventions. Markdown source of truth. Predictable file locations. Frontmatter for metadata. Windsurf, Aider, OpenClaw, and Continue all shipped compatible patterns. Notably absent from the convergence: GUI-first tools like ChatGPT Custom GPTs and Microsoft Copilot Studio, which still favor proprietary formats and vendor-managed marketplaces.

Why markdown won

• LLMs read prose better than structured data. Prompts written as instructions consistently outperform the same content in JSON or YAML. The model is being asked to follow a recipe. Recipes work better in English than in declarative syntax.
• Human-editable without tooling. A developer can open a skill in any editor, iterate on the prompt, and test changes immediately. No build step, no schema validation, no IDE-specific format support required.
• Path-of-least-resistance compatibility. Once Claude Code’s convention had a community of installed skills, Cursor and Windsurf adopted compatibility because that was easier than competing with a different format.

How skills relate to MCP and function calling

These are three different tools for three different needs.

Most production agents use all three. Skills define what to do. MCP servers expose how to talk to live systems. Function calling handles atomic in-request operations.

What this means for API providers

For any company shipping an API that agents are likely to use, three things are now table-stakes:

• Publish at least one reference skill. It demonstrates the canonical workflow and gets people from “I have an API key” to working code in minutes rather than hours.
• Host skills on your own domain at stable URLs. The install command is curl -sL https://yourdomain.com/skills/{name}.md. Don’t hide skills behind GitHub repos that get renamed. Breaking the install command breaks every downstream agent.
• Design errors for agent recovery. Rate-limit responses should include limit_type so the agent knows whether to wait, switch APIs, or surface a billing prompt. Validation errors should specify the field. Async jobs should return a polling URL, not require a webhook.

The standardization debate

The Agent Skills Spec proposal (drafted in Q1 2026 with contributors from Anthropic, Vercel, and several independent maintainers) is the current effort to formalize the convention. It proposes a frontmatter schema, a canonical file location convention (~/.agents/skills/{namespace}/{name}.md), and an optional capabilities block.

The community appears split between two camps. Those who want a lightweight standard mostly to ensure cross-tool compatibility. And those who think the lack of a standard is itself a feature, because skills are valuable precisely because they’re plain text that any LLM can read. The most likely outcome is the lightweight standard lands in late 2026 with optional adoption.

The interesting precedent here isn’t the format. It’s that an AI tooling convention emerged through community convergence rather than vendor specification. That’s rare in infrastructure history, and worth paying attention to.

What’s likely next

Three things to watch over the next twelve months. Skill marketplaces, vendor-neutral aggregators (early candidates: skills.dev, agent-skills.org), will start to compete with vendor-managed catalogs. Agent IDEs (Cursor, Windsurf, several new entrants) will compete on built-in skill management UX. And the line between “skill” and “subagent” will get blurry. Composable agents that delegate to other agents are already shipping in some platforms and will increasingly look like skill chains.