Your Markdown Files Are Now Executable AI Agents

Meeting Developers Where They Are

Talk Duration: 15-20 minutes (including demos)
Perspective: Developer Experience Advocate
Event: Microsoft AI Dev Days

---

Hook (1 minute)

"Raise your hand if you've written markdown today."

[Wait for hands]

"Keep it up if you've written YAML."

[Most hands stay up]

"Now—how many of you have written a prompt for an AI?"

[Almost everyone]

"What if I told you those three skills you already have ARE the skills for building AI agents?"

The Shift: We're not learning a new paradigm. We're recognizing that the tools we love—markdown, YAML, CLI—were always the right abstraction for AI.

---

Section 1: The Familiar Made Powerful (3 minutes)

Key Point: Markdown as Universal Developer Language

• We already document in markdown (READMEs, wikis, docs)
• We already configure with YAML (Jekyll, Hugo, GitHub Actions, Kubernetes)
• We already automate with CLI (npm scripts, shell, pipelines)

The Revelation

# review.claude.md
---
model: opus
---
Review this code for bugs and suggest improvements.

@./src/**/*.ts

That's it. That's an AI agent.

Demo Idea #1: "Your First Agent in 30 Seconds"

• Create hello.copilot.md live
• Show it runs with ma hello.copilot.md
• Point out: no SDK, no API keys in code, no boilerplate

---

Section 2: YAML Frontmatter — Config You Already Know (3 minutes)

Key Point: Every Key Becomes a Flag

---
command: claude
model: opus
dangerously-skip-permissions: true
add-dir:
  - ./src
  - ./tests
---

Becomes:

claude --model opus --dangerously-skip-permissions --add-dir ./src --add-dir ./tests

The Developer-Friendly Design

Pattern	Source	Now Powers
Frontmatter	Jekyll/Hugo (2008+)	AI config
Key-value → flags	Every CLI ever	AI behavior
Arrays → repeated flags	Docker Compose	Multi-input

Demo Idea #2: "From Jekyll to AI Agent"

Show side-by-side:

# blog-post.md (Jekyll)     # review.claude.md (Agent)
---                          ---
layout: post                 command: claude
title: "Hello"               model: opus
tags: [dev, ai]             add-dir: [./src, ./lib]
---                          ---

Same pattern. Different power.

---

Section 3: CLI as Native Habitat (4 minutes)

Key Point: Pipes, Chains, and Composition

The Unix philosophy applies perfectly to AI:

• Small, focused agents that do one thing well
• Stdin/stdout for data flow
• Pipes for composition

Real-World Patterns

# Pipe git diff into a review agent
git diff | ma review.claude.md

# Chain agents together
ma plan.claude.md | ma implement.codex.md

# Use in existing scripts
if ma lint-check.copilot.md --exit-code; then
  echo "Code looks good!"
fi

Demo Idea #3: "The Git Workflow"

Live demo of a real workflow:

# 1. Stage changes
git add .

# 2. Get AI-powered commit message
git diff --staged | ma commit.copilot.md

# 3. Review before commit
git diff --staged | ma review.claude.md

# 4. If good, commit

Show how markdown agents slot into existing git workflows without changing habits.

---

Section 4: Low Floor, High Ceiling (3 minutes)

Key Point: Progressive Complexity

Day 1 Developer:

# explain.copilot.md
Explain this code simply.

Week 2 Developer:

# explain.copilot.md
---
model: gpt-4.1
$1: prompt
---
Explain this code simply.

Month 2 Developer:

# smart-explain.claude.md
---
model: sonnet
inputs:
  - name: level
    type: select
    message: "Explanation depth?"
    choices: ["beginner", "intermediate", "expert"]
---
Explain this code for a {{ level }} developer.

Context from codebase:
@./src/**/*.ts

Related documentation:
@./docs/architecture.md

The Power Features (For When You're Ready)

• @./path — Import files inline
• @./src/**/*.ts — Glob patterns
• @./file.ts:10-50 — Line ranges
• @./file.ts#InterfaceName — Symbol extraction
• !`git log -5` — Command output inline
• LiquidJS templates — Full template logic

Demo Idea #4: "Escalation Pattern"

# Start with fast/cheap agent
result=$(ma quick-check.copilot.md)

# Escalate to smarter agent if needed
if echo "$result" | grep -q "NEEDS_REVIEW"; then
  ma deep-review.claude.md
fi

Show intelligent scripts that know when to ask for help.

---

Section 5: Version Control Friendly (2 minutes)

Key Point: Instructions Are Just Files

The old way:

• AI prompts in databases
• Config in dashboards
• "Where did that prompt go?"

The markdown-agent way:

• Prompts in ./agents/ directory
• Git history for every change
• PR reviews for prompt changes
• Branch-specific agents

Real Team Workflow

~/company-agents/
├── review.claude.md       # Code review (everyone)
├── commit.copilot.md      # Commit messages (shared)
├── security-audit.claude.md # Security (ops team)
└── .env.local             # API keys (gitignored)

export PATH="$HOME/company-agents:$PATH"
# Now everyone on the team has the same agents

Demo Idea #5: "Git Blame Your Prompts"

git log --oneline agents/review.claude.md
git blame agents/review.claude.md

Show who changed what, when, and why—just like code.

---

Section 6: The Copilot Focus (2 minutes)

Key Point: GitHub Copilot CLI in Non-Interactive Mode

# task.copilot.md
---
model: gpt-4.1
$1: prompt
silent: true
---
Analyze this error and suggest a fix.

Piping Results for Automation

# Get structured output
ma analyze.copilot.md < error.log | jq '.suggestions[]'

# Use in CI/CD
ma security-check.copilot.md | tee report.md

Why This Matters

• Copilot is already in your toolchain
• Non-interactive mode enables automation
• Same agent files work with Claude, Codex, Gemini
• Swap models by changing one line

---

Closing: The New Stack (2 minutes)

The Shift in Perspective

Old Mental Model:

"I need to learn this AI framework's API, SDK, patterns..."

New Mental Model:

"I already know markdown. I already know YAML. I already know CLI. I'm ready."

The Three Truths

1. Software is now instructions + tools (not just code)
2. The barrier to AI automation is zero (if you know markdown)
3. Your existing skills transfer directly (no new paradigm)

Call to Action

npm install -g markdown-agent
ma --setup

# Your first agent
echo '---
command: copilot
---
Say hello!' > hello.copilot.md

ma hello.copilot.md

"You've been writing AI agent config your whole career. You just called them blog posts and CI pipelines."

"Now go make them intelligent."

---

Memorable Closing Line

"The best developer tools don't ask you to learn something new. They reveal that you already knew it all along. Markdown agents are what happens when we stop fighting developers and start meeting them where they live—in the terminal, in text files, in the tools they love."

---

Resources

• GitHub: github.com/johnlindquist/agents
• Install: npm install -g markdown-agent
• Docs: Project README

---

Demo Checklist

• Terminal with large font, dark theme
• Pre-create a few example agents (but type at least one live)
• Have a real codebase ready for @./src/**/*.ts demo
• Git repo with staged changes for commit message demo
• Copilot CLI authenticated and ready
• Claude CLI as backup/escalation demo
• .env file with API keys ready

---

Timing Summary

Section	Time	Running Total
Hook	1 min	1 min
Familiar Made Powerful	3 min	4 min
YAML Frontmatter	3 min	7 min
CLI as Native Habitat	4 min	11 min
Low Floor, High Ceiling	3 min	14 min
Version Control Friendly	2 min	16 min
Copilot Focus	2 min	18 min
Closing	2 min	20 min

Buffer: 2-3 minutes for demos running over or audience questions during.