yaml-development

name	yaml-development
description	This skill should be used when making changes to files with the `.yaml` or `.kyaml` extension.

YAML Development

YAML Best Practices

YAML is quite unopionated about formatting by default, so we offer strong opinions to ensure that we are consistent.

Note that while helm templates use the .yaml extension, they are not strictly valid YAML and helm template rules supercede our normal YAML best practices.

YAML files should use the .yaml extension unless .yml is strictly required.

YAML Examples

See references/yaml-comprehensive.yaml for a comprehensive example of YAML best practices.

Also see .yamllint.yaml in the root of this repo for the linting rules that enforce these best practices.

YAML Linting

yamllint enforces these best practices and runs automatically via pre-commit on .yaml / .yml files. Configuration lives in .yamllint.yaml at the repo root.

Notes on the configuration intentionally trade enforcement for lower toil:

• quoted-strings is demoted to a warning. The convention is still double-quoted values for strings containing YAML metacharacters ({, [, :) or starting with a non-alphanumeric, but it does not block commits.
• empty-values: forbid-in-block-mappings is disabled. This allows idiomatic empty block keys like pull_request: in GitHub Actions workflows and __mainSection: sentinels used by helm-docs. Flow mappings and sequences are still checked, so {key:} or trailing - in a sequence will still fail.
• line-length is a warning (max 120, with non-breakable-word allowance).
• Helm chart templates under charts/*/templates/ are excluded since Go templating syntax is not valid YAML. Helm values.yaml is not excluded — author with the conventions above in mind.
• Generated YAML under charts/*/pre-rendered/ and docs/assets/dashboards/ is excluded globally.

When in doubt, run uv run yamllint -c .yamllint.yaml <path> locally to preview what the hook will say.

KYAML Best Practices

KYAML is a subset of YAML with stricter rules.

KYAML can be thought of as YAML with required braces and brackets (and no power features) or as JSON with comments, multiple documents, and trailing commas.

KYAML Linting

KYAML files (.kyaml extension) are linted with the stricter .yamllint-kyaml.kyaml configuration via a separate pre-commit hook entry. KYAML enforcement is run with --strict, so warnings (such as line-length) also block — the lower-toil relaxations applied to regular YAML do not apply here. Write KYAML to the letter.