Clarify your Intent for Agents with Markdown Semantics

We have all been there: You write a skill, which reads very clearly to you, but the agent doesn’t always get it right. So you expand the text, repeat yourself, etc.

Did you know that coding agents such as Codex and OpenCode are quite good at actually understanding the semantics of markdown syntax? Numbered lists have an order to their items and current AI models do prioritise that order. 

Let me give you a small overview with some examples on how you can improve your agent skills and context files.

Reduce Prose Text

Reading tasks defined in prose text is a challenge to humans and AI models alike.

Imagine you are packing for a concert in your town.

You need your concert ticket, ticket for public transport, your earplugs, wallet with money and ID and you want to make sure your phone is charged.

That short list above is much clearer to check, if it’s written in bullet points:

- Concert Ticket
- Ticket for public transport
- Earplugs
- Wallet
    - Money
    - ID
- Charged Phone

Many coding agents with their /init command generate large AGENTS.md files with "too much information". To describe your applications features, they may use 5-10 lines of text, while a bullet point list may give an easier overview instead.

Use bullet points to list information in a clean way that does not rely on an order.

Check Boxes for Tasks

Using checkboxes can help convey that the items are individual tasks, which should be verified at the end. I have not seen a significant impact by using check boxes, so I go with numbered lists if precision is necessary.

- [ ] Concert Ticket
- [ ] Ticket for public transport
- [ ] Earplugs
- [ ] Wallet
    - [ ] Money
    - [ ] ID
- [ ] Charged Phone

Describe Workflows with Numbered Lists

While many skills just describe a workflow in prose text, some use bullet points.

But bullet points are an unordered list. So you do the last point first, that’s okay. When describing a workflow, that’s just not the right tool for the job.

Instead of a fictional example, let's consider Matt Pocock’s grill-with-docs skill, which interviews the user on a topic, while also reading and updating the project documentation (for projects using domain driven design, but that’s irrelevant here).

---
name: grill-with-docs
description: A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go.
---

Run a `/grilling` session, using the `/domain-modeling` skill.

The above skill looks okay and worked well, before the training data of the models contained many articles about the now famous grilling skill.

I have observed my agents frequently not loading the grilling skill, but relying on its training data.

The below version aims to improve this by making each step of the workflow explicit.The numbered list means that I cannot proceed to step 2 without finishing step 1.

Additionally, I have rephrased “running a grilling session” to “read the grilling skill”, making my intent more explicit.

---
name: grill-with-docs
description: A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go.
---

1. load the `domain-modeling` skill
2. load the `grilling` skill
3. Strictly follow the instructions of both skills to perform a domain-aware grilling session

Headings (H1-H3)

Headings help a model understand the structure of your input. This applies to prompts, AGENTS.md and skills. Any input, really.

Only add an H1, if it adds something. In your repository README.md, # Version Control System for Images brings real value. But adding # Context for Agents to your Context.md doesn’t add anything. Just omit it.

H2 headings and H3 headings, on the other hand, are always great to structure longer text.Let’s look at a prompt to plan a task. Instead of writing “add a database to the IaC” and maybe adding a little more text manually, we can include the Jira Ticket information for more context.

The following prompt gives a clear task (writing an implementation plan) for a clear scope (adding a new database) with acceptance criteria and additional context, which may dictate further acceptance criteria.

Write an implementation plan for the following task:

## Task Description
Add a new database to the IaC

### Technical Acceptance Criteria
- Use smallest size available for DEV environment
- Backups for PROD only
- Delete DEV database, when DEV stack is deleted
- Retain PROD database, when PROD stack is deleted

## User Story Details
[Paste your ticket info from Jira]
This Jira Ticket information will give insights into what this database will be used for.
Acceptance Criteria here are likely non-technical

Code Blocks

Markdown has two syntax elements related to Code:

Inline Code can be useful to highlight and scope file names, commands, classes or even words with special meaning.

It can be useful when describing behaviour differences when running an application on windows, mac or linux platforms.

I like to use it when listing my npm scripts in my AGENTS.md:

[...]
## Common npm scripts
- `npm run build`: Build the application
- `npm run test`: Run all tests, including integration tests
- `npm run test:unit`: Run unit tests only

See the package.json for a full list of npm scripts
[...]

Code Blocks are useful for two things: 

• provide code examples inline in your markdown file
• Limit the scope of a markdown template within your markdown

The following example shows a simple prompt to review if the code aligns with SOLID principles. It defines the output structure with a template in a code block:

Review if the code follows the review criteria and write a report with your findings.

## Review Criteria

Focus your review on the SOLID principles
- Single Responsibility
- Open/Closed
- Liskov Substitution
- Interface Segregation
- Dependency Inversion

## Report

After reviewing the code, you perform the following steps to create a report:
1. Define a Severity for each Finding (`Low`, `Medium`, `High`)
2. Define an Effort Estimate for each Finding in T-Shirt Sizes (`S`, `M`, `L`)
3. Use the Template defined below to format your report

### Template
```
# SOLID Review Report

Verdict: `PASS` or `FAIL`

The code review has found <NUMBER> findings

## Findings

1. <FINDING NAME>: <FINDING DESCRIPTION> 
    - Severity: <SEVERITY>
    - Effort Estimate: <EFFORT ESTIMATE>
    - File: <FILE>
```

The Toolbelt

Here is a small overview of the most useful Markdown elements and their intent.

Next Steps

With this markdown syntax you can describe your intent more clearly with less text. Depending on your agent, context and model, you may see a minor or major impact. If you want to take this further, see how you can optimize your agentic development workflows across your team (german).

For me, the greatest benefits have been in my AGENTS.md and my skills. These are living documents, so take ownership and improve them as a team.

Just don’t forget that we have the same deterministic tools that we’ve always had. Don’t describe your coding style when you can use a formatter. Don’t tell the agent to “always run build, lint and tests”, if you can use a git pre-commit hook.