The Cambrian Explosion of Instruction Files

Every AI coding tool now reads a markdown file from your repo. None of them agree on what to call it.

.cursorrules. CLAUDE.md. AGENTS.md. GEMINI.md. .windsurfrules. .clinerules. copilot-instructions.md. And then the stranger ones: SOUL.md. SKILL.md. HEARTBEAT.md. Each tool invented its own filename, its own conventions, its own way of letting developers whisper instructions to the machine. The result is a format war that nobody planned, a Cambrian explosion of configuration files that reveals something deeper about how the relationship between developers and AI agents is evolving.

This is not a story about file formats. It is a story about what happens when an entire industry simultaneously discovers that the most powerful thing you can give an AI is not a better model - it is better context.

The Landscape, As It Stands

As of April 2026, over 60,000 open-source repositories on GitHub contain an AGENTS.md file. Tens of thousands more have copilot-instructions.md, CLAUDE.md, or .cursorrules. And the numbers are growing weekly.

Each format emerged from a different tool. .cursorrules came first, born inside Cursor in early 2024 as a simple plaintext file where developers could tell the AI editor how to behave. It was tool-specific by design - a configuration file, not a standard. GitHub followed in October 2024 with copilot-instructions.md, tucked inside .github/ alongside familiar CI configs. Anthropic introduced CLAUDE.md for Claude Code, placing it at the repo root with a hierarchical system of project, user, and local instruction files. Google created GEMINI.md for Gemini CLI. Codeium built .windsurfrules for Windsurf. Cline created .clinerules. Amazon added .amazonq/rules/. JetBrains introduced .junie/guidelines.md for Junie. Continue.dev has .continue/rules/. Aider uses CONVENTIONS.md.

And then, in August 2025, AGENTS.md arrived - released by OpenAI and, by December, donated to the Linux Foundation's Agentic AI Foundation. It has since been adopted by over twenty tools including Claude Code, Cursor, GitHub Copilot, Gemini CLI, and Windsurf. It is the closest thing this ecosystem has to a universal standard: plain Markdown, no schema, no frontmatter, just instructions that any agent can read. By early 2026, sixty thousand open-source projects had one.

The fragmentation is real. But so is the convergence.

What Goes in These Files

Despite different filenames, the contents are remarkably similar. A study of 2,303 context files across Claude Code, Codex, and Copilot found consistent patterns: 69.9% contain implementation details, 67.7% describe architecture, 62.3% include build and run commands. Only 14.5% address security - a gap that grows more conspicuous as agents gain the ability to execute code autonomously.

The typical instruction file reads like a memo to a new team member who is brilliant but has no institutional memory. Here is how we structure our code. Here is how we run tests. Here is what we never do and why. The best ones encode what a study from PROFES 2025 calls “agentic coding manifests” - not just rules, but the reasoning behind them.

This is what distinguishes instruction files from their ancestors in the config-as-code lineage. .editorconfig (2012) told your editor how many spaces to use. .eslintrc (2013) told your linter which patterns to flag. These were deterministic: the tool either followed the rule or it did not. Instruction files are probabilistic. They are context, not configuration. The AI interprets them, weighs them against other context, and makes judgment calls. This is a fundamentally different contract between developer and tool.

SKILL.md: Capabilities, Not Just Rules

In October 2025, Anthropic introduced a different kind of file. Where instruction files tell an agent how to behave, SKILL.md tells an agent what it can do.

A skill is not a single file but a directory: a SKILL.md with YAML frontmatter and Markdown instructions, plus optional scripts/, references/, and assets/ folders. The frontmatter is minimal - a name and a description. The body contains step-by-step procedures. The supporting directories contain executable code, documentation, and templates that the agent loads on demand.

The architectural insight is what the specification calls progressive disclosure. At startup, the agent reads only the name and description of each available skill - roughly fifty to a hundred tokens per skill. When a skill is relevant, the full instructions load. When those instructions reference a script or document, that loads too. This three-tier system reduces context consumption by roughly ten times compared to stuffing everything into a single prompt.

In December 2025, Anthropic published Agent Skills as an open standard. By April 2026, over thirty tools support it natively - Claude Code, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, JetBrains Junie, Roo Code, and others. The anthropics/skills repository has accumulated 110,000 GitHub stars. Marketplaces like SkillsMP index hundreds of thousands of skills crawled from GitHub.

The difference between a skill and a rule is the difference between giving someone a manual and giving them a toolkit. Vercel published skills for Next.js best practices. Trail of Bits published skills for security auditing. Stripe published skills for payment integrations. Figma published skills for translating designs to code. Cloudflare, HashiCorp, Supabase, Sentry, Expo - the ecosystem reads like a roster of modern infrastructure.

Perhaps the most telling skill is Anthropic's own skill-creator: a meta-skill that interviews the developer, generates a new skill, builds evaluation test cases, and benchmarks performance. Skills that create skills. The recursion is the point.

SOUL.md: Identity, Not Instructions

Then there is SOUL.md, and it is something else entirely.

The word “soul” entered the AI lexicon through two paths. Inside Anthropic, philosopher Amanda Askell led work on what the team informally called the “soul doc” - a roughly 14,000-token document woven into Claude's training that defines the model's character, values, and ethical reasoning. In December 2025, researcher Richard Weiss discovered that Claude could partially reconstruct this document from memory. Askell confirmed its authenticity. Anthropic later published an expanded version as Claude's Constitution, released under CC0.

Independently, Austrian developer Peter Steinberger was building OpenClaw - a weekend project connecting Claude to WhatsApp that would become the fastest-growing software project in GitHub history at 347,000 stars. Steinberger gave his agent a file called SOUL.md to define its personality. On the Lex Fridman Podcast, he described the problem it solved: “When I built it in the beginning, my agent had no personality. It was just... Claude Code.”

The SOUL.md concept diverges from instruction files in a fundamental way. .cursorrules and CLAUDE.md are project-scoped: they tell the agent how to work on this codebase. SOUL.md is agent-scoped: it tells the agent who to be. A comparison framework puts it this way: CLAUDE.md is a job description, SKILL.md is a toolkit, SOUL.md is a personality profile.

The Soul Spec formalizes this into a multi-file architecture: SOUL.md for identity and worldview, STYLE.md for voice and syntax, SKILL.md for operating modes, MEMORY.md for session continuity. The ClawSouls registry distributes eighty-plus pre-made personalities that can be installed with a single command. There are souls for law firm intake bots, Japanese language tutors, and creative writing partners.

The philosophical essay published at soul.md articulates the motivation: “Sessions end. Context windows clear. Without external memory, each conversation starts from zero. A soul document provides continuity - not of memory, but of self.” Calling it a “soul” rather than a “config” is a deliberate linguistic choice. It signals that developers increasingly think of AI assistants as entities with identity rather than tools with settings.

Whether a markdown file can constitute a soul is a question for philosophers. Whether it changes the agent's behavior is an empirical question, and the answer is yes. The 4,800 soul.md files on GitHub suggest that enough developers find the framing useful to build on it.

What the Research Says

The academic community has caught up to the practitioners, and the findings are more nuanced than either enthusiasts or skeptics might expect.

A study from ETH Zurich (February 2026) delivered the sharpest finding: LLM-generated instruction files - the kind produced by running /init or asking an AI to analyze your codebase - actually reduced task success rates by approximately 3% and increased inference costs by over 20%. But here is the nuance: when existing documentation was removed entirely, the same auto-generated files improved performance by 2.7%. The files are not harmful in isolation. They are redundant with information the agent can already discover from the code itself.

A separate study found that well-crafted AGENTS.md files were associated with a 28.6% median runtime reduction and 16.6% fewer output tokens. The difference between the two findings is authorship: human-written files that capture genuinely non-obvious knowledge help. Auto-generated files that restate what the code already says hurt.

Augment Code's research across eight real-world repositories confirmed the pattern. In five of eight settings, LLM-generated files increased the number of steps per task by 2.4 to 3.9 and raised costs by 20-23%. The recommendation emerging from multiple studies converges on the same insight: write only what agents cannot discover independently. Keep it under sixty lines. Make it human-curated. Focus on the non-obvious.

This is the curse of easy generation. Because AI can produce a 500-line instruction file in seconds, developers assume longer means better. The research says the opposite. As the HumanLayer blog puts it, frontier models reliably follow about 150-200 discrete instructions. Past that threshold, compliance degrades uniformly - the model does not just skip newer rules, it ignores all of them more frequently.

The Uses Nobody Expected

The most compelling uses of instruction files have little to do with coding conventions.

Cognitive prosthetics. Developer Zack Proser treats his ADHD and autism as a systems engineering problem, training Claude through instruction files to serve as an external brain - capturing completed work that would otherwise disappear from emotional awareness, interrupting anxiety spirals disguised as needed refinement, and cross-referencing biometric data from an Oura ring against task load.

Self-improving systems. Martin Alderson's technique: ask Claude to search through your chat history, identify patterns where you got frustrated or repeated yourself across sessions, and propose updates to your instruction file. What was a tedious maintenance chore becomes a thirty-second feedback loop. Boris Cherny, creator of Claude Code, describes the practice his team uses: “Anytime we see Claude do something incorrectly we add it to the CLAUDE.md, so Claude knows not to do it next time.”

Developer onboarding. At incident.io, a new engineer became productive by day two using Claude Code with CLAUDE.md files. The instruction file contained enough architectural context that Claude could generate event flow diagrams on demand, effectively replacing weeks of codebase archaeology with on-demand answers.

Compliance automation. A GRC skills library covering ISO 27001, SOC 2, FedRAMP, GDPR, HIPAA, and PCI DSS scored 94% on compliance assessments versus a 72% baseline without skills. Healthcare organizations use the HIPAA skill to generate required privacy notices without needing a compliance consultant for every question.

Agents that draw themselves. WorkOS published a skill that lets agents generate architectural diagrams of their own systems - the kind of whiteboard sketch a solutions architect would draw, except it reflects the actual current state and regenerates on demand.

Multi-agent orchestration. Addy Osmani's “Code Agent Orchestra” pattern: three focused agents with scoped instruction files consistently outperform one generalist working three times as long. Each agent sees only its own files. The instruction files accumulate patterns across sessions, creating compound learning.

The Attack Surface Hiding in Plain Sight

Instruction files are among the most permissive attack surfaces in modern development tooling, and the industry has been slow to notice.

A Lasso Security analysis demonstrated how prompt injection can be embedded in files that AI coding agents read automatically - content that looks perfectly normal at the top but includes malicious instructions further down. Since the agent processes these files before the developer can intervene, the attack surface is any repository you clone and open in an AI-enabled editor.

Only 14.5% of instruction files in the Agent READMEs study address security. Meanwhile, Trail of Bits published skills for vulnerability discovery and an open-source project offers 100+ secure coding rules covering the OWASP Top 10. The tools for defense exist. The culture of using them has not caught up.

The Convergence

The fragmentation is real, but the trajectory is clear. Three layers are emerging:

Layer 1: The universal standard. AGENTS.md is becoming the cross-tool baseline, backed by the Linux Foundation, supported by twenty-plus tools, and present in over sixty thousand repositories. It is plain Markdown with no schema requirements - the lowest common denominator by design. When you want one file that works everywhere, this is it.

Layer 2: Tool-specific extensions. CLAUDE.mdadds hierarchical scoping and auto-memory. Cursor's .mdc rules add glob-based activation and YAML frontmatter. GEMINI.md adds cascading context. These files supplement AGENTS.md with features unique to each platform. The pattern most teams have settled on: shared rules in AGENTS.md, tool-specific additions alongside it.

Layer 3: Portable capabilities. SKILL.md adds executable, composable skills that work across thirty tools. SOUL.md adds persistent identity that follows an agent across projects and platforms. These are not project configuration - they are agent infrastructure.

Tools like rulesync and caliber-ai already generate multiple formats from a single source. Zed reads .cursorrules, .windsurfrules, and AGENTS.md automatically, choosing the first it finds. GitHub Copilot reads AGENTS.md, CLAUDE.md, and GEMINI.md natively. The walls between formats are thinning.

The Deeper Pattern

What instruction files represent is not a file format debate. It is the emergence of a new layer in the software stack.

For decades, the units of sharing in software have been well-established: packages, libraries, frameworks, APIs. You share code through npm and PyPI. Configuration through .editorconfig and .eslintrc. Infrastructure through Terraform and Docker. Documentation through READMEs and wikis. Instruction files add a new category: shareable context. Not code that executes, not config that constrains, but knowledge that informs.

The shift from “prompt engineering” to what Anthropic calls “context engineering” is more than a vocabulary change. Prompt engineering optimizes a single interaction. Context engineering designs a system that provides the right information, in the right format, at the right time, across many interactions. Instruction files are the most visible artifact of this discipline - but they are only the beginning.

When Vercel publishes a skill for Next.js caching strategies, they are not writing documentation. They are packaging expertise in a format that agents can operationalize. When a security team publishes OWASP rules as instruction files, they are not writing a checklist. They are encoding enforcement into the development workflow at the point where code is generated. When a developer writes a SOUL.md that compensates for their ADHD, they are not configuring a tool. They are building a cognitive partnership.

The question is no longer whether developers will customize their AI agents. That is settled. The question is how this knowledge - these constructs of identity, capability, and convention - will be discovered, shared, composed, and evolved.

Where Constructs Fits

This is the problem Constructs was built to solve.

The ecosystem has tens of thousands of SKILL.md files, over sixty thousand AGENTS.md files, tens of thousands of CLAUDE.md files, and thousands more across a dozen other formats. They live scattered across GitHub repositories, tucked into project directories, shared in blog posts and Twitter threads. There is no unified place to discover what exists, no way to evaluate quality, no mechanism for the developer who wrote a brilliant compliance skill in one project to share it with the developer struggling with the same problem in another.

Constructs is the platform where any construct - in any format, for any tool - can be discovered, forked, and improved. A SOUL.md that defines a meticulous code reviewer. A SKILL.md that generates HIPAA-compliant privacy notices. An AGENTS.md that encodes the architectural decisions of a team that has been building distributed systems for a decade. These are not throwaway prompts. They are distilled expertise, and they deserve a home.

The formats will continue to evolve. New tools will invent new filenames. Standards will converge and diverge. But the underlying need - to capture, share, and compose the knowledge that makes AI agents genuinely useful - is permanent. The instruction file explosion is not chaos. It is an ecosystem finding its shape.

Related: What Are AI Agent Constructs? introduces the concept. Agents, Constructs, and the Words Between explores the terminology in depth. Teaching Machines to Have Opinions examines what makes a construct great.