Yaml Master

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): ${CLAUDE_SKILL_DIR}/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

Skill Assets

This directory contains static assets used by this skill.

Purpose

Assets can include:

• Configuration files (JSON, YAML)
• Data files
• Templates
• Schemas
• Test fixtures

Guidelines

• Keep assets small and focused
• Document asset purpose and format
• Use standard file formats
• Include schema validation where applicable

Common Asset Types

• config.json - Configuration templates
• schema.json - JSON schemas
• template.yaml - YAML templates
• test-data.json - Test fixtures

Skill References

This directory contains reference materials that enhance this skill's capabilities.

Purpose

References can include:

• Code examples
• Style guides
• Best practices documentation
• Template files
• Configuration examples

Guidelines

• Keep references concise and actionable
• Use markdown for documentation
• Include clear examples
• Link to external resources when appropriate

Types of References

• examples.md - Usage examples
• style-guide.md - Coding standards
• templates/ - Reusable templates
• patterns.md - Design patterns

YAML Master Agent

This skill provides automated assistance for yaml master tasks.

⚡ This skill activates AUTOMATICALLY when you work with YAML files!

Overview

This skill provides automated assistance for the described functionality.

Automatic Trigger Conditions

This skill proactively activates when Claude detects:

1. File Operations: Reading, writing, or editing .yaml or .yml files 2. Configuration Management: Working with Ansible, Kubernetes, Docker Compose, GitHub Actions 3. CI/CD Workflows: GitLab CI, CircleCI, Travis CI, Azure Pipelines configurations 4. Schema Validation: Validating configuration files against schemas 5. Format Conversion: Converting between YAML, JSON, TOML, XML formats 6. User Requests: Explicit mentions of "yaml", "validate yaml", "fix yaml syntax", "convert yaml"

No commands needed! Just work with YAML files naturally, and this skill activates automatically.

---

Core Capabilities

1. Intelligent YAML Validation

What It Does:

• Detects syntax errors (indentation, duplicate keys, invalid scalars)
• Validates against YAML 1.2 specification
• Identifies common anti-patterns (tabs vs spaces, anchors/aliases issues)
• Provides detailed error messages with line numbers and fix suggestions

Example:

# ❌ INVALID YAML
services:
  web:
    image: nginx
	  ports:  # Mixed tabs and spaces - ERROR!
      - "80:80"

Agent Action: Automatically detects mixed indentation, suggests fix:

# ✅ FIXED YAML
services:
  web:
    image: nginx
    ports:  # Consistent 2-space indentation
      - "80:80"

2. Schema Inference & Generation

What It Does:

• Analyzes YAML structure and infers JSON Schema
• Generates OpenAPI/Swagger schemas from YAML
• Creates type definitions for TypeScript/Python from YAML configs
• Validates instances against inferred or provided schemas

Example:

# Input YAML
user:
  name: Jeremy
  age: 35
  roles:
    - admin
    - developer

Agent Action: Infers schema:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "user": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "age": { "type": "integer" },
        "roles": {
          "type": "array",
          "items": { "type": "string" }
        }
      },
      "required": ["name", "age", "roles"]
    }
  }
}

3. Format Conversion (YAML ↔ JSON ↔ TOML ↔ XML)

What It Does:

• Bidirectional conversion between YAML, JSON, TOML, XML
• Preserves comments when possible (YAML ↔ TOML)
• Handles complex nested structures, arrays, anchors/aliases
• Validates converted output maintains semantic equivalence

Example - YAML to JSON:

# config.yaml
database:
  host: localhost
  port: 5432
  credentials: &creds
    user: admin
    pass: secret

Agent Action: Converts to JSON:

{
  "database": {
    "host": "localhost",
    "port": 5432,
    "credentials": {
      "user": "admin",
      "pass": "secret"
    }
  }
}

4. Kubernetes Manifest Expertise

What It Does:

• Validates K8s manifests against API versions
• Suggests best practices (resource limits, labels, health checks)
• Detects security issues (privileged containers, root users)
• Generates complete manifests from minimal specs

Example:

# Minimal input
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx

Agent Action: Expands with best practices:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
  labels:
    app: nginx
    version: "1.0"
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
        version: "1.0"
    spec:
      containers:
      - name: nginx
        image: nginx:1.25-alpine
        ports:
        - containerPort: 80
          name: http
        resources:
          requests:
            memory: "64Mi"
            cpu: "250m"
          limits:
            memory: "128Mi"
            cpu: "500m"
        livenessProbe:
          httpGet:
            path: /
            port: 80
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /
            port: 80
          initialDelaySeconds: 5
          periodSeconds: 5
        securityContext:
          runAsNonRoot: true
          runAsUser: 1000
          allowPrivilegeEscalation: false

5. Docker Compose Optimization

What It Does:

• Validates Docker Compose syntax (v2.x, v3.x)
• Suggests networking best practices
• Optimizes volume mounts and environment variables
• Detects security misconfigurations

Example:

# ❌ SUBOPTIMAL
version: '3'
services:
  db:
    image: postgres
    environment:
      POSTGRES_PASSWORD: admin123  # Hardcoded secret!

Agent Action: Suggests secure alternative:

# ✅ OPTIMIZED
version: '3.8'
services:
  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_PASSWORD_FILE: /run/secrets/db_password
    secrets:
      - db_password
    volumes:
      - db_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped

secrets:
  db_password:
    file: ./secrets/db_password.txt

volumes:
  db_data:
    driver: local

6. CI/CD Pipeline Intelligence

What It Does:

• Validates GitHub Actions, GitLab CI, CircleCI workflows
• Suggests caching strategies for faster builds
• Detects matrix build inefficiencies
• Optimizes job dependencies and parallelization

Example - GitHub Actions:

# ❌ INEFFICIENT
name: CI
on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install  # No caching!
      - run: npm test

Agent Action: Optimizes with caching:

# ✅ OPTIMIZED
name: CI
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [18, 20, 22]
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: 'npm'

      - name: Install dependencies
        run: npm ci  # Faster than npm install

      - name: Run tests
        run: npm test

      - name: Upload coverage
        if: matrix.node-version == 20
        uses: codecov/codecov-action@v4

7. YAML Linting & Style Enforcement

What It Does:

• Enforces consistent indentation (2 spaces, 4 spaces, tabs)
• Validates key ordering (alphabetical, custom)
• Detects trailing whitespace, missing newlines
• Suggests canonical YAML representations

Linting Rules:

# Rule 1: Consistent 2-space indentation
# Rule 2: No duplicate keys
# Rule 3: Quoted strings for special characters
# Rule 4: Explicit document markers (---, ...)
# Rule 5: No tabs, only spaces
# Rule 6: Max line length 120 characters
# Rule 7: Comments aligned at column 40

8. Anchors & Aliases Mastery

What It Does:

• Manages complex YAML anchors and aliases
• Suggests reusable configurations with merge keys
• Validates anchor references
• Refactors duplicate blocks into anchors

Example:

# ❌ REPETITIVE
services:
  web:
    image: nginx
    restart: always
    logging:
      driver: json-file
      options:
        max-size: "10m"
  api:
    image: node:20
    restart: always
    logging:
      driver: json-file
      options:
        max-size: "10m"

Agent Action: Refactors with anchors:

# ✅ DRY (Don't Repeat Yourself)
x-common-config: &common-config
  restart: always
  logging:
    driver: json-file
    options:
      max-size: "10m"

services:
  web:
    <<: *common-config
    image: nginx

  api:
    <<: *common-config
    image: node:20

---

Advanced Features

Multi-Document YAML Handling

Works with YAML files containing multiple documents:

---
apiVersion: v1
kind: Service
metadata:
  name: nginx-service
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
---

Agent Action: Validates each document independently, ensures consistency across documents.

Environment-Specific Configurations

Manages environment overrides and templates:

# base.yaml
database: &db
  host: localhost
  port: 5432

# production.yaml (inherits from base)
database:
  <<: *db
  host: prod-db.example.com
  ssl: true

Complex Data Type Handling

Supports advanced YAML data types:

# Timestamps
created_at: 2025-10-24T23:00:00Z

# Binary data (base64)
ssl_cert: !!binary |
  R0lGODlhDAAMAIQAAP//9/X
  17unp5WZmZgAAAOfn515eXv

# Null values
optional_field: null
another_null: ~

# Custom tags
color: !rgb [255, 128, 0]

---

Common Use Cases

1. Fixing Broken YAML Files

User: "My Kubernetes manifest won't apply, fix it"

Agent Action: 1. Reads the YAML file 2. Identifies syntax errors (indentation, missing fields) 3. Validates against Kubernetes API schema 4. Provides corrected version with explanations

2. Converting JSON API Response to YAML Config

User: "Convert this JSON to YAML for my config file"

Agent Action: 1. Parses JSON input 2. Converts to idiomatic YAML (multi-line strings, minimal quotes) 3. Adds helpful comments 4. Validates output

3. Generating Docker Compose from Requirements

User: "Create docker-compose.yaml for nginx + postgres + redis"

Agent Action: 1. Generates complete docker-compose.yaml 2. Adds healthchecks, volumes, networks 3. Includes environment variable templates 4. Suggests .env file structure

4. Optimizing CI/CD Pipeline

User: "My GitHub Actions workflow is slow, optimize it"

Agent Action: 1. Analyzes workflow YAML 2. Identifies bottlenecks (no caching, sequential jobs) 3. Suggests parallelization, caching strategies 4. Provides optimized workflow

---

Integration with Other Tools

Works Seamlessly With:

• yamllint: Validates against yamllint rules
• Kustomize: Handles Kustomization files
• Helm: Works with Helm chart values.yaml
• Ansible: Validates playbooks and roles
• OpenAPI/Swagger: Converts to/from OpenAPI specs
• JSON Schema: Validates against schemas
• Terraform: Converts YAML to HCL (experimental)

---

Error Handling & Troubleshooting

Common YAML Errors This Skill Fixes:

---

Best Practices Enforced

1. Indentation: Consistent 2-space indentation (configurable) 2. Quotes: Minimal quoting (only when necessary) 3. Comments: Descriptive comments for complex sections 4. Security: No hardcoded secrets, use secrets managers 5. Validation: Always validate against schemas 6. Documentation: Inline documentation for anchors/aliases 7. Versioning: Explicit version tags (Docker Compose, K8s API)

---

Performance Considerations

• Large Files: Streams YAML instead of loading entire file into memory
• Validation: Incremental validation for real-time feedback
• Conversion: Optimized parsers for fast format conversion
• Caching: Caches schema validation results

---

Compliance & Standards

✅ YAML 1.2 Specification: Fully compliant ✅ YAML 1.1: Backward compatible where possible ✅ JSON Schema Draft 7: Supports schema validation ✅ OpenAPI 3.1: Compatible with OpenAPI specs ✅ Kubernetes API: Validates against all stable APIs ✅ Docker Compose v3.8: Full support for latest spec

---

Examples by Complexity

Beginner: Simple Config File

# app-config.yaml
app:
  name: MyApp
  version: 1.0.0
  environment: production

server:
  host: 0.0.0.0
  port: 8080

database:
  url: postgres://localhost:5432/mydb

Intermediate: Multi-Service Docker Compose

version: '3.8'

services:
  web:
    build: ./web
    ports:
      - "3000:3000"
    depends_on:
      - api
      - redis

  api:
    build: ./api
    environment:
      DATABASE_URL: postgres://db:5432/app
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:15-alpine
    volumes:
      - db_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD", "pg_isready"]
      interval: 5s

  redis:
    image: redis:7-alpine
    command: redis-server --appendonly yes

volumes:
  db_data:

Advanced: Kubernetes Deployment with Secrets

apiVersion: v1
kind: Secret
metadata:
  name: app-secrets
type: Opaque
stringData:
  DATABASE_URL: postgres://user:pass@db:5432/app
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: web-app
  labels:
    app: web
spec:
  replicas: 3
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
      - name: web
        image: myapp:latest
        envFrom:
        - secretRef:
            name: app-secrets
        resources:
          requests:
            memory: "128Mi"
            cpu: "100m"
          limits:
            memory: "256Mi"
            cpu: "500m"
        livenessProbe:
          httpGet:
            path: /health
            port: 8080
          initialDelaySeconds: 30
        readinessProbe:
          httpGet:
            path: /ready
            port: 8080
          initialDelaySeconds: 5
---
apiVersion: v1
kind: Service
metadata:
  name: web-service
spec:
  selector:
    app: web
  ports:
  - port: 80
    targetPort: 8080
  type: LoadBalancer

---

Troubleshooting Guide

Issue: "YAML won't parse"

Diagnosis: 1. Check indentation (tabs vs spaces) 2. Verify key-value separator (: with space after) 3. Look for duplicate keys

Issue: "Kubernetes apply fails"

Diagnosis: 1. Validate API version matches cluster version 2. Check required fields are present 3. Verify resource names are DNS-compliant

Issue: "Docker Compose won't start"

Diagnosis: 1. Check version compatibility 2. Validate service dependencies 3. Verify volume mount paths exist

---

Version History

• v1.0.0 (2025-10-24): Initial release with comprehensive YAML capabilities

---

License

MIT License - See LICENSE file

---

Support

• Issues: Report issues with YAML handling
• Documentation: This SKILL.md + plugin README
• Community: Share YAML tips and tricks

---

Credits

Author: Jeremy Longshore Plugin: 002-jeremy-yaml-master-agent Spec Compliance: Anthropic Agent Skills Spec v1.0

🤖 Generated with Claude Code

Co-Authored-By: Claude <noreply@anthropic.com>

Prerequisites

• Access to project files in ${CLAUDE_SKILL_DIR}/
• Required tools and dependencies installed
• Understanding of skill functionality
• Permissions for file operations

Instructions

1. Identify skill activation trigger and context 2. Gather required inputs and parameters 3. Execute skill workflow systematically 4. Validate outputs meet requirements 5. Handle errors and edge cases appropriately 6. Provide clear results and next steps

Output

• Primary deliverables based on skill purpose
• Status indicators and success metrics
• Generated files or configurations
• Reports and summaries as applicable
• Recommendations for follow-up actions

Error Handling

If execution fails:

• Verify prerequisites are met
• Check input parameters and formats
• Validate file paths and permissions
• Review error messages for root cause
• Consult documentation for troubleshooting

Resources

• Official documentation for related tools
• Best practices guides
• Example use cases and templates
• Community forums and support channels

Skill Scripts

This directory contains optional helper scripts that support this skill's functionality.

Purpose

Scripts here can be:

• Referenced by the skill for automation
• Used as examples for users
• Executed during skill activation

Guidelines

• All scripts should be well-documented
• Include usage examples in comments
• Make scripts executable (chmod +x)
• Use #!/bin/bash or #!/usr/bin/env python3 shebangs

Adding Scripts

1. Create script file (e.g., analyze.sh, process.py) 2. Add documentation header 3. Make executable: chmod +x script-name.sh 4. Test thoroughly before committing