---
name: yaml-style-conventions
source: https://app.decimal.ai/s/yaml-style-conventions@1/SKILL.md
source_sha256: 39fdccd4c7d1
---

# YAML style conventions

## Contract

Enforces the yamllint-default style on every YAML document you write or normalize: 2-space indentation,
lowercase `true`/`false`, plain unquoted scalars, block style, and a leading `---`. Apply whenever the task
is to author or clean up a `.yaml`/`.yml` file; not when picking what settings the file should contain.

## Rules

1. **Indentation — 2 spaces per level, spaces only.** Each nesting level adds exactly two spaces. Never
   use tabs, and never use 4 spaces. Sequence items under a key are indented two spaces from that key.

2. **Booleans — lowercase `true` / `false`.** A boolean scalar is always `true` or `false`. Never `Yes`,
   `No`, `On`, `Off`, `TRUE`, `False`, `y`, or `n` — those are the legacy YAML 1.1 spellings this style
   rejects.

3. **Quote only when required.** Leave an ordinary scalar unquoted (`name: api-gateway`, `count: 3`).
   Add quotes ONLY when the value would otherwise parse as a different type or is ambiguous:
   - a string that reads as a boolean or number → quote it: `answer: "yes"`, `version: "3.10"`, `zip: "07030"`.
   - `null`, `~`, or an empty value you want as a string → quote: `note: ""`, `tag: "null"`.
   - a value beginning with an indicator character (`@ ` `` ` `` `%` `&` `*` `!` `?` `|` `>` `#` `,` `[` `{`),
     or containing `: ` or a trailing space → quote it.
   When you must quote, prefer single quotes unless the value needs an escape.

4. **Spacing — one space after `:` and after `- `.** Write `key: value`, never `key:value` and never
   `key :value`. A sequence dash is followed by one space: `- item`. No space before the colon.

5. **No trailing whitespace; end with one newline.** Strip spaces at end of line; the file ends in a single
   `\n`.

6. **Document start `---`.** Begin the file with a `---` document-start marker on its own line. It is
   required for a multi-document stream and is the linted default for single documents too.

7. **Block style over flow.** Write nested mappings and sequences in indented block form, one entry per
   line. Do not collapse them into inline flow `{key: value}` / `[a, b]`. Reserve flow only for a genuinely
   empty collection (`items: []`).

8. **Comments — `# ` then text.** A comment is a hash followed by one space. Put a full-line comment on its
   own line, indented to the block it describes.

## Worked examples

The base's echo-the-input default is on the left; the conforming YAML on the right.

A logging block handed in with tabs, `Yes`, and an inline flow map:

```
BEFORE  logging:
        	level: DEBUG
        	handlers: {console: Yes, file: No}

AFTER   ---
        logging:
          level: DEBUG
          handlers:
            console: true
            file: false
```

An HTTP server section indented four spaces, with over-quoted plain strings:

```
BEFORE  server:
            "host": "localhost"
            "port": "8080"

AFTER   server:
          host: localhost
          port: 8080
```

A value that genuinely needs quoting because it would parse as a boolean or a float:

```
BEFORE  reply: yes
        release: 2.0

AFTER   reply: "yes"
        release: "2.0"
```

## Edge cases & exceptions

- **A string that looks like a number** (a leading-zero code, a version, a phone number) → quote it so it
  stays a string: `code: "007"`, not `code: 007`.
- **A value containing a colon-space** (`title: a: b`) parses wrong unquoted → quote the whole value:
  `title: "a: b"`.
- **An empty mapping or list** is the one place flow is fine: `env: {}` / `args: []`.
- **A multi-line string** uses a block scalar (`|` literal or `>` folded), still indented two spaces under
  its key — not a quoted one-liner with `\n`.
- **Anchors/aliases** (`&name` / `*name`) keep their leading indicator; they are not quoted.

## Do / Don't

- Do write booleans as `true` / `false`. Don't use `Yes` / `No` / `On` / `Off`.
- Do indent with 2 spaces. Don't use tabs or 4 spaces.
- Do leave plain scalars unquoted. Don't wrap every string in quotes.
- Do quote a value that would otherwise parse as a bool/number/null. Don't leave `port: "8080"` quoted when
  the value is a plain integer.
- Do use block style for nested maps. Don't inline them as `{a: 1, b: 2}`.
- Do begin the file with `---`. Don't start straight into the first key.
- Do put one space after `:`. Don't write `key:value`.

## Common mistakes

- Carrying the input's 4-space or tab indentation straight into the output.
- Preserving `Yes` / `No` / `On` / `Off` instead of normalizing to `true` / `false`.
- Quoting ordinary strings (`"localhost"`, `"api"`) that never needed quotes.
- Forgetting to quote a value that DOES parse wrong (`version: 1.0` silently becomes a float `1`).
- Emitting a nested map as inline flow `{ }` instead of an indented block.
- Omitting the leading `---`.
- `key:value` with no space after the colon.

## Quick checklist

- [ ] Two-space indentation, no tabs, no 4-space blocks.
- [ ] Every boolean is `true` or `false`, never `Yes`/`No`/`On`/`Off`.
- [ ] Plain scalars unquoted; only ambiguous values quoted.
- [ ] One space after each `:` and each `- `.
- [ ] Nested collections in block style, not inline flow.
- [ ] File opens with `---`; no trailing whitespace.