likec4-dsl

LikeC4 DSL Skill

Architecture-as-code tool. Describe systems in .c4/.likec4 files and LikeC4 generates interactive diagrams.

Rules

1. Projects - it is possible to have multiple likec4 projects in a workspace, project is determined by presence of a config file (.likec4rc, likec4.config.{ts,js,json}). LikeC4 files belong to the project of the nearest config file in the directory hierarchy.
2. Top-level statements — only import, specification, model, deployment, views, global are allowed. Blocks can repeat, but at least one per file must be present.
3. Multi-file merge — Top-level blocks across files are merged. For example, model { ... } blocks present in multiple files, parsed separately, and then merged into a single model.
4. Strings — 'single', "double" — all support multi-line. Escape quotes with backslash: \' or \". In a title, escape \/ to include a literal / without it being read as a view-folder separator.
5. Markdown — properties like summary/description/notes can contain Markdown. Use triple quotes ''' or """. Begin a new line after opening quotes and indent Markdown content for better formatting and syntax highlighting.
6. Comments — // single line and /* multi-line */ comments supported anywhere.
7. Identifier — letters, digits, hyphens, underscores only. No dots (dots are FQN separators). Can't start with a digit. Examples: customer, payment-service, frontendApp, queue-1. Critical: payment-api is valid; payment.api is NOT an identifier (dots separate FQN hierarchy). See references/identifier-validity.md.
8. FQN — Fully Qualified Name (FQN) is a dot-separated path to an element, MUST be unique within the project. Examples: customer, saas.backend.payment-service.paymentsApi, infra.eu.zone1.node1.
9. References — LikeC4 has lexical scoping with hoisting, nested scope may shadow outer, like in JavaScript. That scope does not carry across files: even with imports/includes in the same project, cross-file references must use full FQNs. Tiny reminder: backend.api does not survive a file boundary; across files write the full path such as cloud.backend.api.

Response Discipline (critical for evals)

• If prompt says "minimal", "paste-ready", "strict", "exact", or requires a specific first line, output exactly one final command/snippet/verdict token first (no alternatives, no fallback variants, no extra preamble).
• Do not add unrequested title, labels, alternate snippets, or long explanations unless explicitly asked.
• Prefer exact requested tokens/phrases in the first line when the prompt requires strict phrasing.
• For strict command prompts, avoid ambiguous wording like "equivalent command" unless prompt explicitly asks for alternatives.
• If the task is snippet-first or command-first, a prose-only answer is a failure even if the explanation is knowledgeable.

CLI Canonical Contracts (anti-substitution guardrails)

• Validate family: use likec4 validate (never substitute with check, lint, or build).
• Export family: use likec4 export (never substitute with other command families).
• Validation flags contract for strict evals: --json --no-layout --file <path> ... <project-dir>.
• Multi-file validation contract: repeat --file once per edited .c4 / .likec4 source file.
• Export output flags contract: prefer --outdir or -o (avoid invented aliases).

Exact Syntax Guardrails (high-signal only)

Deployment snippets

• If the prompt asks for named deployment instances, use IDENTIFIER = instanceOf ELEMENT_ID.
• Do not substitute anonymous instanceOf ELEMENT_ID lines when naming is required.
• If the prompt asks for a full fixture, keep the minimal executable structure: specification, model, deployment, and views.

Relationship-extension matchers

• Relationship identity is matched by source + target + kind (+ title when needed).
• If typed relationships exist, omitting KIND is wrong for strict disambiguation prompts.
• If multiple relationships share source/target/kind, include the title in the matcher.
• Do not "simplify" a typed matcher to extend SOURCE -> TARGET ... when the prompt is testing exact relationship identity.

Triage anchor when typed alternatives coexist:

// Existing relationships
api -[async]-> queue "publishes"
api -[sync]-> queue "publishes"
 
// ✅ Correct: exact relationship selected
extend api -[async]

Compact ambiguity rule:

• Ambiguous — kind omitted while multiple typed relationships share the same source/target/title family and you are only explaining why the matcher is underspecified.
• Wrong — kind omitted when the task asks for the final matcher/snippet for a specific async/sync relationship.

Workflow

1. (Required) Find existing or create new project config (section below). Directory with project config defines the scope for all LikeC4 files in that directory and subdirectories. Ask user if you are uncertain about the scope.
2. (Required) Find existing or create new specification { ... }, this enables what kinds of elements/deployments/relationships/tags you can use. See Specification section below.
3. Architecture elements and relationships are defined in model { ... } block. See Model section below.
4. Deployment topology is defined in deployment { ... } block. See Deployment section below.
5. Views (diagrams) are defined in views { ... } block. See Views section below.
6. After editing LikeC4 files, validate with the CLI

Generate → Self-check → Finalize

For strict command/snippet prompts, keep a compact loop:

1. Generate only the requested final command/snippet.
2. Self-check quickly:

• exact command family / required flags / repeated --file count
• snippet-first or first-line contract satisfied
• predicate semantics (*, _, **) stated precisely
• scope / FQN correctness
• deployment naming requirement satisfied
• relationship matcher specificity (kind, title when needed)
• dynamic view exactness: return arrows, chain form, single parallel block when requested, flow-control block placement (alt branches, no nested parallel, try/catch/finally order)

3. Finalize by fixing in place (no extra alternatives unless explicitly requested).

Before final answer, verify the required tokens are literally present when the prompt depends on them (examples: --no-layout, instanceOf, variant sequence, global predicate, -[async]->, parallel {, alt {, when, try {, <-).

Never claim CLI execution happened unless it actually ran.

Validation

Runtime launchers are equivalent for this command family:

• --json — structured output (stdout), logging goes to stderr
• --no-layout — skip layout drift checks (faster, only syntax+semantic)
• --file <path> — use with --json to scope results to the edited files. Without --json, text output still prints all diagnostics. Repeat once per edited source file.
• <project-dir> — path to the project directory
• There is no likec4 check command; use likec4 validate.

For evals/gradings/executions, be runner-tolerant (npx/bunx/pnpm dlx), and judge correctness by subcommand + flags + project scope.

If workspace already has likec4 as a dependency, check its version from package.json and ensure it is at least 1.53.0. If pinning is needed, use the active runner (npx/bunx/pnpm dlx) with likec4@1.53.0.

Example output:

Broken specification/model in a large project can cascade into lots of errors across all files. Always use --file to focus on the files you edited. If filteredErrors is 0 but totalErrors is high, your files are clean but something else in the project is broken (not your problem). Selfcheck that filteredFiles matches the number of files you passed to --file.

Field semantics (must be explicit in answers):

• filteredFiles: count of files actually included by repeated --file filters
• filteredErrors: errors in the filtered subset only
• totalErrors: errors across the full project model

Example edge case: if you pass 3 files but one is likec4.config.json, filteredFiles may be 2 because config JSON is not a .c4/.likec4 source file for DSL validation.

Export PNG flags (precision)

Canonical output directory flags:

• --outdir (long form)
• -o (short form)

Do not invent flags like --out-dir. Depending on LikeC4 version, --output may appear as compatibility alias; prefer --outdir/-o for deterministic answers.

Full CLI reference → references/cli.md

Canonical Snippets for High-Variance Families

Use these as exactness anchors when the prompt is testing syntax, not broad explanation.

predicateGroup reusable predicate

Deployment fixture with named instances

Scoped include semantics

Interpretation anchor: in a scoped view, include * means the scoped element plus its direct children as the base include set; neighbors can still appear through scoped relationship visibility.

Metadata predicates

Truth card:

• Array containment: metadata.regions is "eu" matches if the array contains "eu".
• Scope: unqualified metadata.* filters the matched element or relationship itself; source.metadata.* / target.metadata.* filters endpoints.
• Deployment views: instance tags are cumulative; instance metadata replaces logical metadata as a whole when present, otherwise logical metadata is the fallback.

Deployment-view styling guardrail

For strict repair prompts about deployment views, the safe answer is local style ... {} inside the deployment view.

Mini-reminder: in deployment views, treat include ... with {} and global style ... as unsupported repair patterns. Use a local style ... {} rule inside the deployment view instead.

LikeC4 Project Configuration

Config file (likec4.config.json, .likec4rc, or likec4.config.{ts,js}) defines a project. Its location sets the project scope (LikeC4 files belong to the project of the nearest config file in the directory hierarchy).

Key options: name (required, unique ID in the workspace), title (display name) Full reference → references/configuration.md

Specification

Defines all named vocabularies: element kinds, deployment node kinds, relationship kinds, tags, and custom color tokens. Must appear before those kinds are used in model or deployment blocks.

Key reminders: all definitions are global across files; duplicate kind/tag identifiers cause a validation error; specification changes trigger a full project re-parse — keep it in a dedicated spec.c4 file.

Full syntax, options per kind, and worked example → references/specification.md

Model

Hierarchical structure of elements and relationships. Elements have a kind (from specification), a unique identifier within their parent, and optional properties and nested elements.

Key reminders: this/it aliases the current element in nested relationships; cross-file references require full FQN; parent-child direct relationships are forbidden; extend FQN { } merges tags, metadata, and links into an existing element without redefining it.

Full syntax, extend patterns, property table, and worked example → references/model.md

Style

Style properties control visual appearance: color, shape, border, opacity, size, padding, textSize, icon, iconColor, iconSize, iconPosition, multiple. Relationship style extends this with line, head, and tail arrow shapes.

Full color token table, all shape values, border/opacity/size tokens, icon pack prefixes (aws:, azure:, gcp:, tech:, bootstrap:), and correct usage patterns → references/style-tokens-colors.md

To discover available icons, use the CLI: likec4 list-icons (text, one per line). Filter by group with --group <name>. Icon groups and approximate counts: aws (~307), azure (~614), gcp (~216), tech (~2000), bootstrap (~2051) (see references/cli.md for details).

Deployment

Maps logical model elements to physical infrastructure nodes using instanceOf. Uses deploymentNode kinds from specification. Inherits all logical model relationships automatically; additional deployment-level relationships can be defined inline.

Named vs. anonymous instances, multi-environment fixture, deployment relationships, and deployment filter metadata rules → references/deployment.md

Views

Three view types: element views (view id or view id of element), dynamic views (dynamic view id), deployment views (deployment view id). View properties: title, description, metadata, link.

Include/exclude predicates, view-level style rules, groups, autoLayout, extends, navigateTo, and global predicate groups → references/views.md

Quick Decision Trees

"I need incoming relationship predicates"

include -> X and include * -> X are related but not interchangeable in all contexts; prefer the exact form requested by user/eval.

Scoped Predicate Truth Card (*, _, **)

Hard rule: do not describe * as recursive; do not describe _ as wildcard-all; do not drop relationship-condition semantics for _ / **.

"I need to create a diagram/view or show a flow or sequence"

"I need to style ..."

"I need to organize across files"

"I need to show a flow or sequence"

Flow-control blocks (experimental) — all take an optional title and nest to any depth, except parallel/par which cannot nest. when/if/else are valid only directly inside alt; loop/opt/parallel/try cannot be a direct child of alt (nest them inside a branch). See references/dynamic-views.md.

Return-arrow precision:

• If the prompt asks for response arrows back out, prefer <- steps rather than replacing them with new forward arrows.
• If the prompt asks for a body on a specific hop in a chain, attach the block only to that hop.
• If the prompt asks for one fan-out, keep sibling actions in one parallel { ... } block instead of multiple one-step parallel blocks.

Anti-Patterns to Avoid in Strict Prompts

Common Mistakes & Debugging

When a model errors or an eval answer seems wrong, load references/troubleshooting.md which contains:

• Syntax errors — identifier format (dots forbidden in identifiers), unknown kinds, duplicate FQNs, malformed where predicates
• Model & Hierarchy — broken FQN references, parent-child relationship constraint, cross-file visibility
• View Predicates — * vs ** confusion, missing neighbor elements, WHERE case sensitivity
• Deployment — instanceOf FQN resolution, undefined deploymentNode kinds
• Dynamic Views — flow-control blocks (parallel/opt/loop/alt/try), alt-branch placement rules, no nested parallel, response arrow symmetry, exact variant sequence keyword
• Validation & Import — config not found, import path resolution, upstream error cascade
• Performance — spec in separate file, splitting large views
• 5-step debugging workflow — validation-first with --file, FQN integrity, predicate isolation, spec-first validation
• 7 Skill Best Practices — response discipline, relationship disambiguation, FQN usage, safe editing rules

Reference Index

Load a reference file when the task involves the corresponding topic. Claude reads SKILL.md first; these files are loaded on demand only when needed.