aiskillstore/yaml-authoring
Create and validate YAML diagram files. Use when writing new diagrams or troubleshooting YAML syntax.
This is a copy. The original lives at comeonoliver/yaml-authoring.
npx skills add https://github.com/aiskillstore/marketplace --skill yaml-authoringversion: 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
Child nodes (with parent) can omit layout entirely for automatic positioning:
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:
x/y overrides auto-positioningx or only y (both or neither)The kind field uses a hierarchical format: category.type or category.subcategory.type
| Kind | Description |
|------|-------------|
| network.vpc | Virtual Private Cloud |
| network.subnet | Subnet within VPC |
| 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 |
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
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"
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
# 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
Error: Missing required field "version"
Error: Missing required field "docId"
Ensure version and docId are at the document root.
Error: Duplicate node id: "my-node"
Each node and edge must have a unique id.
Error: Edge must have an id
All edges require an id field.
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.
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.
Error: Node "child" references unknown parent: "missing-vpc"
Ensure parent references an existing container node.
Error: Edge references unknown node: "missing-id"
Ensure from and to reference existing node IDs.
Error: YAML parse error at line 5
Check indentation (2 spaces) and proper quoting.
user-api not n1parent to nest resources inside VPC/Subnet containersw and h in layoutlayout entirely for automatic grid positioning# for documentationkind field is flexible - use any string that makes sense for your architectureTake aiskillstore/yaml-authoring from the repository into ~/.claude/skills for personal
use, or into .claude/skills inside a project.
The agent identifies a skill by the name field in its header. Two skills with the
same name cannot sit side by side — one of them will be ignored.