yaml-master

YAML Master Agent

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

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

Work

---

Content truncated.