docs(skills): enhance LikeC4 DSL skill reference#2807
Merged
Conversation
|
Contributor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughLarge documentation and evaluation additions for the LikeC4 DSL: major rewrite of Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
Improve model examples with properties (metadata, links, icons, style blocks), clarify extend relationship disambiguation, add custom color specification, and update property/style reference tables for accuracy.
7e110ae to
fbd84bc
Compare
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
--outdir and --output are both valid aliases for -o, so the previous entry incorrectly listed a valid flag as a mistake. Changed to --out-dir which is a genuinely invalid flag. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
Closed
- tighten strict response discipline and canonical CLI contracts - add focused reference docs for specification/model/deployment/dynamic views - add public eval set + grading spec for high-variance syntax cases - fix malformed trailing block in dynamic-views reference
Contributor
There was a problem hiding this comment.
Actionable comments posted: 4
🧹 Nitpick comments (1)
skills/likec4-dsl/references/include-predicates-wildcards.md (1)
160-163: Fix the self-canceling row in the “Common mistakes” table.At Line 162, the “Wrong” and “Right” examples are effectively the same, so this row doesn’t demonstrate an actual mistake. Consider removing it or replacing the left side with a genuinely incorrect form.
✏️ Suggested cleanup
| Wrong | Right | Why | |---|---|---| -| `include * where kind is app` in unscoped view | `include * where kind is app` (same) | Correct as written | | `include **` expecting only immediate children | `include *` | `**` is recursive; use `*` for one level |🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@skills/likec4-dsl/references/include-predicates-wildcards.md` around lines 160 - 163, The table's "Common mistakes" row showing "`include * where kind is app`" as both Wrong and Right is self-canceling; update the table by either removing that row or replacing the "Wrong" cell with a genuinely incorrect example (e.g., a mis-scoped or syntactically invalid form such as "`include ** where kind is app`" or "`include * where kind = app`") so the pair contrasts with the correct "`include * where kind is app`" in the "Right" cell and clearly demonstrates the mistake; locate the row containing the "`include * where kind is app`" text to make the change.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@skills/likec4-dsl/references/specification.md`:
- Line 76: The file ends with an unmatched closing code fence (a stray triple
backtick) on the final line; remove that trailing ``` so there are no unmatched
Markdown code fences (verify there is no intended code block content following
the example table/row and delete the lone fence at EOF).
In `@skills/likec4-dsl/references/troubleshooting.md`:
- Around line 54-58: Update the troubleshooting line about `--file` to make
clear that file-level scoping is only applied to the JSON output and not to text
output: change the text to instruct users to run the validator with `--json
--no-layout` and then inspect `filteredErrors`/`filteredFiles` in the JSON to
get per-file scoping; reference the CLI implementation in
packages/likec4/src/cli/validate/index.ts where text mode intentionally prints
all diagnostics and `--file` affects JSON semantics only.
In `@skills/likec4-dsl/SKILL.md`:
- Line 18: Update the identifier examples to fix the typo: replace the incorrect
example string "quque-1" with "queue-1" in the Identifier examples section (the
example list that currently includes `customer`, `payment-service`,
`frontendApp`, `quque-1`), leaving the rest of the sentence and formatting
unchanged.
- Around line 117-120: Update the `--file <path>` bullet to state that the
file-scoping applies to JSON output only (i.e., it limits fields, summaries, and
exit behavior when `--json` is used) and clarify that in text mode the CLI
intentionally still prints all diagnostics; reference the CLI implementation in
packages/likec4/src/cli/validate/index.ts and the `--file` flag usage so readers
know the asymmetry is by design.
---
Nitpick comments:
In `@skills/likec4-dsl/references/include-predicates-wildcards.md`:
- Around line 160-163: The table's "Common mistakes" row showing "`include *
where kind is app`" as both Wrong and Right is self-canceling; update the table
by either removing that row or replacing the "Wrong" cell with a genuinely
incorrect example (e.g., a mis-scoped or syntactically invalid form such as
"`include ** where kind is app`" or "`include * where kind = app`") so the pair
contrasts with the correct "`include * where kind is app`" in the "Right" cell
and clearly demonstrates the mistake; locate the row containing the "`include *
where kind is app`" text to make the change.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 8511015f-493c-44d1-a79a-148405b8b92e
📒 Files selected for processing (12)
skills/likec4-dsl/SKILL.mdskills/likec4-dsl/evals/evals-public.jsonskills/likec4-dsl/evals/grading-spec.jsonskills/likec4-dsl/references/deployment.mdskills/likec4-dsl/references/dynamic-views.mdskills/likec4-dsl/references/identifier-validity.mdskills/likec4-dsl/references/include-predicates-wildcards.mdskills/likec4-dsl/references/model.mdskills/likec4-dsl/references/relationships-bidirectional.mdskills/likec4-dsl/references/specification.mdskills/likec4-dsl/references/style-tokens-colors.mdskills/likec4-dsl/references/troubleshooting.md
✅ Files skipped from review due to trivial changes (3)
- skills/likec4-dsl/references/relationships-bidirectional.md
- skills/likec4-dsl/evals/grading-spec.json
- skills/likec4-dsl/references/model.md
| | Duplicate tag or kind identifier | Each identifier must be unique within its type category | | ||
| | `#tag` in specification argument | Tags are defined without `#`; they are used with `#` elsewhere: `tag critical` → `#critical` | | ||
| | Raw hex color in style | Define a named color token first: `color my-blue #003366`, then use `color my-blue` in styles | | ||
| ``` |
Contributor
There was a problem hiding this comment.
Remove the stray fence marker at EOF.
Line 76 contains an extra ``` with no matching block content, which can break markdown rendering.
🧹 Minimal fix
-| Raw hex color in style | Define a named color token first: `color my-blue `#003366``, then use `color my-blue` in styles |
-```
+| Raw hex color in style | Define a named color token first: `color my-blue `#003366``, then use `color my-blue` in styles |🧰 Tools
🪛 markdownlint-cli2 (0.22.0)
[warning] 76-76: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@skills/likec4-dsl/references/specification.md` at line 76, The file ends with
an unmatched closing code fence (a stray triple backtick) on the final line;
remove that trailing ``` so there are no unmatched Markdown code fences (verify
there is no intended code block content following the example table/row and
delete the lone fence at EOF).
Comment on lines
+54
to
+58
| | `validate` reports config not found | Ensure `likec4.config.json` exists in the project root directory | | ||
| | Imported file shows "Module not resolved" | Use correct relative path: `import { x } from './path/to/file.c4'` | | ||
| | Symbol from import invisible in model | Symbol must be public (defined at top level); nested elements need FQN | | ||
| | Large error count in project but your file is clean | Use `--file <edited-file>` to filter; upstream errors are not your responsibility | | ||
|
|
Contributor
There was a problem hiding this comment.
Clarify that --file scoping is reliable in JSON output, not plain text output.
Line 57 currently reads as if --file alone filters what is printed. To avoid confusion, point readers to --json --no-layout + filteredErrors/filteredFiles when claiming file-level scoping.
🛠️ Suggested wording update
-| Large error count in project but your file is clean | Use `--file <edited-file>` to filter; upstream errors are not your responsibility |
+| Large error count in project but your file is clean | Use `likec4 validate --json --no-layout --file <edited-file> <project-dir>` and check `filteredErrors`/`filteredFiles`; text mode may still print upstream diagnostics |Based on learnings, in packages/likec4/src/cli/validate/index.ts, text mode intentionally prints all diagnostics and --file fully scopes JSON output semantics.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@skills/likec4-dsl/references/troubleshooting.md` around lines 54 - 58, Update
the troubleshooting line about `--file` to make clear that file-level scoping is
only applied to the JSON output and not to text output: change the text to
instruct users to run the validator with `--json --no-layout` and then inspect
`filteredErrors`/`filteredFiles` in the JSON to get per-file scoping; reference
the CLI implementation in packages/likec4/src/cli/validate/index.ts where text
mode intentionally prints all diagnostics and `--file` affects JSON semantics
only.
This was referenced Apr 2, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Test plan
🤖 Generated with Claude Code