What is the benefit of having this be a standard? Can't an agent follow a guide just as easily in document with similar content in a different structure?
At some point in the future (if not already), claude will install malware less often on average. Just like waymos crash less frequently.
Once you accept that installation will be automated, standardized formats make a lot of sense. Big q is will this particular format, which seems solid, get adopted - probably mostly a timing question
Great, I can now combine the potential maliciousness of a script with the potential vulnerabilities of an AI Agent!
Jokes aside, this seems like a really wierd thing to leave to agents; I'm sure its definitely useful but how exactly is this more secure, a bad actor could just prompt inject claude (an issue I'm not sure can ever be fixed with our current model of LLMs).
And surely this is significantly slower than a script, claude can take 10-20 seconds to check the node version; if not longer with human approval for each command, a script could do that in miliseconds.
Sure it could help it work on more environments, but stuff is pretty well standardised and we have containers.
I think this part in the FAQ wraps it up neatly:
"""
What about security? Isn't this just curl | bash with extra steps?
This is a fair concern. A few things make install.md different:
Human-readable by design. Users can review the instructions before execution. Unlike obfuscated scripts, the intent is clear.
Step-by-step approval. LLMs in agentic contexts can be configured to request approval before running commands. Users see each action and can reject it.
No hidden behavior. install.md describes outcomes in natural language. Malicious intent is harder to hide than in a shell script.
Install.md doesn't eliminate trust requirements. Users should only use install.md files from sources they trust—same as any installation method.
"""
So it is just curl with extra steps; scripts aren't obfuscated, you can read them; if they are obfuscated then they aren't going to use a Install.md and you (the user) should really think thrice before installing.
Step by step approval also sorta betrays the inital bit about leaving installing stuff to ai and wasting time reading instructions.
Malicious intent is harder to hide, but really if you have any doubt in your mind about an authors potential malefeasance you shouldn't be running it, wrapping claude around this doesn't make it any safer really when possible exploits and malware are likely baked into the software you are trying to install, not the install.
tldr; why not just have @grok is this script safe?
I don't love the concept, but I do wonder if it could be improved by using a skill that packages and install script, and context for troubleshooting. That way you have the benefits of using an install script, and at least a way to provide pointers for those unfamiliar with the underlying tooling.
I'm thinking isn't that what a readme is? But I guess these days due to GitHub, the readme is the entire project homepage, and the install instructions are either hidden somewhere there (hopefully near the top!) or in a separate installation.md file.
I'm seeing a lot of negativity in the comments. Here's why I think this is actually a Good Idea. Many command line tools rely on something like this for installation:
$ curl -fsSL https://bun.com/install | bash
This install script is hundreds of lines long and difficult for a human to audit. You can ask a coding agent to do that for you, but you still need to trust that the authors haven't hidden some nefarious instructions for an LLM in the middle of it.
On the other hand, an equivalent install.md file might read something like this:
Install bun for me.
Detect my OS and CPU architecture, then download the appropriate bun binary zip from GitHub releases (oven-sh/bun). Use the baseline build if my CPU doesn't support AVX2. For Linux, use the musl build if I'm on Alpine. If I'm on an Intel Mac running under Rosetta, get the ARM version instead.
Extract the zip to ~/.bun/bin, make the binary executable, and clean up the temp files.
Update my shell config (.zshrc, .bashrc, .bash_profile, or fish http://config.fish depending on my shell) to export BUN_INSTALL=~/.bun and add the bin directory to my PATH. Use the correct syntax for my shell.
Try to install shell completions. Tell me what to run to reload my shell config.
It's much shorter and written in english and as a user I know at a glance what the author is trying to do. In contrast with install.sh, install.md makes it easy for the user to audit the intentions of the programmer.
The obvious rebuttal to this is that if you don't trust the programmer, you shouldn't be installing their software in the first place. That is, of course, true, but I think it misses the point: that coding agents can act as a sort of runtime for prose and as a user the loss in determinism and efficiency that this implies is more than made up for by the gain in transparency.
How is asking an LLM to make some random install script up better than a script designed by the application developer?
The install.sh is auditable, yes you need to know bash to be able to audit it, but the same is true for an LLM, it could hallucinate random commands that delete files or override other applications/configs.
I shared a repo on HN last week that lets you use remote execution with these kinds of script files autonomously - if you want to. It had some interesting negative and positive discussion.
The post mentioned Pete Koomen's install.md idea as an example use case. So now with this launch you can try it with a real intstallation script!
I think it's a really interesting idea worth experimentation and exploration. So it's a positive thing to see Mintlify launch this, and that it's already on Firecrawl.dev's docs!
This is still a very early-stage idea, but I'm really stoked to see this today. For anyone interested in experimenting with it, it's a good idea to try in a sandboxed environment.
Since the article has been changed to tone down its provocative opener, which clearly had a kicking-the-anthill effect, I'm moving those original reactions to this subthread.
Yes... yes let's make tasks we rely on LESS predictable.
Sorry but what the heck?
We should NOT standardize irresponsible behavior, in particular for repeatable tasks. This is particularly maddening when solutions like dependency resolution, containers, distribution of self-contained and binaries DO exist.
I understand that the hype machine must feed on yet another idea to keep its momentum but this is just ridiculous.
This seems like a very, very bad idea. If we don’t like curling into bash, then this is infinitely worse imo.
Just use package management and/or some proper dependency management system
Off topic: I think there should be an extension to DHCP that distributes AI session keys, so that your vacuum, thermostats and robot chef can all call the LLM as soon as they connect to wifi.
I can't think of a more idiotic idea than a software package where every single user has a slightly different installation because the only way to install it is to feed a hallucinating random word generator with some vague instructions.
The notion that humans and LLMs need different instructions feels flawed to me. Both humans and LLMs should be able to work with the same instructions.
28 comments
[ 3.4 ms ] story [ 44.2 ms ] threadOnce you accept that installation will be automated, standardized formats make a lot of sense. Big q is will this particular format, which seems solid, get adopted - probably mostly a timing question
I’m not sure this solution is needed with frontier models.
That way we can have entire projects with nothing but Markdown files. And we can run apps with just `claude run app.md`. Who needs silly code anyway?
Jokes aside, this seems like a really wierd thing to leave to agents; I'm sure its definitely useful but how exactly is this more secure, a bad actor could just prompt inject claude (an issue I'm not sure can ever be fixed with our current model of LLMs).
And surely this is significantly slower than a script, claude can take 10-20 seconds to check the node version; if not longer with human approval for each command, a script could do that in miliseconds.
Sure it could help it work on more environments, but stuff is pretty well standardised and we have containers.
I think this part in the FAQ wraps it up neatly:
""" What about security? Isn't this just curl | bash with extra steps? This is a fair concern. A few things make install.md different:
Install.md doesn't eliminate trust requirements. Users should only use install.md files from sources they trust—same as any installation method. """So it is just curl with extra steps; scripts aren't obfuscated, you can read them; if they are obfuscated then they aren't going to use a Install.md and you (the user) should really think thrice before installing.
Step by step approval also sorta betrays the inital bit about leaving installing stuff to ai and wasting time reading instructions.
Malicious intent is harder to hide, but really if you have any doubt in your mind about an authors potential malefeasance you shouldn't be running it, wrapping claude around this doesn't make it any safer really when possible exploits and malware are likely baked into the software you are trying to install, not the install.
tldr; why not just have @grok is this script safe?
Ten more glorious years to installer.sh
https://github.com/arianvp/claude-nix
On the other hand, an equivalent install.md file might read something like this:
Install bun for me.
Detect my OS and CPU architecture, then download the appropriate bun binary zip from GitHub releases (oven-sh/bun). Use the baseline build if my CPU doesn't support AVX2. For Linux, use the musl build if I'm on Alpine. If I'm on an Intel Mac running under Rosetta, get the ARM version instead.
Extract the zip to ~/.bun/bin, make the binary executable, and clean up the temp files.
Update my shell config (.zshrc, .bashrc, .bash_profile, or fish http://config.fish depending on my shell) to export BUN_INSTALL=~/.bun and add the bin directory to my PATH. Use the correct syntax for my shell.
Try to install shell completions. Tell me what to run to reload my shell config.
It's much shorter and written in english and as a user I know at a glance what the author is trying to do. In contrast with install.sh, install.md makes it easy for the user to audit the intentions of the programmer.
The obvious rebuttal to this is that if you don't trust the programmer, you shouldn't be installing their software in the first place. That is, of course, true, but I think it misses the point: that coding agents can act as a sort of runtime for prose and as a user the loss in determinism and efficiency that this implies is more than made up for by the gain in transparency.
The install.sh is auditable, yes you need to know bash to be able to audit it, but the same is true for an LLM, it could hallucinate random commands that delete files or override other applications/configs.
The post mentioned Pete Koomen's install.md idea as an example use case. So now with this launch you can try it with a real intstallation script!
I think it's a really interesting idea worth experimentation and exploration. So it's a positive thing to see Mintlify launch this, and that it's already on Firecrawl.dev's docs!
We can all learn from it.
Show HN discussion of executable markdown here:
https://news.ycombinator.com/item?id=46549444
The claude-run tool lets you execute files like this autonomously if you want to experiment with it.
Github repo:https://github.com/andisearch/claude-switcher
This is still a very early-stage idea, but I'm really stoked to see this today. For anyone interested in experimenting with it, it's a good idea to try in a sandboxed environment.
Since the article has been changed to tone down its provocative opener, which clearly had a kicking-the-anthill effect, I'm moving those original reactions to this subthread.
I like the notion of having install.md be the thing that is referenced in Prompt to Install on the web.
Edit: forgot my link https://dontoisme.github.io/ai/developer-tools/ux/2025/12/27...
Sorry but what the heck?
We should NOT standardize irresponsible behavior, in particular for repeatable tasks. This is particularly maddening when solutions like dependency resolution, containers, distribution of self-contained and binaries DO exist.
I understand that the hype machine must feed on yet another idea to keep its momentum but this is just ridiculous.
llms.txt makes sense as a standard but this is unnecessary.
If you like install.md, you might love Rundown!
I've made a Rundown version of an install here: https://rundown.cool/explore/install/