C. Markdown and YAML reference

Markdown keeps technical notes readable as plain text while adding simple structure for a renderer. YAML is a data format used for small metadata blocks such as skill frontmatter. They serve different purposes: a Markdown heading organizes prose, while a YAML key supplies a value to a parser. Preview documents and validate the format consumed by the actual host.

A small README that teaches an action

This original example uses the constructs needed in the course:

# Synthetic monitor baseline

The host prints a fixed sample. No physical measurement is claimed.

## Run

From the extracted CP01 project root in PowerShell:

```powershell
.\scripts\replay.cmd
```

Read the [setup instructions](docs/setup.md) before running the build.

- Confirm the current folder.
- Read the actual output and exit status.
- Keep the synthetic label with the result.

## Evidence

| Check | Result | Limit |
| --- | --- | --- |
| Host replay | Record your actual run | No physical sensor observation |

Use one main heading and meaningful subordinate headings. Blank lines separate paragraphs and blocks. Backticks mark inline code; fenced blocks preserve multi-line commands and their language label. A normal prose paragraph is not a reliable way to preserve code spacing. Core headings, links, lists, and fences are defined by CommonMark; tables and task lists are common extensions whose support must be checked in the chosen renderer. CommonMark 0.31.2

Write commands exactly as learners should enter them, with context outside or in a clearly marked comment. Do not include a terminal prompt as part of the command. If you show expected output, use a separate block and label it expected. If you show actual output, name the run that produced it.

Links and images

A relative link is resolved from the document containing it. In a root README, docs/setup.md points into the docs directory. In a document already inside docs, the equivalent sibling may be setup.md. Test the link from the rendered location instead of assuming a working filesystem path will be rewritten correctly by every export.

Use descriptive link text, such as “toolchain setup,” rather than “click here.” An image needs useful alternative text explaining the information it conveys. A screenshot caption should name the action and relevant result; decorative wording does not help a learner who cannot read tiny interface text. Keep selectable commands in the page even when a screenshot shows them.

YAML frontmatter for a skill

---
name: datasheet-to-constraints
description: Derive sourced constraints for an exact component from supplied primary documents.
---

The opening and closing delimiters mark the metadata block used by the skill format. Keys and values are separated by a colon and space. Use spaces consistently for indentation when nesting data. Quote a value when punctuation might be interpreted structurally, especially a colon followed by a space. YAML's full syntax is broader than this small subset; consult its specification when a parser reports an ambiguity. YAML 1.2.2

Do not put Markdown headings inside the metadata block or leave its closing delimiter out. Keep a skill's workflow in the Markdown body after frontmatter. A valid YAML document can still have the wrong keys or an overbroad trigger for the consuming tool; syntax and behavior require separate checks.

Recovery checks

If a code block swallows the rest of a document, inspect its closing fence. If a link fails, resolve it from the current document and check spelling/case. If a table renders as plain text, confirm the selected renderer supports that extension and that the separator row exists. If a skill is not discovered, check exact filename, location, metadata, and host behavior before rewriting its procedure.

Keep the final document useful without its author standing nearby. A reader should find the starting state, action, expected result, actual evidence, and remaining limitation. Formatting is successful when it makes those details easier to follow.