Why Your AI Keeps Getting It Wrong - And How Markdown Fixes It

Most Skills that produce inconsistent output have one thing in common: the instructions are written as prose. A paragraph explaining what the AI should do, another explaining what to avoid, everything run together with no structural signal separating rules from context from examples.

It's an easy pattern to fall into. Prose feels natural to write, and the instructions usually make complete sense when you read them back. The problem shows up in the output. The model reads everything as equally weighted text and makes judgment calls about what matters. Some of those calls are right. Some aren't. The output varies.

This isn't a model problem. It's a structure problem and it's one of the most common things we see when Skills aren't performing the way they should. The good news is that the fix is straightforward: Markdown gives your instructions the structure that removes the guesswork entirely. This post walks you through exactly how.

What Markdown Actually Is

Markdown is plain text with a small set of formatting symbols that tell a renderer how to display the content. Created in 2004 by John Gruber (with Aaron Swartz as a key collaborator), it was designed around one constraint: the raw file should be readable without rendering it. The ## symbol for a heading, the ** around bold text - these were chosen because they visually suggest their function before any tool processes them.

Web Dev Simplified's Markdown Crash Course describes it well: Markdown is a writing-first format that converts plain text into structurally valid HTML. The raw view is the blueprint. The rendered view is the finished house.

When a .md file opens in Notepad or TextEdit and shows ## symbols and asterisks instead of formatted text, nothing is broken. It opened in a tool that displays the blueprint instead of rendering the house. Open the same file in Dillinger, Typora, or nuwacom's Skill editor and it looks like a normal document. The file hasn't changed, only the tool displaying it has.

Markdown Syntax: The Six Symbols You Actually Need

The table below maps what you see in a raw text editor to what a renderer produces.

Six patterns. That's the working vocabulary for most Skill files and knowledge base entries you'll write in nuwacom.

Headings use # symbols. One # is the document title. ## is a major section. ### is a subsection. Most documents don't go deeper than three levels - if yours does, the structure usually needs rethinking before the nesting does.

Bold and italic use asterisks. **text** renders as bold. *text* renders as italic. Both markers disappear once rendered. Web Dev Simplified recommends * over _ for italics - underscores can behave unexpectedly inside compound words.

Links follow the pattern [visible text](URL). No space between the closing bracket and opening parenthesis. One of the few places where a missing character breaks the output entirely.

Code uses backticks. Single backtick for inline references: `like this`. Three backticks on their own line open and close a block - useful for Skill instructions, configuration examples, or anything you want displayed verbatim rather than interpreted.

The Markdown Guide cheat sheet covers the full syntax. The Basic Syntax reference has the detail behind each element.

Why Structure Changes What the AI Does With Your Instructions

Large language models don't just read text. They parse it. When input arrives as unformatted prose, the model has to infer what's a rule, what's context, what's an example, and what's a constraint - from the same undifferentiated stream of words. It makes reasonable guesses. Some of those guesses are wrong.

Here's what that looks like in practice.

The same Skill instruction, written two ways:

Unformatted prose version:

You are a customer response assistant. When responding to customers, be professional and direct. Answer their question first before adding context. Keep responses short, under 150 words. Don't use passive voice or promise delivery dates without confirmed inventory. Always end with a next step. Avoid sign-offs like "please don't hesitate."

Structured Markdown version:

Both contain the same information. The model reading the prose version treats it as a continuous argument where everything has roughly equal weight. It has to guess that "under 150 words" is a hard constraint, not a preference - and that "don't use passive voice" is a rule, not a stylistic suggestion. The model reading the Markdown version doesn't have to guess. ## Instructions signals directives. ## Avoid signals constraints. ## Expected Output signals evaluation criteria. The hierarchy is explicit.

The result isn't that the model becomes smarter. It's that the model spends less inferential effort on structure and more on execution. That's where the output quality difference comes from.

How to Use MD Files in nuwacom

MD files show up in three places inside nuwacom. Here's what you'll actually do in each one.

Skills and Custom Instructions

A Skill in nuwacom is a structured instruction set that defines how the AI behaves for a specific task - what to produce, how to produce it, what to avoid. The Skill is written in Markdown. The headings are not decoration: they're the signals that tell the model what category of information it's reading.

Most Skill files start with a YAML metadata block. Before the AI reads a single instruction, it needs to know what kind of document it's dealing with and who is supposed to be writing it. The YAML block answers that. Think of it as a label on a file folder - the folder holds your instructions, and the label tells the system what's inside before it opens anything.

Each line is a field. The role field is the one that matters most — it establishes the professional identity the AI adopts before reading anything else in the Skill. When an LLM sees role: Expert Customer Communication Specialist, the model doesn't start from a blank slate. It starts from a defined behavioral baseline. Everything that follows gets interpreted through that lens. The Best Practices section covers what to write in each field and why it matters.

Below the YAML block, the Skill itself is written in Markdown. A complete working file looks like this:

The model reads ## Instructions and knows it's parsing directives. It reads ## Avoid and knows it's parsing constraints. Flatten both into unformatted prose and the model treats them as equally weighted text — which is exactly the condition that produces variable output.

Documentation

nuwacom can store guides, processes, and reference documentation in Markdown because plain text is readable by both humans and retrieval systems. Updating it doesn't require specialized software. Any text editor handles the change. Any Markdown renderer handles the verification.

The practical operation here is narrow: adding a section to an existing file without breaking its structure. Add a ## heading at the correct level, write the content underneath, save. The file remains valid Markdown. Every tool that processed it before still processes it correctly.

Knowledge Base Entries

Knowledge base entries define what the system knows about your business: products, processes, terminology, constraints, edge cases. Structure matters here because it reduces one specific failure mode - the model applying information in the wrong context.

Now, nuwacom can ingest many different file types including PDFs, Word documents, spreadsheets, slides, and more. So you don't need to convert anything just to use it. But there's a difference between what works and what works well. When a knowledge base entry is in Markdown with proper headings, the model can tell the difference between, say, a "Key Specifications" section, which is general product data, and a "Known Edge Cases" section, which is behavior that differs from the norm. Flatten that into prose, or leave it buried inside a PDF with no structural signals, and the model has to infer which claims are general and which are exceptions. That costs computational effort and raises the chance the model misapplies what it finds. 

That said, this is not a "go convert every file in your organization" recommendation. That would be overkill. Where it makes a real difference is when you're setting up a specific project, say you're building a customer presentation or kicking off a product launch and there are five to ten files that are particularly relevant to that work. Product specs, brand guidelines, core reference documents. For those files, converting them to Markdown before uploading them to your knowledge base is worth the effort. You're making a small, focused investment in structure that pays off every time the model retrieves from those documents.

A few handy tools

The following tools are little free helpers that we find very useful for our markdown workflows:

• Markdown-to-richtext converter. As the name suggests, this one converts markdown to richtext, which is useful if, for instance, you want to share a skills instructions in a form that’s easier to read for humans. 

• Richtext-to-markdown converter: This one handles the conversion in the opposite direction very well. If you want to feed existing docs to AI, this one is very helpful.

• t0md - Files to MD converter: A good converter for PDFs, PPTX, Docx, and other files to markdown. 

Best Practices for Writing Markdown in nuwacom

Correct Markdown and effective Markdown are not the same thing. A file can render without errors and still produce inconsistent AI output because the structure is ambiguous, the sections are overloaded, or the constraints are too vague to act on. These practices close that gap.

YAML Metadata

• Fill in the YAML block every time. It is not an optional boilerplate. LLMsread the role field before processing the Markdown below it. A Skill without a defined role gives the AI no identity anchor, which means it defaults to a generic response posture regardless of how well-written the instructions are.

• Write the role as a job title, not a description. Expert Customer Communication Specialist works. A helpful assistant that responds to customers does not - it's too diffuse to establish a meaningful behavioral baseline.

• Keep the description to one sentence. It's a routing signal, not a summary. If you're writing more than one sentence, you're putting instruction content in the wrong field.

Heading Hierarchy

• Start every Skill with a single # title. One H1 per file. Everything else is ## or ###. Multiple H1s tell the model the document has multiple roots, which undermines the hierarchy you're trying to establish.

• Use ## for major sections, ### only when a section genuinely has sub-components. If you're reaching for ### because a ## section is getting long, the section probably needs to be split, not subdivided.

• Don't skip levels. Going from ## to #### without a ### in between creates structural gaps the model has to bridge inferentially. Keep the hierarchy unbroken.

Skill Sections

• Keep each section short enough to scan in under ten seconds. If ## Instructions runs to twelve bullet points, the model is working through a list long enough to lose priority weighting. Break it into two named sections before it reaches that length.

• One idea per bullet point. A bullet that contains two instructions separated by "and" is two bullets. Compound instructions produce compound ambiguity.

• Write ## Avoid with reasons, not just rules. - Don't use passive voice is a rule. - Avoid passive voice - it obscures who is responsible for the action, which matters in customer-facing responses is a constraint the model can apply judgment to. The reason is what makes the rule transferable to edge cases you didn't anticipate.

Example Sections

• Always include ## Example Input and ## Example Output. These two sections do more to anchor consistent AI behavior than any other part of the Skill. The model uses them to calibrate the gap between a raw input and an acceptable output - length, tone, structure, level of detail. Instructions tell the model what to do. Examples show it what done looks like.

• Use a real example, not a placeholder. [Insert example here] contributes nothing. Pull an actual input from your workflow - a real customer inquiry, a real meeting note, a real product question - and write the output you'd want the AI to produce. The closer the example is to production reality, the better the calibration.

• If your Skill handles more than one input type, include one example per type. A Skill that handles both short inquiries and detailed complaints needs both represented. A single example anchors the model to one pattern only.

Knowledge Base Entries

• Separate facts from exceptions at the heading level. General product information and known edge cases belong under different ## headings, not in the same paragraph. The heading tells the model which category of claim it's reading.

• Put the most important information first within each section. nuwacom retrieves context under time and token constraints. If the critical specification is buried in the fifth sentence of a paragraph, it may not surface when it needs to. Lead with the claim, then support it.

• Flag exceptions explicitly. Don't rely on softening language like "usually" or "in most cases" to signal an exception. Write a ## Exceptions or ## Edge Cases section and put the deviation there, explicitly labeled.

Documentation Files

• Write one topic per file. A documentation file that covers three related processes is harder to retrieve and harder to maintain than three focused files. nuwacom's retrieval performs better on narrow, well-labeled documents than on broad ones.

• Use the filename as a summary. customer-response-drafting.md is retrievable. doc-v3-final.md is not. The filename is metadata. Treat it as such.

• Update the YAML description field when the content changes. Stale metadata creates a mismatch between what nuwacom expects to find in a file and what's actually there. Keep the description current.

Starter Template

Use this when building a new Skill in nuwacom. Copy it, adapt the values, verify the rendered output in Dillinger, then load it as a Skill.

Save with a .md extension - type the filename manually in the Save As dialog if your editor defaults to .txt. Open in Dillinger to verify the structure renders correctly, then load it into nuwacom's Skill editor.

One Last Thing

Markdown isn't a technical requirement. It's a communication decision. Every time you structure a document; a Skill, a knowledge base entry, a process guide, you're deciding how much inferential work you're asking the AI to do before it gets to the actual task. Structured input means less guesswork. Less guesswork means more consistent output. That relationship holds whether you're building a single Skill or managing a system of fifty.

The format is simple enough to learn in an afternoon. The discipline of using it consistently is what compounds over time. Documents that are easier to update, easier to hand off, and easier to trust because the structure makes the intent explicit to anyone reading it, human or AI.

That's what well-written Markdown actually gives you. Not just cleaner files. A more reliable system.