agent-markdown

I use coding agents as a regular part of how I think through software, data, and product questions - and more generally, using the IDE + a coding agent as my new OS for work.

Most of that collaboration between me and the coding agent happens prompts, turns, and when things get heavy, through Markdown.

It makes sense. Markdown is cheap, portable, readable in diffs, easy for agents to write, and easy for humans to skim. If I ask an agent to reason through a refactor, summarize a system, compare approaches, or explain a set of tradeoffs, Markdown is usually the right medium.

But I kept running into the same ceiling: sometimes a flat document was not enough.

I wanted an agent to make a chart from local data. Or produce a small dashboard for a question we were investigating. Or show a map, a sortable table, a Mermaid diagram, a few metrics, and a callout explaining what changed. Sometimes I wanted the document to include a lightweight form or button-like action so I could invoke a local process without turning the whole thing into an app.

These were not production experiences. They were ephemeral artifacts. Mostly for me, sometimes for teammates working in the same repo with the same local data and environment. The goal was not to deploy anything. The goal was to understand something faster.

The options I reached for were heavier than the problem.

I had agents generate HTML. That works until it does not. The context gets noisy, the output gets brittle, and suddenly I am reviewing script tags, inline styles, and weird layout code instead of the actual analysis.

I also found myself making little Streamlit apps. Streamlit is great, but it still turns a question into an application. Now there is a file to maintain, a runtime to start, dependencies to think about, and a small amount of application design that nobody really asked for.

The funny thing is that the agent did not need a full app. It needed a slightly richer vocabulary.

That is what Agent Markdown is: Markdown with a small set of opinionated interactive primitives.

Instead of asking an agent to emit a web app, I can ask it to write a .agent.md file. It can still use normal Markdown for explanation, but it can also reach for things like:

• ::chart for local CSV or JSON data.
• ::table for sortable inspection.
• ::metric for KPI-style summaries.
• ::diagram for Mermaid.
• ::map for local GeoJSON or lat/lon points.
• ::tabs for alternate views.
• ::callout for risks, notes, or decisions.
• ::embed for safe local artifacts.

The syntax is intentionally boring. That is the point.

Agents are already good at producing structured text. They do not need JSX imports, state management, build configuration, CSS strategy, or a component library just to show me a bar chart. They need a compact way to say, "render this data like this."

The implementation is local-first. Agent Markdown resolves local files from the workspace, validates the document, blocks arbitrary JavaScript and remote fetching, and renders through a browser viewer or a VSCode/Cursor preview extension. There is a CLI for validation and serving, plus project-local skills so agents know when and how to use the format.

The skill part matters. I do not want every agent conversation to start with a long explanation of the format. Running agent-md init --agent cursor installs a SKILL.md file into the project, alongside schema, config, component references, and an example. The next time an agent is working in that repo, it has a small local guide for producing valid Agent Markdown.

That changes the interaction. Instead of saying "please make an HTML dashboard," I can say something closer to "analyze this data and make an Agent Markdown report." The agent stays in a document-shaped mode, but it has more expressive tools available.

I am especially interested in that boundary: how the medium changes the agent's communication pattern.

When the only output is prose, agents tend to over-explain. When the output is a full app, they tend to over-build. A middle layer gives them another behavior: compose a small interactive artifact. Not a product. Not a notebook. Not a static note. Something closer to a local analytical object.

That feels useful for vibe coders and analysts who live inside tools like Cursor, Codex, or Claude Code. A lot of their work is exploratory. They are asking questions like:

• What changed in this dataset?
• Which files are most connected to this feature?
• Can you summarize this incident timeline?
• Can you compare these vendors?
• Can you show the metrics behind this hypothesis?
• Can you make something I can share with a teammate in this repo?

For those questions, a lightweight interactive document is often enough.

There is also a context-window reason this matters. Agents spend tokens on whatever surface you ask them to produce. If the answer is a React app, the model has to spend attention on scaffolding, imports, styling, component state, and glue code. If the answer is HTML, it spends attention on markup and browser details. With Agent Markdown, the model spends more attention on the data, the interpretation, and the structure of the communication.

That is the design bet: constrain the output medium so the agent can be more useful inside it.

This is not meant to replace notebooks, BI tools, MDX, Streamlit, or real applications. Those all have their place. If I am building a durable internal tool, I want a real app. If I am publishing polished content, MDX may be a better fit. If I am doing serious statistical work, I probably want a notebook.

Agent Markdown is for the in-between moments: local, fast, interactive, disposable, shareable enough.

I built it because I kept wanting agents to communicate with more than paragraphs, but less than software.

That space feels underexplored. As coding agents become more common collaborators, the question is not just what they can generate. It is what kinds of media we give them to think with us.

If you're interested in trying it out, check out the Agent Markdown repo, or run:

npm install @abuswami1996/agent-md
npx agent-md init --agent cursor

Then try prompts like:

• "Create an Agent Markdown report that explains this repo's architecture with diagrams, tables, and key metrics."
• "Analyze the local CSV files in this project and create a .agent.md dashboard with charts and callouts."
• "Build an Agent Markdown incident review from these logs, including a timeline, summary metrics, and risks."