docs(skills): improve skill references based on benchmark feedback#2801
Conversation
Add Common Commands and Frequent Mistakes section to CLI reference. Expand variant sequence documentation with examples and common mistakes. Add wildcard comparison table for * vs ** in predicates. Emphasize importance in configuration reference.
|
📝 WalkthroughWalkthroughThe PR updates documentation in LikeC4 DSL reference files, adding sections on common CLI mistakes, configuration schema requirements, wildcard depth selectors, and sequence diagram syntax with direction arrows. No code logic or public API changes are introduced. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~15 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 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 |
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 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/cli.md`:
- Line 25: Remove the incorrect "npx likec4 export png --outdir ./images" row
from the Frequent Mistakes table (the row that claims the flag is `--outdir` but
short form is `-o`), since `outdir` is defined with aliases `['o','output']` and
`--outdir` is a valid long form; locate the table row by its contents (the
pipe-delimited line containing "npx likec4 export png --outdir ./images") and
delete that entire row so the table no longer contradicts the documented
"**export png** options: `--outdir` (`-o`)" entry.
🪄 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: 258382f5-6cf6-48b8-8901-8dfed899ca79
📒 Files selected for processing (4)
skills/likec4-dsl/references/cli.mdskills/likec4-dsl/references/configuration.mdskills/likec4-dsl/references/predicates.mdskills/likec4-dsl/references/views.md
| | `npx likec4 check ...` | Command doesn't exist | Use `npx likec4 validate ...` | | ||
| | `npx likec4 lint ...` | Command doesn't exist | Use `npx likec4 validate ...` | | ||
| | `npx likec4 verify ...` | Command doesn't exist | Use `npx likec4 validate ...` | | ||
| | `npx likec4 export png --outdir ./images` | Flag is `--outdir` but short form is `-o` | Use `-o ./images` or `--outdir ./images` | |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify export png command accepts --outdir
# Check the outdir option definition
rg -A10 "positional\('path'" packages/likec4/src/cli/export/png/handler.ts
# Check if there's any validation that rejects --outdir
rg "outdir" packages/likec4/src/cli/export/png/ -C3Repository: likec4/likec4
Length of output: 2628
Remove the export png "--outdir" row from the Frequent Mistakes table.
This row incorrectly lists npx likec4 export png --outdir ./images as a mistake. The code defines outdir with aliases ['o', 'output'], making --outdir the primary valid long form (alongside -o and --output as valid alternatives). Line 68 of this same file confirms this: **export png** options: --outdir (-o), ...
Remove this row from the table to eliminate the contradictory guidance.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@skills/likec4-dsl/references/cli.md` at line 25, Remove the incorrect "npx
likec4 export png --outdir ./images" row from the Frequent Mistakes table (the
row that claims the flag is `--outdir` but short form is `-o`), since `outdir`
is defined with aliases `['o','output']` and `--outdir` is a valid long form;
locate the table row by its contents (the pipe-delimited line containing "npx
likec4 export png --outdir ./images") and delete that entire row so the table no
longer contradicts the documented "**export png** options: `--outdir` (`-o`)"
entry.
| views { | ||
| // Selects ONLY: api, db (direct children of backend) | ||
| view direct-only { | ||
| include backend.* | ||
| } | ||
|
|
||
| // Selects: api, db, handlers, authHandler (all descendants) | ||
| view all-descendants { | ||
| include backend.** | ||
| } | ||
|
|
||
| // ❌ Common mistake: expecting * to include nested elements | ||
| view wrong-expectation { | ||
| include backend.* // This does NOT include handlers or authHandler! | ||
| style backend.handlers { color red } // handlers won't be styled | ||
| } | ||
|
|
||
| // ✅ Correct: use ** when you need all nested elements | ||
| view correct { | ||
| include backend.** // Includes everything under backend | ||
| style backend.handlers { color red } // Now handlers IS included | ||
| } | ||
| } | ||
| ``` |
There was a problem hiding this comment.
This behaviour is a bit different in deployment views. But this is a great description
| - Use `variant sequence` at the start of the dynamic view block | ||
| - Use `->` for forward/call direction | ||
| - Use `<-` for backward/return direction (not `->` with different semantics) | ||
| - Sequence diagrams work best with leaf elements (not containers) |
There was a problem hiding this comment.
This is unclear, though I know what it refers to : this note here. This sentence could be more affirmative of the correct behaviour
| **Common mistake:** Using `->` for returns instead of `<-`. The arrow direction indicates message flow: | ||
| - `a -> b` means "a sends to b" (request/call) | ||
| - `a <- b` means "b sends to a" (response/return) | ||
|
|
||
| ```likec4 | ||
| // ❌ WRONG - using -> for returns | ||
| dynamic view wrong { | ||
| variant sequence | ||
| client -> gateway "request" | ||
| gateway -> client "response" // This renders incorrectly! | ||
| } | ||
|
|
||
| // ✅ CORRECT - using <- for returns | ||
| dynamic view correct { | ||
| variant sequence | ||
| client -> gateway "request" | ||
| client <- gateway "response" // Proper return flow | ||
| } | ||
| ``` |
There was a problem hiding this comment.
Thats fine, I just feel like this is a matter of preference but ok as a best practice. The benchmark was a bit overly specific on this
|
I cannot push to your PR (should have been obvious to me), neither can I suggest changes on SKILL.md as this file is out of scope of the PR. Model is a hierarchical structure of elements, where each element can contain other elements. Element MUST have a kind (from the specification) and an identifier (also known as name). Identifier MUST be unique within its parent. Element may have a body Syntax: For relationship Example: Element properties: |
Summary
This PR improves the LikeC4 agent skill documentation based on comprehensive benchmark feedback from issue #2636.
Changes
CLI Reference (cli.md)
validatevscheck,lint,verify)@latesttag for npx commandsViews Reference (views.md)
->for returns<-for return flowsPredicates Reference (predicates.md)
*(direct children only) vs**(all descendants)Configuration Reference (configuration.md)
$schemainclusion$schemaBenchmark Impact
Based on the benchmark results from issue #2636, these changes address the key improvement areas:
validatenotcheck*vs**differenceTesting
The improved documentation has been structured to help AI agents:
Closes feedback loop from #2636
cc @davydkov @a-scolan