Agent skill

yaml-authoring

Create and validate YAML diagram files. Use when writing new diagrams or troubleshooting YAML syntax.

View SKILL.md on GitHub Repository
Stars 232
Forks 15

Install this agent skill to your Project

npx add-skill https://github.com/aiskillstore/marketplace/tree/main/skills/7nohe/yaml-authoring

SKILL.md

YAML Diagram Authoring

Basic Structure

yaml
version: 1
docId: unique-document-id
title: "My Architecture Diagram"  # optional

nodes:
  - id: unique-id
    provider: aws  # Provider name (e.g., aws, gcp, azure)
    kind: compute.lambda  # Service category.type
    label: "Display Name"  # optional
    parent: container-id  # optional, for nesting in VPC/Subnet
    layout:  # optional for child nodes (auto-positioned)
      x: 100  # optional for child nodes
      y: 200  # optional for child nodes
      w: 200  # required for containers (VPC/Subnet)
      h: 150  # required for containers

edges:
  - id: edge-1
    from: source-node-id
    to: target-node-id
    label: "optional label"  # optional

Auto-Layout

Child nodes (with parent) can omit layout entirely for automatic positioning:

yaml
nodes:
  - id: vpc
    provider: aws
    kind: network.vpc
    layout: { x: 0, y: 0, w: 800, h: 600 }  # Container: explicit layout

  - id: ec2_1
    provider: aws
    kind: compute.ec2
    parent: vpc
    # No layout - auto-positioned at (40, 40)

  - id: ec2_2
    provider: aws
    kind: compute.ec2
    parent: vpc
    # No layout - auto-positioned at (200, 40)

Auto-layout rules:

  • 3 columns per row
  • 60px padding, 160px horizontal spacing, 140px vertical spacing
  • Explicit x/y overrides auto-positioning
  • Cannot specify only x or only y (both or neither)

Node Kind Categories

The kind field uses a hierarchical format: category.type or category.subcategory.type

Container Types (require w/h in layout)

Kind Description
network.vpc Virtual Private Cloud
network.subnet Subnet within VPC

Resource Types

Category Kind Examples
compute compute.lambda, compute.ec2, compute.ecs, compute.eks
compute.lb compute.lb.alb, compute.lb.nlb, compute.lb.elb
database database.dynamodb, database.rds, database.aurora
storage storage.s3, storage.efs, storage.ebs
integration integration.apiGateway, integration.sns, integration.sqs, integration.eventBridge
security security.iam, security.cognito, security.waf
analytics analytics.kinesis, analytics.athena, analytics.glue

Examples

Simple Lambda + S3

yaml
version: 1
docId: lambda-s3-example
title: "Lambda S3 Integration"

nodes:
  - id: fn
    provider: aws
    kind: compute.lambda
    label: "Process Upload"
    layout:
      x: 100
      y: 100
  - id: bucket
    provider: aws
    kind: storage.s3
    label: "uploads-bucket"
    layout:
      x: 300
      y: 100

edges:
  - id: fn-to-bucket
    from: fn
    to: bucket

API with Database

yaml
version: 1
docId: api-db-example
title: "REST API Architecture"

nodes:
  - id: api
    provider: aws
    kind: integration.apiGateway
    label: "REST API"
    layout:
      x: 100
      y: 200
  - id: handler
    provider: aws
    kind: compute.lambda
    label: "Handler"
    layout:
      x: 300
      y: 200
  - id: db
    provider: aws
    kind: database.dynamodb
    label: "Users Table"
    layout:
      x: 500
      y: 200

edges:
  - id: api-to-handler
    from: api
    to: handler
    label: "invoke"
  - id: handler-to-db
    from: handler
    to: db
    label: "read/write"

VPC with Nested Resources

yaml
version: 1
docId: vpc-example
title: "VPC Architecture"

nodes:
  - id: vpc
    provider: aws
    kind: network.vpc
    label: "Production VPC"
    layout:
      x: 50
      y: 50
      w: 600
      h: 400
  - id: public-subnet
    provider: aws
    kind: network.subnet
    label: "Public Subnet"
    parent: vpc
    layout:
      x: 70
      y: 100
      w: 250
      h: 300
  - id: alb
    provider: aws
    kind: compute.lb.alb
    label: "Application LB"
    parent: public-subnet
    layout:
      x: 100
      y: 150
  - id: lambda
    provider: aws
    kind: compute.lambda
    label: "API Handler"
    parent: public-subnet
    layout:
      x: 100
      y: 280

edges:
  - id: alb-to-lambda
    from: alb
    to: lambda

Validation

bash
# Validate and build to JSON
bun run packages/cli/src/index.ts build diagram.yaml

# Serve with live reload (default port: 3456)
bun run packages/cli/src/index.ts serve diagram.yaml

Common Errors

Missing Required Fields

Error: Missing required field "version"
Error: Missing required field "docId"

Ensure version and docId are at the document root.

Duplicate IDs

Error: Duplicate node id: "my-node"

Each node and edge must have a unique id.

Missing Edge ID

Error: Edge must have an id

All edges require an id field.

Missing Layout

Error: layout is required for top-level nodes
Error: layout.x is required for top-level nodes

Top-level nodes (without parent) must have a layout with x and y. Child nodes can omit layout for auto-positioning.

Partial Coordinates

Error: layout.x and layout.y must be both specified or both omitted

You cannot specify only x or only y. Either provide both, or omit both for auto-layout.

Invalid Parent Reference

Error: Node "child" references unknown parent: "missing-vpc"

Ensure parent references an existing container node.

Missing Edge Target

Error: Edge references unknown node: "missing-id"

Ensure from and to reference existing node IDs.

YAML Syntax Error

Error: YAML parse error at line 5

Check indentation (2 spaces) and proper quoting.

Tips

  • Use descriptive IDs: user-api not n1
  • Labels can include spaces and special characters (use quotes)
  • Use parent to nest resources inside VPC/Subnet containers
  • Container nodes (VPC, Subnet) require w and h in layout
  • Child nodes can omit layout entirely for automatic grid positioning
  • Use comments with # for documentation
  • The kind field is flexible - use any string that makes sense for your architecture

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

aiskillstore/marketplace

perigon-backend

Perigon ASP.NET Core + EF Core + Aspire conventions

232 15
Explore
aiskillstore/marketplace

perigon-agent

Pointers for Copilot/agents to apply Perigon conventions

232 15
Explore
aiskillstore/marketplace

perigon-angular

Angular 21+ standalone/Material/signal conventions for Perigon WebApp

232 15
Explore
aiskillstore/marketplace

fastapi-mastery

Comprehensive FastAPI development skill covering REST API creation, routing, request/response handling, validation, authentication, database integration, middleware, and deployment. Use when working with FastAPI projects, building APIs, implementing CRUD operations, setting up authentication/authorization, integrating databases (SQL/NoSQL), adding middleware, handling WebSockets, or deploying FastAPI applications. Triggered by requests involving .py files with FastAPI code, API endpoint creation, Pydantic models, or FastAPI-specific features.

232 15
Explore
aiskillstore/marketplace

context7-efficient

Token-efficient library documentation fetcher using Context7 MCP with 86.8% token savings through intelligent shell pipeline filtering. Fetches code examples, API references, and best practices for JavaScript, Python, Go, Rust, and other libraries. Use when users ask about library documentation, need code examples, want API usage patterns, are learning a new framework, need syntax reference, or troubleshooting with library-specific information. Triggers include questions like "Show me React hooks", "How do I use Prisma", "What's the Next.js routing syntax", or any request for library/framework documentation.

232 15
Explore
aiskillstore/marketplace

browser-use

Browser automation using Playwright MCP. Navigate websites, fill forms, click elements, take screenshots, and extract data. Use when tasks require web browsing, form submission, web scraping, UI testing, or any browser interaction.

232 15
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results