agentsmd
Markdown is the wrong format for agent rules
I realize this is a major spanner in your branding - but most people already know the many reasons why a richer and more-structured input must be used for prompt engineering, and openai themselves recently announced this.
If you want humans to be able to read it - sure - markdown. If you want an LLM to reliably understand it, along with all the nuances of priority, recursive embedding, unambiguous references, nested steps, and so forth - do not use markdown.
Bonus - if you switched to HTML/XML for this instead of markdown - the very fact you've got .md in your name, and do not use .md, would cement your leadership in this space in everyone's minds - that's the kind of strangeness that people remember. and being bold enough to offer the correct advice will definitely earn you respect!!
If you want to properly fix the total SNAFU that is the current state of LLM input/output/and rule-following - reach out. Designing a solution for this is urgently needed, and some incredibly elegant ones are still possible - "you can't put markdown inside markdown" is all the clue you need about why something has to evolve here !!!
<!DOCTYPE html>
<html xmlns="https://agents.md/sds">
<head>
<title>Self-Documenting Schema (SDS) Comprehensive Documentation</title>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" href="sds.css">
<script src="sds.js" defer></script>
</head>
<body>
<section class="metadata">
<h2>Metadata</h2>
<dl>
<dt>Version:</dt>
<dd>1.0.0</dd>
<dt>Timestamp:</dt>
<dd>2025-03-10T12:00:00Z</dd>
<dt>Purpose:</dt>
<dd>
<p>This document serves as the comprehensive specification and documentation for the Self-Documenting Schema (SDS) format.</p>
<p>It defines the structure, usage patterns, and capabilities of SDS across all OpenAI components and AI interactions.</p>
<p>This document <i>is</i> also sds.</p>
</dd>
<dt>Status:</dt>
<dd>Active</dd>
<dt>Related_Documents:</dt>
<dd>
<ul>
<li><a href="sds_reasoning_types.html">AI Reasoning Types Framework</a> - Detailed specification of AI reasoning capabilities</li>
</ul>
</dd>
</dl>
</section>
<section class="explanation">
<h2>SDS Overview</h2>
<dl>
<dt>What is SDS?</dt>
<dd>
<p>The Self-Documenting Schema (SDS) is a structured, human-readable, and machine-interpretable format designed for:</p>
<ol>
<li>AI-Human Communication</li>
<li>AI-AI Communication</li>
<li>Component Interfaces</li>
<li>System Documentation</li>
<li>Data Streaming</li>
<li>Rule Definition</li>
</ol>
<p>Key characteristics:</p>
<ul>
<li>Based on valid HTML5</li>
<li>Self-describing and self-validating</li>
<li>Supports both structured and streaming data</li>
<li>Human-readable in standard web browsers (you are reading sds right now!)</li>
<li>Machine-parseable with standard XML tools</li>
</ul>
</dd>
</dl>
</section>
... and so forth: pm if interested.
This is somewhat similar to Microsoft's POML (Prompt Orchestration Markup Language).
link: https://github.com/microsoft/poml
I would be very much curious to here, what the guys here https://github.com/eyaltoledano/claude-task-master have to say about this, as they have been working on vastly superior and comprehensive task management system
Markdown works!
It might not be as good as other formats (xml etc.) but it's the best format that both humans and AI agents can easily collaborate with. I think the goal of AGENTS.md is to allow any dev to add additional context to their repo in the easiest possible way. In many cases the README.md is already good enough but it is common practice to add specific instructions for AI agents.
Plus, in the future, models might get better at parsing markdown as this becomes more of a standard.
Source: backlog.md
In addition to what @MrLesk said, the proposed xml is wasteful. A combination of simple xml tags, with markdown inside is fair - I believe Anthropic is using that.
@MrLesk @OriNachum - you misunderstood the point of repo - it is NOT for humans
Markdown works!
No it does not - not for ChatGPT - not well enough - and definitely not well enough to base a rules standard on!!!
There's dozens of reasons why markdown should never be used for serious rules (I already listed some - did you understand my post?); if you've not encountered the problems yet, you're probably not doing anything that requires serious rule adherence (like code, structur4ed output, or even rules themselves).
Your response lacks of respect and is condescending.
This is a public medium - please act accordingly.
With that said, I am responsible for a lot of projects running in production with 100% success rate and working over long time.
Some of the agents use pretty long prompts, and chain multiple agents.
Your assumptions are incorrect, though, I believe you to have experienced problems working with AI.
I have over 10 markdown instruction documents, I write spec for most of my features and have different documentation and stuff amd each sometimes takes me a whole night to craft out nicely and then I keep adding in any stuff I missed, markdown really works, humans can read it and agents can still just see it as text, after all, you not going to write code in rules files are you? not to great extent, and the rules is human made not LLM slop so it gotta be good to both humans and LLMs, for code snippets or anything of sorts, xml can be embedded in markdown, so can html.
Any instruction good or bad is only as good as its quality, markdown or xml won't save you on bad instructions. I think markdown with xml pieces in is the best combo, am not writing xml completely for rather something that is basically documenting stuff.
I have over 10 markdown instruction documents... So you're new to this.
You can't put markdown in markdown.
You can't pout anything else (xml/html/etc) in markdown either, if that "else" contains markdown...
You need to read and understand the OP - " the nuances of priority, recursive embedding, unambiguous references, nested steps " - otherwise you're wasting everyone's time because you have not learned this lesson yet.
If you think it's working for you today, you're either not doing anything important enough yet, or have not realized that it's not working properly for you yet.
Context is everything. markdown simply doesn't offer the power you need to give an AI the correct context. If you want to compromise so you can more-easily read it yourself - fine - but this agents.md concept is for AGENTS - so it makes MORE sense to do what's best for THEM, rather than compromise...
I have over 10 markdown instruction documents... So you're new to this.
You can't put markdown in markdown.
You can't pout anything else (xml/html/etc) in markdown either, if that "else" contains markdown...
You need to read and understand the OP - " the nuances of priority, recursive embedding, unambiguous references, nested steps " - otherwise you're wasting everyone's time because you have not learned this lesson yet.
If you think it's working for you today, you're either not doing anything important enough yet, or have not realized that it's not working properly for you yet.
Context is everything. markdown simply doesn't offer the power you need to give an AI the correct context. If you want to compromise so you can more-easily read it yourself - fine - but this agents.md concept is for AGENTS - so it makes MORE sense to do what's best for THEM, rather than compromise...
I like how you keep assuming people aren't doing anything important, but would say you take such assumption with a grain of salt, now for AI not following instructions is a bigger problem than just which format is used, don't make it look like its simple, if it was, well then use your magical format and you done, for more context on that point, read here: https://www.parlant.io/blog/how-parlant-guarantees-compliance otherwise even looking at this from business perspective, markdown is much easier for purely non technical vibe coders to pickup than your xml and html stuff, this is important for products like cursor, further making this the overall winner, human readable, business sense, LLMs can read it, if it didn't work for you, it works for others sorry.
So you're new to this.
You can't put markdown in markdown.
You can't pout anything else (xml/html/etc) in markdown either, if that "else" contains markdown...
You need to read and understand the OP - " the nuances of priority, recursive embedding, unambiguous references, nested steps " - otherwise you're wasting everyone's time because you have not learned this lesson yet.
If you think it's working for you today, you're either not doing anything important enough yet, or have not realized that it's not working properly for you yet.
Sir, you repeat disrespecting others.
I will have to report your replies if you keep doing it.
Please avoid any unpleasantries.
You can put markdown in markdown - I have, it works.
Besides that, I advocate xml tags with markdown as @Hussseinkizz perfectly phrased in their answer.
Please be nice.
This is a public medium.