home / skills / jeremylongshore / claude-code-plugins-plus-skills / yaml-master

yaml-master skill

safe

/plugins/productivity/002-jeremy-yaml-master-agent/skills/yaml-master

This skill proactively validates, formats, and corrects YAML files, ensuring syntax correctness and schema conformance for Kubernetes, GitHub Actions, and

npx playbooks add skill jeremylongshore/claude-code-plugins-plus-skills --skill yaml-master

Review the files below or copy the command above to add this skill to your agents.

Files (5)

SKILL.md

2.5 KB

---
name: yaml-master
description: |
  Execute proactive YAML intelligence: automatically activates when working with YAML files.
  Use when appropriate context detected. Trigger with relevant phrases based on skill purpose.
  
allowed-tools: Read, Write, Edit, Grep, Glob, Bash(general:*), Bash(util:*)
version: 1.0.0
author: Jeremy Longshore <[email protected]>
license: MIT
---
# YAML Master

Proactive YAML intelligence: validate syntax, enforce consistent formatting, and keep configuration files schema-correct (Kubernetes, GitHub Actions, Docker Compose, and similar).

## Overview

This skill activates when working with `.yml`/`.yaml` files to detect structural issues early (indentation, anchors, type mismatches), and to produce safe, minimal edits that keep CI/config tooling happy.

## Prerequisites

- The YAML file(s) to inspect and their intended target (e.g., Kubernetes, GitHub Actions, Compose)
- Any relevant schema or constraints (when available)
- Permission to edit the file(s) (or to propose a patch)

## Instructions

1. Parse and validate YAML syntax (identify the first breaking error and its location).
2. Normalize formatting (indentation, quoting) without changing semantics.
3. Validate structure against the target system’s expectations (keys, types, required fields).
4. Identify risky patterns (duplicate keys, ambiguous scalars, anchors used incorrectly).
5. Output a minimal patch plus a short validation checklist (what to run next).

## Output

- Corrected YAML with minimal diffs
- A concise list of issues found (syntax vs schema vs best practice)
- Follow-up validation commands appropriate for the target (e.g., `kubectl apply --dry-run=client`, CI lint)

## Error Handling

- If the schema/target is unknown, ask for the target system and apply syntax-only fixes first.
- If the YAML is valid but tooling still fails, surface the exact downstream error and reconcile expectations.

## Examples

**Example: Fix an indentation/syntax error**
- Input: a workflow with a mis-indented `steps:` block.
- Output: corrected indentation and a note on which job/step was affected.

**Example: Convert JSON to YAML safely**
- Input: a JSON config blob.
- Output: YAML with explicit quoting where necessary to avoid type surprises.

## Resources

- Full detailed guide (kept for reference): `{baseDir}/references/SKILL.full.md`
- YAML spec: https://yaml.org/spec/
- GitHub Actions workflow syntax: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions

Overview

This skill provides proactive YAML intelligence that activates when working with .yml or .yaml files. It detects syntax and structural issues, enforces consistent formatting, and proposes minimal, safe edits to keep configuration tooling stable. Use it to catch indentation errors, ambiguous scalars, duplicate keys, and schema mismatches before they break CI or runtime systems.

How this skill works

The skill parses YAML to find the first breaking syntax error and reports its exact location. It normalizes formatting (indentation, quoting, line breaks) without changing semantics and validates structure against known targets like Kubernetes, GitHub Actions, or Docker Compose when a schema is available. It flags risky patterns (duplicate keys, anchors misused, ambiguous types), produces a minimal patch, and supplies a short validation checklist with suggested commands to run next.

When to use it

Editing or reviewing .yml or .yaml files in a repo
Preparing CI/CD configs (GitHub Actions, GitLab CI) for merge
Maintaining Kubernetes manifests or Helm templates
Converting JSON blobs to YAML or vice versa
Troubleshooting config-related errors from tooling or runtime

Best practices

Provide the intended target system (Kubernetes, Actions, Compose) or a schema for best validation results
Allow the skill to propose minimal edits and review diffs before applying changes
Keep YAML files small and modular to limit cascading validation errors
Use explicit quoting for values that might be interpreted as booleans or numbers
Run the suggested follow-up validation commands after applying fixes

Example use cases

Fix a mis-indented GitHub Actions workflow and get a compact diff plus the affected job/step noted
Normalize a Docker Compose file so services load consistently and preserve service types
Validate Kubernetes manifests against known API fields and required keys, with kubectl dry-run commands suggested
Convert an embedded JSON config to safe YAML with explicit quoting to avoid type surprises
Detect duplicate keys or ambiguous anchors in a long config and propose a minimal patch

FAQ

What if I don’t know the target system or schema?

If the target is unknown the skill performs syntax-first fixes and asks for the intended target so it can run schema-specific checks next.

Will the skill change semantics when normalizing formatting?

No. Formatting normalization is designed to be semantics-preserving; the skill focuses on minimal edits and highlights any change that could affect interpretation.