Markdown-based Installation (MD Scripts)
Markdown-based installation replaces shell scripts (`install.sh`) with prose installation procedures (`install.md`) that an LLM) reads and executes against the local environment. Instead of writing brittle Bash that branches on OS, package manager, shell version, and existing state, you write the in
Canonical version: Markdown-based Installation (MD Scripts).
Markdown-based installation replaces shell scripts (install.sh) with prose installation procedures (install.md) that an LLM reads and executes against the local environment. Instead of writing brittle Bash that branches on OS, package manager, shell version, and existing state, you write the installation in plain English and tell the user: "show this to your LLM".
The idea was articulated by Andrej Karpathy as one of the new affordances unlocked by LLM-native tooling. The LLM is an advanced interpreter of English, capable of intelligent targeting and inline debugging.
Why MD Scripts Beat Shell Scripts
Shell scripts encode a single execution path; MD scripts encode intent.
- Adapts to the local setup: detects the OS, installed package managers, available shells, existing config, and adjusts steps accordingly.
- Debugs inline: when a step fails, the LLM reads the error, diagnoses the cause, and proposes a fix without escalating to the maintainer.
- Self-documenting: the README is the script. No drift between docs and behavior.
- Smaller surface to maintain: one MD file instead of an
install.sh+install.ps1+ Dockerfile + Brewfile matrix. - User-controlled: the user reviews each step before execution, so the LLM is a co-pilot, not an opaque automation.
Format
A typical MD script:
- States the goal (what gets installed).
- Lists prerequisites in prose.
- Walks through each step with rationale, expected output, and failure modes.
- Specifies verification ("after this step, running
Xshould printY"). - Gives uninstall instructions.
The LLM treats this as a contract: read, plan, ask the user for confirmation on destructive steps, execute, verify, recover.
Tradeoffs
- Non-determinism: two LLM runs may take different paths; reproducibility weakens.
- Trust: the user must trust the LLM to interpret prose correctly, especially for security-sensitive steps.
- Cost: every install costs tokens.
- Capability gating: only works if the user has access to a capable enough LLM that can drive a shell (Claude Code, AI Agent Harness).
Variants
- Pure MD: prose only.
- Hybrid: prose with embedded shell snippets the LLM can choose to use verbatim or adapt.
- Skill-based: the install MD is itself a skill in the LLM's skill registry, invoked by capability rather than file path.
Related
- Andrej Karpathy
- Large Language Models (LLMs)
- Menugen Architecture Pattern
- LLM Knowledge Bases Over Unstructured Data
- Agentic Engineering
- AI Agent Harness
- Claude Code
- Prompt-driven development (PDD)
- AI Verifiability as a Capability Ceiling
About Sébastien
I'm Sébastien Dubois, and I'm on a mission to help knowledge workers escape information overload. After 20+ years in IT and seeing too many brilliant minds drowning in digital chaos, I've decided to help people build systems that actually work. Through the Knowii Community, my courses, products & services and my Website/Newsletter, I share practical and battle-tested systems.
I write about Knowledge Work, Personal Knowledge Management, Note-taking, Lifelong Learning, Personal Organization, Productivity, and more. I also craft lovely digital products and tools.
If you want to follow my work, then become a member and join our community.
Ready to get to the next level?
If you're tired of information overwhelm and ready to build a reliable knowledge system:
- 📚 KM for Beginners — 10+ hours of structured video lessons
- 🚀 Obsidian Starter Kit — Ready-made vault with 40+ templates
- 💼 Knowledge Worker Kit — Complete guides + lifetime community
- 🦉 1-on-1 Coaching — Personalized guidance
- 🎯 Join Knowii — Community + ALL courses & tools
Found this valuable? Share it with someone who needs it.