Markdown-based Installation (MD Scripts)

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:

1. States the goal (what gets installed).
2. Lists prerequisites in prose.
3. Walks through each step with rationale, expected output, and failure modes.
4. Specifies verification ("after this step, running X should print Y").
5. 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

Ready to get to the next level?