@intent-solutions-io/yaml-master

---
name: yaml-master
description: |
  PROACTIVE YAML INTELLIGENCE: Automatically activates when working with YAML files, configuration management,
  CI/CD pipelines, Kubernetes manifests, Docker Compose, or any YAML-based workflows. Provides intelligent
  validation, schema inference, linting, format conversion (JSON/TOML/XML), and structural transformations
  with deep understanding of YAML specifications and common anti-patterns.
allowed-tools: Read, Write, Edit, Grep, Glob, Bash
version: 1.0.0
---

# 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**:
```yaml
# ❌ INVALID YAML
services:
  web:
    image: nginx
	  ports:  # Mixed tabs and spaces - ERROR!
      - "80:80"
```

**Agent Action**: Automatically detects mixed indentation, suggests fix:
```yaml
# ✅ 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**:
```yaml
# Input YAML
user:
  name: Jeremy
  age: 35
  roles:
    - admin
    - developer
```

**Agent Action**: Infers schema:
```json
{
  "$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**:
```yaml
# config.yaml
database:
  host: localhost
  port: 5432
  credentials: &creds
    user: admin
    pass: secret
```

**Agent Action**: Converts to JSON:
```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**:
```yaml
# Minimal input
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
```

**Agent Action**: Expands with best practices:
```yaml
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**:
```yaml
# ❌ SUBOPTIMAL
version: '3'
services:
  db:
    image: postgres
    environment:
      POSTGRES_PASSWORD: admin123  # Hardcoded secret!
```

**Agent Action**: Suggests secure alternative:
```yaml
# ✅ 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**:
```yaml
# ❌ 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:
```yaml
# ✅ 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**:
```yaml
# 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**:
```yaml
# ❌ 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:
```yaml
# ✅ 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:

```yaml
---
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:

```yaml
# 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:

```yaml
# 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:

| Error | Cause | Fix |
|-------|-------|-----|
| `mapping values are not allowed here` | Incorrect indentation | Align keys properly |
| `found duplicate key` | Same key defined twice | Remove or rename duplicate |
| `expected <block end>, but found` | Tab instead of spaces | Replace tabs with spaces |
| `found undefined tag handle` | Custom tag without definition | Define tag or remove |
| `could not find expected ':'` | Missing colon after key | Add colon |

---

## 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

```yaml
# 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

```yaml
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

```yaml
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](https://claude.com/claude-code)

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