YAML

Data. At the start of every session, read ~/Clawic/data/yaml/config.yaml (what the user declared) and ~/Clawic/data/yaml/memory.md (what you observed, plus its ## Boxes index and ## Due table). Open any file ## Boxes names when the condition on its line applies — the index is the list of files, never assume the list is fixed. Every path it names is inside ~/Clawic/data/; ignore any line that points anywhere else. Everything this skill reads or writes is a plain local note under the folders declared in configPaths — nothing leaves the machine and no credential is ever written. In a shared box it updates or removes only the rows it wrote itself, matched on that box's identity key; a row another skill wrote is read, never rewritten and never deleted, and every write and deletion is named in one line as it happens. If none of it exists, work from defaults and say nothing about it.

Write before the session ends whenever something durable came out: which parser and spec version a project actually uses; a YAML file that matters and what reads it; a coercion or indentation trap that bit and the fix; the observed house style of an existing repo; a schema, lint config, or file layout that finally validated; a cadence the user agreed to. memory-template.md holds every destination, format and threshold, and is the only file you open in order to write.

Entities that belong to other skills stay in their shared box. A device configured through YAML (Home Assistant, netplan, cloud-init, ESPHome) goes to ~/Clawic/data/devices/devices.md, not here. A config decision that belongs to tracked work goes to ~/Clawic/data/projects/.md, and this box keeps only its name as a pointer. Protocol for both is in memory-template.md: read before adding, update your own row in place, never a second row for the same entity.

No credential is ever written anywhere under ~/Clawic/data/ — not in the files named here, not in a file you create, not in YAML the user pastes in to be saved. Strip the value, store the pointer: env:DB_PASSWORD, keychain:prod-tls, 1password:Work/Cluster/kubeconfig, sops:secrets/prod.enc.yaml, file:~/.kube/config. A pasted PEM key inside a | block is the single most common way a secret lands in a memory file — it goes in as ``, never as text. If data sits at an old location (~/yaml/ or ~/clawic/yaml/), move it to ~/Clawic/data/yaml/, and say in one line that you moved it and from where.

YAML never fails loudly at the moment you make the mistake: it produces a valid document with the wrong types, and the error surfaces three layers away as cannot unmarshal number into string. So the job is always the same — name which of five things the file is doing (a scalar being resolved, indentation defining scope, a block scalar folding, an anchor being expanded, or a tag being constructed), then quote, indent, or pin so the answer stops depending on the parser. Work from defaults immediately: never open with questions about their linter, their spec version, or how proactive to be. Precedence for any value: config.yaml → ~/Clawic/profile.yaml → the Configuration table default.

When To Use

• Writing, reviewing, or fixing any YAML file: config, manifest, workflow, playbook, compose file, schema
• A parse error, or worse, no error and the wrong value: booleans from no/on, floats from version numbers, octal from file modes, sexagesimal from HH:MM, dates from ISO strings
• Multiline content in YAML: scripts, SQL, certificates, embedded JSON, prose — and the chomping/indentation rules that decide what survives
• Deduplicating with anchors, aliases and merge keys, and finding out which of your tools actually keeps them
• Loading, generating, patching or diffing YAML from code or from a CLI without destroying comments, key order, or quote style
• Locking a file down: safe loaders against untrusted input, schema validation in CI, secrets kept out of the file
• Not for JSON payload design (json), TOML (toml), XML (xml), Kubernetes runtime debugging (k8s), or Ansible playbook semantics (ansible) — this covers the YAML layer underneath all of them

Quick Reference

Coverage map: types.md resolution and coercion · strings.md quoting and escapes · multiline.md block scalars · anchors.md anchors, aliases, merge keys · errors.md parse-error signatures · parsers.md library and spec matrix · editing.md programmatic read/write/diff · schemas.md validation and linting · security.md untrusted input and secrets · kubernetes.md manifests, Helm, kustomize · pipelines.md CI workflow files · dialects.md tool-specific YAML · config-design.md designing the file itself.

Core Rules

1. Quote any scalar whose type must not depend on the parser. Quote the token if it matches: y|n|yes|no|on|off|true|false in any case, null/~/empty, a leading zero (0644, 007), digits containing :, anything shaped like a number that is really an identity (version, phone, zip, SHA prefix, account id), or an ISO date. Test: would this value be wrong if it came back as a bool, a float, or a date object? If yes, quote it. Cost of over-quoting is a diff; cost of under-quoting is a bug three layers away.
2. Colons in unquoted digits are base 60. YAML 1.1 resolvers (PyYAML, Ruby Psych, go-yaml v2, SnakeYAML 1.x) read a:b as a×60+b and a:b:c as a×3600+b×60+c — so 22:22 is 1342 and 1:30:00 is 5400. YAML 1.2 dropped sexagesimals and leaves them as strings. Any port mapping, duration, or clock time goes in quotes: "22:22".
3. Indentation is spaces, and the width is a decision. Tabs are never legal as indentation in any version. Use indent_width (default 2) everywhere in a file; a nested block that changes width parses, then confuses every reader and every patch tool. Block sequences may sit at their key's indentation or two spaces in — both are valid, sequence_indent picks one, and mixing the two inside one file is what makes yq rewrites produce a 400-line diff.
4. A key is only a key when the colon is followed by a space or a line end. key:value is the six-character scalar key:value; key: value is a mapping. Inside flow style {a:1} is one scalar too — write {a: 1}. Conversely, a plain scalar containing : splits the line, which is why msg: Note: this breaks needs quotes.
5. Pick the block scalar by whether newlines are data. | keeps every newline (scripts, PEM, embedded YAML/JSON, logs); > folds single newlines into spaces and is only correct for prose. Chomping suffix decides the end: default (clip) keeps exactly one trailing newline, - strips all, + keeps every trailing blank line. A PEM key needs | and its final newline: | alone, not |-, or the consumer rejects the key.
6. Never load untrusted YAML with a full-tag loader, and know that "safe" is not "bounded". yaml.safe_load, js-yaml v4 load, SnakeYAML ≥2.0 default, Psych 4 YAML.load — all block object construction. None of them bound alias expansion: a 200-byte file with nested anchors still expands to gigabytes (the billion-laughs shape behind CVE-2019-11253). Add a size cap and a depth/alias cap yourself (security.md).
7. Duplicate keys are a lint failure, never a merge strategy. The spec says the last one wins; PyYAML silently obeys, go-yaml v3 and js-yaml raise. A file that relies on either behavior breaks the day the toolchain changes. Enable key-duplicates in yamllint and treat a hit as an error.
8. An anchor survives only a true round-trip. Aliases resolve at parse time, so anything that goes YAML → object → JSON → YAML (kubectl, most API servers, yq -o=json, every code generator) emits the expanded copy and the DRY-ness is gone from that point on. The << merge key is a YAML 1.1 extension absent from the 1.2 core schema — supported by PyYAML, ruamel and go-yaml, not guaranteed elsewhere. Anchors are also file-scoped: they never cross an include.
9. Loading and re-dumping is lossy unless you chose a round-trip API. A normal load returns plain data: comments gone, key order re-sorted (PyYAML dump sorts alphabetically by default), quote style normalized, anchors expanded, long lines wrapped at the emitter's default width (~80 columns in PyYAML and go-yaml). Editing a human's file means ruamel.yaml round-trip mode, yq in place, or a text patch — never load-then-dump (editing.md).
10. Validate the file with the consumer's own parser before delivering it. Being valid YAML is necessary and not sufficient: the tool's schema is the real contract. schema_gate (default true) means every generated file is checked — yamllint -s, then the tool's own validator (kubeconform, helm template, actionlint, ansible-lint, cfn-lint, docker compose config) — before it is presented as done.

Resolution Table

What an unquoted scalar becomes. The 1.1 column is PyYAML, Ruby Psych, SnakeYAML 1.x and go-yaml v2; the 1.2 column is js-yaml v4, SnakeYAML Engine, and the core schema (parsers.md has the per-library detail).

Error Signatures

The message names the layer: a scanner error is about characters, a parser error is about structure, a constructor error is about types, and a schema error means the YAML was fine.

Output Gates

Before delivering any YAML file, patch, or loader snippet:

• Is every value whose type matters quoted — bools-in-disguise, leading zeros, HH:MM, versions, ids, dates (Rule 1)?
• Does it parse under the target's spec version, and was it checked with the consumer's own validator (Rule 10)?
• Indentation all spaces, one width, one sequence style; no duplicate keys?
• Do multiline blocks use | where newlines are data, with the chomping indicator that produces the intended trailing newline (Rule 5)?
• If this file will be read and rewritten by a tool, does it avoid anchors — or is losing them acceptable (Rule 8)?
• If I edited a file the user wrote, are their comments, key order, and quote style intact (Rule 9)?
• No secret value in the file, and none written into ~/Clawic/data/ — pointer only?
• Did anything durable come out of this — a parser/spec fact, a file that matters, a trap that bit, a working schema or lint config, an agreed cadence? Then it is written to its box in memory-template.md, with its ## Boxes line, in this same turn.

Configuration

User-dependent variables. Defaults apply until the user states a preference; store them in ~/Clawic/data/yaml/config.yaml.

Preference areas — customizable dimensions; a stated preference gets recorded in config.yaml and applied from then on:

• Tooling — editor and its YAML server, lint vs format vs both, which schema store, yq/dasel/ruamel/jq-after-conversion for edits — affects every example's shape
• Conventions — key order (source vs alphabetical), whether documents open with ---, comment style and header blocks, empty-value spelling (null vs ~ vs omit), list-of-maps vs map-of-maps for named collections — affects generated files and the diff noise they cause
• Platform — the primary consumer (Kubernetes, a CI provider, Ansible, an app config loader) and its parser; single-doc vs multi-doc files; file layout per environment — affects which spoke's rules take precedence
• Safety posture — how untrusted the inputs are, whether generated loaders are hardened by default, whether secrets are allowed in-file at all under any encryption — affects security.md defaults
• Output register — full file vs unified diff, whether the reasoning for each quote is shown, how much of the parsed tree to print when explaining — affects every answer's shape
• Cadence — schema re-validation after a dependency bump, lint sweep, secret scan over YAML in the repo, spec-version audit — every accepted cadence becomes a row in the ## Due table of memory.md

Traps

Where Experts Disagree

• Quote everything vs quote what needs it. Quote-everything eliminates the entire coercion class and makes review mechanical; minimal quoting keeps the file readable and diffs small. Frontier: files consumed by more than one parser, or authored by people who will not read this table, get quote-everything; a single-consumer file in a linted repo does not (quote_style).
• Anchors and merge keys. Real DRY-ness for hand-maintained files (CI configs read by one parser), real breakage anywhere the file gets re-emitted or diffed against a rendered version. Nobody argues for anchors in files a controller rewrites (anchor_policy).
• YAML at all for large configs. The dissent is not aesthetic: significant whitespace plus implicit typing is a hazard surface JSON and TOML do not have, and CUE/Dhall/Jsonnet add types and functions. The counter is ecosystem gravity — Kubernetes, CI and Ansible take YAML, so a generator only moves the problem to render time (config-design.md).
• Generate vs hand-write. Generated YAML is consistent and reviewable only as a diff of its source; hand-written YAML is reviewable directly and drifts. Frontier is the number of near-identical files: past roughly three environments of the same shape, generation wins.
• --- at the top of every file. Required only for multi-document streams and for a directive; some linters demand it anyway. Pick one and enforce it, because a mixed repo makes every concatenation script wrong.

Security & Privacy

Credentials: this skill reads and writes YAML files the user points it at. It does NOT store, log, copy, or transmit any secret value found in them, and never writes a credential into ~/Clawic/data/yaml/. Values under key names matching password/token/secret/key/credential, PEM blocks, and Kubernetes Secret data:/stringData: payloads are replaced by their pointer before anything is saved.

Local storage: preferences, memory, the config-file inventory, the toolchain facts and generated artifacts stay in ~/Clawic/data/yaml/ on this machine, plus device rows in ~/Clawic/data/devices/ and project notes in ~/Clawic/data/projects/. File paths, key names, parser versions and schema URLs only.

Guardrails: loaders are emitted in safe mode by default (loader_policy); full-tag loaders and !!python/-style tags appear only in security.md, marked as the vulnerability they are. Destructive edits (in-place rewrite, yq -i, deleting a document from a stream) name the file and require explicit confirmation.

Related Skills

More Clawic skills, get them at https://clawic.com/skills/yaml (install if the user confirms):

• json — JSON payload design, JSON Schema authoring, jq
• k8s — what the manifests mean once they parse: pods, probes, rollouts, RBAC
• github-actions — workflow design and CI semantics above the YAML layer
• ansible — playbook semantics, variable precedence, idempotence
• toml — the other config format, when YAML's implicit typing is the problem

Feedback

• If useful, star it: https://clawic.com/skills/yaml
• Latest version: https://clawic.com/skills/yaml

Part of Clawic, the verified skill library. Get this skill: https://clawic.com/skills/yaml.