spb/ultra-sharp-agent-skills Public

1---2name: processing-yaml3description: Creates, reads, modifies, and validates YAML files with Python. Use when the user asks to parse, edit, generate, or fix a .yaml or .yml file, mentions YAML syntax errors, or works with YAML-based config files such as docker-compose.yml, Kubernetes manifests, or GitHub Actions workflow files. Do not use for JSON files or for authoring the logic of CI pipelines — only the YAML file mechanics.4---56<!--7Author: Simon-Pierre Boucher8Contact: contact@spboucher.ai9-->1011# Processing YAML1213## When to use / when NOT to use14- **Use for:** creating, reading, editing, or validating `.yaml`/`.yml` files — app configs, docker-compose, Kubernetes manifests, CI workflow files (the file mechanics).15- **Do NOT use for:** JSON files (use `json` directly) or designing the *logic* of CI pipelines — this skill covers YAML file handling, not what the pipeline should do.1617## Quick reference1819**Default:** PyYAML (`pip install pyyaml`). **Escape hatch:** ruamel.yaml (`pip install ruamel.yaml`) only when comments and formatting must survive a round-trip edit — PyYAML discards them.2021```python22import yaml2324# Read — safe_load ONLY25with open("config.yaml") as f:26    data = yaml.safe_load(f)          # returns dict/list/scalars2728# Modify29data["server"]["port"] = 80803031# Write32with open("config.yaml", "w") as f:33    yaml.safe_dump(data, f, default_flow_style=False,34                   sort_keys=False, allow_unicode=True)35```3637**Comment-preserving edit (ruamel.yaml):**3839```python40from ruamel.yaml import YAML41y = YAML()                            # round-trip mode by default42doc = y.load(open("config.yaml"))43doc["server"]["port"] = 808044y.dump(doc, open("config.yaml", "w"))45```4647## Rules48- **NEVER `yaml.load()` without `SafeLoader`** — it executes arbitrary Python object constructors. `safe_load`/`safe_dump` always.49- Quote strings that YAML would reinterpret: `"no"`, `"on"`, `"yes"`, version strings like `"1.10"`, country codes like `"NO"`.50- 2-space indentation; never tabs (tabs are a YAML syntax error).51- If the file has comments the user wants kept, use ruamel.yaml — a PyYAML round-trip silently deletes them.5253## Workflow541. Determine the operation and whether comments/formatting must survive (→ ruamel.yaml).552. Parse with `yaml.safe_load`; on `yaml.YAMLError`, report its message with line/column verbatim and stop — do not guess.563. Modify the loaded structure (recipes in references/recipes.md), quoting ambiguous scalars.574. Write with `safe_dump(default_flow_style=False, sort_keys=False, allow_unicode=True)` to keep block style, key order, and non-ASCII text.585. **Validate:** re-parse the written file with `safe_load`; for multi-document files confirm document count is unchanged. Fix and repeat step 3 until clean.5960## Edge cases & failure modes61- **PyYAML missing** → `pip install pyyaml`; ruamel.yaml missing → `pip install ruamel.yaml`.62- **Malformed YAML** → relay the parser error (it includes line/column); common causes to mention: tabs, unquoted `:` in values, bad indentation.63- **Multi-document files** (`---` separators) → use `yaml.safe_load_all()` / `yaml.safe_dump_all()`; plain `safe_load` raises on the second document.64- **Encoding** → open files as UTF-8; `allow_unicode=True` on dump prevents `\uXXXX` escaping of accented text.65- **Huge files** → YAML has no practical streaming parser; for >50 MB data files, question whether the data belongs in YAML at all and suggest JSON/CSV.6667## References68Deeper copy-paste recipes (anchors, multi-doc, schema validation, JSON conversion): see [references/recipes.md](references/recipes.md).69