Install Md

install-md

Open @references/guide.md and follow it. Do not proceed without it.

Create install.md files that AI agents can execute autonomously. The output enables agents to install software without human intervention.

The guide contains:

• Spec requirements for autonomous execution
• Drafting process with validation gates
• 12 eval checks with pass criteria
• Failure modes from real-world friction

install.md Guide

Create install.md files that AI agents can execute autonomously. Every output must enable an agent to install software without human clarification.

---

Spec

An install.md optimized for autonomous agent execution has this structure:

I want you to install [Product] for me. Execute all steps autonomously.

OBJECTIVE: [Single sentence describing what will be installed]

DONE WHEN: [Runnable check command with default fallbacks for any env vars]

## TODO

- [ ] [Step 1 description]
- [ ] [Step 2 description]
- [ ] [Step 3 description]
(3-7 items)

## Step 0: [Prerequisites] (optional)

[Dependency check command]

**Verify:**
[Check command]
[Expected output hint]

## Step 1: [Action]

...

EXECUTE NOW: Start with Step 0. Mark TODO items complete as you go. Stop when [restate DONE WHEN condition].

---

## Optional: [Additional Content]
(Optional sections allowed after EXECUTE NOW separator)

Spec Rules

---

Process

1. Analyze

Gather these facts before drafting:

• Product name (exact)
• Target OS(s)
• Install method (curl | bash, brew, npm, etc.)
• Success signals (version command, status command)
• Auth steps (if any)
• Dependencies (if any)

2. Draft Skeleton

Enforce exact order: 1. Opening request line 2. OBJECTIVE: line 3. DONE WHEN: line 4. ## TODO section 5. Steps with verify blocks 6. EXECUTE NOW: closing

3. Author Steps

For each step:

• One command block
• One verify block with expected output hint
• No optional variations inline (put in separate section if needed)

4. Clean Content

Remove:

• Troubleshooting sections
• "If you see an error" blocks
• Optional configuration
• HTML tags
• Marketing language

Keep:

• Commands
• Verify blocks
• Expected output hints

5. Tune Word Count

Target: 400-800 words

If under 400:

• Add expected output hints
• Add verify blocks for missing steps
• Add dependency checks

If over 800:

• Remove optional steps
• Consolidate agent variants
• Remove explanatory prose

6. Validate

Run all 12 eval checks. Fix failures before shipping.

---

Eval Checks

# Run from directory containing install.md
FILE="install.md"

echo "1) Has opening request (first line):"
head -1 "$FILE" | grep -qi "I want you to install" && echo "PASS" || echo "FAIL"

echo "2) Has OBJECTIVE:"
grep -q "^OBJECTIVE:" "$FILE" && echo "PASS" || echo "FAIL"

echo "3) Has DONE WHEN:"
grep -q "^DONE WHEN:" "$FILE" && echo "PASS" || echo "FAIL"

echo "4) Has TODO section:"
grep -q "^## TODO" "$FILE" && echo "PASS" || echo "FAIL"

echo "5) TODO has 3-7 items:"
COUNT=$(grep -c "^- \[ \]" "$FILE")
[ "$COUNT" -ge 3 ] && [ "$COUNT" -le 7 ] && echo "PASS ($COUNT items)" || echo "FAIL ($COUNT items)"

echo "6) Word count in range (400-800):"
WC=$(wc -w < "$FILE")
[ "$WC" -ge 400 ] && [ "$WC" -le 800 ] && echo "PASS ($WC words)" || echo "FAIL ($WC words)"

echo "7) No HTML tags:"
grep -qE "<[a-z]+" "$FILE" && echo "FAIL" || echo "PASS"

echo "8) Has EXECUTE NOW:"
grep -q "^EXECUTE NOW:" "$FILE" && echo "PASS" || echo "FAIL"

echo "9) No troubleshooting:"
grep -qi "troubleshoot" "$FILE" && echo "FAIL" || echo "PASS"

echo "10) Each Step has Verify (main flow only):"
# Count steps and verifies before EXECUTE NOW (main flow)
MAIN_FLOW=$(sed '/^EXECUTE NOW:/q' "$FILE")
STEPS=$(echo "$MAIN_FLOW" | grep -c "^## Step")
VERIFIES=$(echo "$MAIN_FLOW" | grep -c "^\*\*Verify:\*\*")
[ "$STEPS" -eq "$VERIFIES" ] && echo "PASS ($STEPS steps, $VERIFIES verifies)" || echo "FAIL ($STEPS steps, $VERIFIES verifies)"

echo "11) Env vars have defaults:"
# Check for $VAR patterns that don't use ${VAR:-default} syntax (including end-of-line)
if grep -E '\$[A-Z_]+($|[^}:-])' "$FILE" | grep -qv ':-'; then
  echo "WARN: Check env vars manually"
else
  echo "PASS"
fi

echo "12) EXECUTE NOW restates DONE WHEN:"
echo "Manual check - compare:"
grep "^DONE WHEN:" "$FILE"
grep "^EXECUTE NOW:" "$FILE"

---

Failure Modes

---

Exemplars

Study before starting:

• ~/Work/basecamp/bcq/INSTALL.md (Target 1 - co-developed with this skill)

---

Self-Eval Checks

This skill must pass skill-crafting criteria.

---

Quick Start

1. Analyze target software 2. Draft skeleton in exact spec order 3. Author steps with verify blocks 4. Remove troubleshooting and optional content 5. Tune to 400-800 words 6. Run all 12 eval checks 7. Fix failures and re-check

install.md Spec

Template

I want you to install [Product] for me. Execute all steps autonomously.

OBJECTIVE: [What will be installed - single sentence]

DONE WHEN: [Runnable check command with ${VAR:-default} for any env vars]

## TODO

- [ ] [Step 0 - prerequisites]
- [ ] [Step 1]
- [ ] [Step 2]

## Step 0: [Prerequisites] (optional, for dependency checks)

[command]

**Verify:**

[check command]

Expected: [output hint]

## Step 1: [Action]

...

EXECUTE NOW: Start with Step 0. Mark TODO items complete as you go. Stop when [same DONE WHEN command].

---

## Optional: [Additional Content]
(Agent variants, updating instructions, etc.)

Rules

Anti-Patterns

• ## Objective (use OBJECTIVE:)
• ## Completion Criteria (use DONE WHEN:)
• If you see an error... (no troubleshooting in main flow)
• <table> or other HTML
• More than 7 TODO items
• Missing verify blocks
• Vague success criteria ("installed successfully")
• $VAR without default (use ${VAR:-default})
• Extra sections before EXECUTE NOW (move to Optional)
• Multiple variants in one step (use Optional section)