Markdown Is Code

markdownagentsskillsai

Markdown was designed to be read by humans. A lightweight syntax that looked good as plain text and rendered cleanly as HTML. That was the whole point.

Somewhere along the way it became something else.

Markdown as agent skills

Claude Code defines skills as .md files. A markdown file describes what an agent should do, when it should do it, and how it should behave. The agent reads the file and follows it.

---
name: debugging
description: Use when encountering any bug or test failure
---
 
## Process
 
1. Reproduce the issue
2. Identify root cause before proposing fixes
3. Write a failing test
4. Fix the issue
5. Verify the test passes

That is a skill definition. Not YAML. Not JSON. Not a DSL. Markdown.

The agent parses the frontmatter to know when the skill applies. It reads the body to know what to do. The format is human readable and machine executable at the same time.

This pattern is showing up everywhere.

  • Claude Code skills define agent behaviors as .md files with frontmatter metadata.
  • CLAUDE.md configures project level agent behavior. Coding standards, test commands, architectural constraints. All in a markdown file at the root of a repo.
  • Cursor rules work the same way. A markdown file tells the agent how to behave in a specific project.
  • Agent Format from Snap uses YAML, but the principle is identical. Declarative, readable definitions that machines parse and execute.

The document is the program.

Why markdown works for this

Programming languages optimize for machines. Documentation optimizes for humans. Markdown sits in the middle.

  • It is structured enough for agents to parse reliably.
  • It is readable enough for humans to write and review without training.
  • It supports frontmatter for metadata without a separate config file.
  • It is portable. No build step, no compiler, no runtime.

When you define an agent skill in Python, only developers can modify it. When you define it in markdown, anyone who can write a document can shape how an agent behaves.

That distinction matters. The people closest to a workflow are often not engineers. Product managers know the process. Domain experts know the edge cases. Markdown lets them define agent behavior directly instead of writing a spec and waiting for someone to implement it.

What exists today

Right now agent skills are fragmented.

  • Claude Code has its skill format with frontmatter and markdown body.
  • Cursor has its rules format.
  • Custom agent frameworks define skills in Python, YAML, or JSON.
  • Each tool reads a different file in a different way.

The skill works inside one tool. Move to another tool and you start over. There is no portability.

CLAUDE.md is the closest thing to a shared pattern. A single file that defines how an agent should behave in a project. But it only works with Claude. A CLAUDE.md sitting in a repo is invisible to every other agent framework.

Where this could go

If markdown is becoming the programming language for agent skills, a few things follow naturally.

  • A standard skill format. Frontmatter defines when and where a skill applies. The body defines what to do. If the format is shared across tools, a skill written for one agent works with another.

  • Skill discovery. If skills are files with structured metadata, they can be indexed. A registry could match agents to skills the same way a package manager matches projects to dependencies.

  • Composable skills. A debugging skill that references a test runner skill. A code review skill that invokes a style checker. Markdown files that import behavior from other markdown files.

  • Version controlled behavior. Agent behavior defined in markdown lives in git. It gets reviewed in pull requests. It has a commit history. Changes are auditable. Rolling back a behavior change is a git revert.

  • Non-engineer authorship. A support team lead defines an escalation skill. A security engineer defines a vulnerability scanning workflow. The people who understand the process write the skill directly.

The shift

The interesting part is not that markdown can do this. It is that markdown might be the right format for this. Not because it is powerful, but because it is simple enough that both humans and agents can work with it without friction.

Code is becoming more declarative. Documents are becoming more executable. Markdown is where those two trends meet.