There’s a new proposal floating around called install.md. The pitch: instead of writing installation docs for humans, write them for AI agents. Create a structured markdown file, pipe it to Claude, and let the AI install your software autonomously.

When I first saw this, my reaction wasn’t "wow, the future!" It was: "This wouldn’t exist if AI hadn’t made shipping half-baked ideas trivially easy."

Let me explain.

---

The Philosophical Problem

We’re in an era where the cost of creating things has collapsed. AI can scaffold a project in seconds. You can go from idea to deployed prototype in an afternoon. This is genuinely revolutionary.

But it also means we’re drowning in stuff. Tools, frameworks, standards, proposals. An endless stream of Things That Exist Because Someone Could Build Them, not because anyone actually needed them.

install.md feels like one of these things.

The premise is that AI agents struggle to install software because they scrape random web pages and hallucinate commands. The solution? A new file format that tells the AI exactly what to do.

But here’s my question: what are getting-started guides for?

Every decent project already has installation documentation. READMEs exist. Quickstart guides exist. If your AI can’t figure out how to run npm install my-package, the problem isn’t the absence of a special file format. The problem is your AI, or your documentation, or both.

install.md isn’t solving a documentation problem. It’s solving an "AI can’t read normal documentation" problem by creating AI-specific documentation. That’s not a standard. That’s a workaround for broken tooling.

---

The Slop Factory

Here’s what bothers me philosophically: install.md is a symptom of a larger pattern. When building is cheap, we build first and ask questions later. We create solutions and then hunt for problems to justify them.

Would anyone have proposed "a markdown file specifically for AI agents to read" in 2020? Of course not. The idea only makes sense in a world where:

1. AI agents are common enough that "installation by AI" is a real use case
2. Building and shipping a "standard" is cheap enough that it doesn’t require serious justification
3. The hype cycle rewards novelty over necessity

This is the definition of AI slop: artifacts that exist because AI made them easy to create, not because they solve genuine problems.

I’m not saying install.md is useless. I’m saying it’s suspicious. It has the shape of a solution without the substance of a problem.

---

The Redundancy Problem

Here’s my core issue with install.md: it’s a second thing to maintain that duplicates something you should already have.

Look at what an install.md file contains:

Now look at a decent getting-started guide:

They’re the same thing. The install.md just adds some AI-specific preamble ("Execute all steps autonomously") and borrows syntax from testing frameworks.

If you’re actively maintaining your install.md, you’re already doing the work of maintaining installation documentation. So why not just... maintain your getting-started guide?

The argument for install.md seems to be: "AI agents can’t understand regular documentation, so we need special documentation for them."

But is that true? Are we really assuming that models sophisticated enough to write complex software, refactor codebases, and debug production issues can’t understand a getting-started guide written for humans?

---

The DONE WHEN Syntax: Borrowed or Reinvented?

Here’s something that jumped out at me. The install.md format uses this pattern:

If you’ve worked with behavior-driven development, this looks familiar. It’s essentially Gherkin syntax with different keywords.

Gherkin, the language behind Cucumber and similar BDD frameworks, has been around since 2008:

The parallel is striking. "DONE WHEN" is just "Then" with extra words. "OBJECTIVE" is just the Scenario description.

I don’t know if the install.md authors consciously borrowed from Gherkin or reinvented it independently. But either way, it raises a question: why not just use Gherkin?

Gherkin already has:

• Decades of tooling and ecosystem
• Clear semantics that map to executable tests
• Wide industry adoption
• Parsers in every major language

If you want structured, verifiable installation steps, Gherkin already exists. You could write:

This is parseable, testable, and backed by real tooling. Why invent a new syntax when the wheel already exists?

---

What We Actually Need

If we want reliable AI-powered installation, we don’t need a new file format. We need:

1. Better Getting-Started Guides

Clear, step-by-step instructions. Code blocks that can be copied and pasted. Explicit prerequisites. Verification steps at the end.

If your getting-started guide is good, AI can follow it. If it’s bad, adding an install.md won’t help. You’ll just have two bad documents instead of one.

2. Use Existing Executable Formats

If you really want machine-parseable installation specs, use formats that already exist:

• Gherkin for behavior-driven installation verification
• Makefiles for reproducible build and install steps
• Dockerfiles for containerized, guaranteed-reproducible environments
• Shell scripts for platform-specific installation

These have tooling. They have ecosystems. They’re battle-tested.

3. Trust That Models Will Improve

The specific problems install.md solves (web scraping confusion, HTML parsing issues, outdated search results) are being actively worked on. AI agents are getting better at reading normal documentation.

Building a standard around today’s AI limitations is like designing a highway system around the constraints of the Model T. The technology is moving too fast.

4. Single Source of Truth

One well-maintained getting-started guide beats a getting-started guide plus an install.md that might drift out of sync.

Reduce documentation duplication, don’t add to it.

---

The Counter-Argument

I can hear the objections. "But AI agents need structured input! They work better with explicit formats! install.md is forward-thinking!"

Maybe. But consider: we’re in the middle of the most rapid improvement in AI capabilities in history. Models that couldn’t follow basic instructions two years ago can now write entire applications.

Are we really confident that the documentation-reading limitations of the current models will persist? That we need to build infrastructure around those limitations?

The history of AI is littered with workarounds that became unnecessary. Prompt engineering techniques that worked for GPT-3 are irrelevant for Claude 3. Context window management strategies that mattered in 2023 are quaint now that we have 200K token windows.

install.md might be solving a problem that won’t exist in eighteen months, or even six months.

Meanwhile, a good getting-started guide will always be useful. Humans will always need to install software. Clear documentation will always matter.

Bet on the timeless, not the temporary.

---

The Verdict

install.md isn’t evil. It’s not going to break anything. If you want to create one for your project, go ahead. It might help some AI agents install your software more reliably.

But let’s be honest about what it is: a workaround for AI limitations, dressed up as a standard. A solution that exists because AI made it cheap to create, not because the software world was crying out for it.

---

The install.md proposal is at installmd.org. Form your own opinion. But maybe also ask yourself: would this exist if building things wasn’t so easy now?