Overview
Theinstall.md file uses standard Markdown with a specific structure to provide clear, actionable installation instructions. The file should be located at /install.md in the root of a project’s web presence.
Required structure
A well-formed install.md file contains these sections in order:1. Title (H1)
The name of the software being installed:2. Summary (Blockquote)
A brief description of what the software does:3. Installation instructions
Clear, sequential instructions written in natural language. Use paragraphs to organize related steps:Writing effective instructions
Be specific but flexible
Instructions should be specific enough to be actionable, but flexible enough for AI agents to adapt:Good:
Too vague:
Organize sequentially
Break complex installations into logical steps using paragraphs:Handle environment detection
Let the AI agent detect the environment rather than using explicit conditionals:Good:
Avoid:
Include prerequisites
Mention what needs to be installed or available:Provide fallback options
Give alternatives for common tools or approaches:Verify installation
Include steps to confirm successful installation:Common patterns
Binary installation
Package manager installation
Language-specific installation
Complex installation with dependencies
Best practices
Keep it concise
Aim for under 100 lines. If installation is more complex, consider whether it can be simplified.
Use natural language
Write as if you’re explaining to a colleague, not writing code.
Be explicit about URLs and paths
Include repository names, GitHub URLs, and specific paths rather than assuming they’re known.
Test with AI agents
Try your install.md file with Claude or other AI assistants to verify it produces the intended results.
Include cleanup steps
Mention removing temporary files or archives after extraction.
What to avoid
- Don’t include actual shell commands unless they’re meant to be run verbatim
- Don’t use overly technical jargon without explanation
- Don’t assume specific shell (bash, zsh, fish) unless necessary
- Don’t include version numbers unless you want to pin to that specific version
- Don’t combine unrelated operations in a single instruction