What YAML Is, and Why Every Agent Skill You Build Depends On It

I broke my first agent skill because I forgot three dashes.

Not a typo in my instructions. Not the wrong file name. Three literal hyphens missing from the top of a file, and the agent handed me back an error that looked like actual code.

The kind of error that makes you close the laptop, mutter something, and decide you will be a technical person again tomorrow.

If you have built a skill, a config file, or anything AI-adjacent lately and hit an error like that, hi. This post is for you.

The thing that broke it has a name: YAML. Once you understand it, YAML stops looking scary and turns into one of those small, boring skills that quietly makes everything else work better. I promise it is more boring than hard.

What is YAML?

YAML stands for “YAML Ain’t Markup Language.”

Yes, that is a joke. The name refers to itself, and whoever named it clearly thought they were having a moment.

But the name is making a real point. Unlike HTML, which is a markup language for describing documents, YAML is not about page structure. It is a way of writing structured data in a format that both humans and computers can read.

That structured data might be names, values, lists, settings, tags, dates, or instructions.

You have probably seen YAML without knowing what it was called. It often looks like the little block at the top of a file, sitting between two rows of dashes:

---
name: voice-note-to-pdf
description: Turn a voice note into a clean PDF summary
---

That block is called frontmatter. In an Astro blog post like this one, frontmatter tells the site the title, description, date, image, and tags for the post. In an agent skill, frontmatter tells the agent what the skill is called and when it should reach for it.

Think of YAML as the label on the box, not the thing inside the box.

It does not do the work. It tells whatever is reading the file what the work is and whether this file matters right now.

Why agent skills depend on YAML

When you create a skill for an AI coding agent, the instructions are only part of the setup.

The agent also needs metadata. That metadata usually lives in YAML frontmatter at the top of the SKILL.md file:

---
name: draft-blog-from-script
description: Turn a YouTube script into a finished blog post for my Astro site
---

The name gives the skill an identity. The description helps the agent decide when the skill applies.

That description is not decoration. It is not a cute note to yourself. It is one of the signals the agent scans when it asks, “Does this skill match what the user just asked me to do?”

If the description is too vague, the skill may never trigger. If it is too broad, it may trigger at the wrong time. If the YAML syntax is broken, the skill may not load at all.

That is the annoying part. You can write the most thoughtful, specific, beautifully useful skill instructions in the world, but if the YAML header is broken, your skill can still do absolutely nothing.

Very humbling. Very rude. Technically fair.

If you are new to this whole agent setup, start with what AI agents are and then come back here. YAML makes more sense when you understand that an agent is not just answering a prompt. It is choosing tools, reading files, and deciding what workflow to follow.

The basic YAML format

The good news is that beginner YAML does not have many rules. The bad news is that it cares about those rules a lot.

Start and end the frontmatter block with three dashes:

---
name: voice-note-to-pdf
description: Turn a voice note into a clean PDF summary
---

Each set of dashes needs to be on its own line.

Everything between the two --- lines is YAML. Everything after the second --- is your regular Markdown content or skill instructions.

Most beginner YAML uses key: value pairs:

name: voice-note-to-pdf
description: Turn a voice note into a clean PDF summary

The part before the colon is the key. The part after the colon is the value.

And yes, the space after the colon matters:

name: voice-note-to-pdf

That is good.

name:voice-note-to-pdf

That is asking YAML to ruin your afternoon.

YAML uses that space to tell the key and value apart. It looks tiny, because it is tiny, but config files are tiny-detail country.

Indentation is part of the meaning

YAML leans on whitespace the way math leans on parentheses.

If you indent one line with two spaces and a similar line with four spaces, YAML does not treat that as a cute formatting choice. It treats those as different levels of meaning.

For lists, use spaces and keep the indentation consistent:

tags:
  - ai
  - codex
  - beginners

Do not use tabs. I know. I also wish every tool on earth agreed on invisible spacing, but here we are.

If your editor can show invisible characters, turn that on when you are debugging YAML. It makes the problem way less mysterious.

Quote values that contain colons

This one gets beginners constantly because it happens when you are writing normally.

Imagine you write a description like this:

description: Turn a voice note into a PDF, no fluff: just the steps

That second colon can confuse YAML. It may think you are starting another key.

Wrap the whole value in quotes:

description: "Turn a voice note into a PDF, no fluff: just the steps"

Now YAML knows the colon belongs inside the text.

Use straight quotes, not curly quotes. This part is sneaky. If you write your YAML in Google Docs, Apple Notes, or anywhere with smart quotes turned on, your editor might swap " for curly quote marks.

YAML does not recognize those as the same thing.

So if your YAML looks correct and still will not parse, check the quotes. Autocorrect loves to help in ways that are deeply unhelpful.

The mistakes beginners actually make

The beginner YAML mistakes are rarely complicated. They are just hard to see until something breaks.

The big ones:

• Missing the opening or closing ---
• Forgetting the space after a colon
• Leaving a second colon unquoted inside a value
• Pasting in curly quotes from a notes app
• Mixing tabs and spaces
• Indenting related lines inconsistently

My personal favorite, by which I mean the one that annoyed me the most, was forgetting the closing set of dashes while recording a tutorial about how to build skills correctly.

Beautiful. No notes.

The fix was not deep engineering. It was three hyphens on a line by themselves.

That is why YAML errors can feel so dramatic. The error message looks serious, but the fix is sometimes embarrassingly small.

Why this matters more now

YAML has been running config files for years. GitHub Actions, Docker Compose, CI pipelines, static site generators, and a bunch of DevOps tools all use it.

For a long time, most people could ignore it unless they were deep in infrastructure land.

That is changing.

Now YAML is showing up in the exact places beginners are meeting AI tooling:

• Agent skills
• MCP server configs
• Prompt libraries
• App metadata
• Blog frontmatter
• Automation workflows

You do not need to become a YAML expert. Please do not let anyone convince you that you need to read a full YAML specification before you are allowed to build a useful skill.

You just need enough to avoid getting taken out by three missing dashes.

If you are already learning how to write better prompts, this is the next layer down. A prompt tells the AI what you want in the moment. YAML helps the tool understand the reusable structure around that work. I wrote a beginner-friendly explanation of prompts in What is a Prompt (Really)? if that piece still feels fuzzy.

A tiny checklist before you save a skill

Before you finish a SKILL.md file, check this:

• Does the file start with ---?
• Does the YAML block end with ---?
• Does every key use key: value with a space after the colon?
• Are values with extra colons wrapped in straight quotes?
• Are you using spaces instead of tabs?
• Is the description specific enough for the agent to know when to use the skill?

That last one is the part people underestimate.

A weak skill description sounds like this:

description: Helps with writing

That could mean anything.

A stronger one sounds like this:

description: Turn a YouTube script into a finished blog post for my Astro site, matching my tone of voice and existing post format

Now the agent has something it can actually match against a request.

Specific beats clever here. Every time.

Keep a working example nearby

I still keep a working example open when I write new skills.

Not because I have fully memorized every YAML rule. Clearly, I forgot three dashes on camera once, and I will probably find a new tiny way to embarrass myself later. Growth mindset, but make it config files.

The difference now is that when the error shows up, I know what it is trying to tell me. I am not staring at the screen like the computer has personally betrayed me.

If you are building your first agent skill, do yourself a favor and start from a known-good file. Copy the frontmatter shape, change the name, rewrite the description, and keep the indentation boring.

Boring is good here. Boring means the tool can read it.

If you want the full walkthrough, including the exact moment I hit this error, watch the video above. Come watch me mess it up in real time so you can skip that part in your own setup.

Happy building!

Kedasha

This post was written with the help of AI from a human-written YouTube script.