Skip to content

docs(skills): improve skill references based on benchmark feedback#2801

Merged
davydkov merged 1 commit into
likec4:mainfrom
vincent067:improve-skill-docs
Mar 27, 2026
Merged

docs(skills): improve skill references based on benchmark feedback#2801
davydkov merged 1 commit into
likec4:mainfrom
vincent067:improve-skill-docs

Conversation

@vincent067

Copy link
Copy Markdown
Contributor

Summary

This PR improves the LikeC4 agent skill documentation based on comprehensive benchmark feedback from issue #2636.

Changes

CLI Reference (cli.md)

  • Added Common Commands and Frequent Mistakes section with a comparison table
  • Documented correct commands vs common incorrect attempts (e.g., validate vs check, lint, verify)
  • Added recommendation to use @latest tag for npx commands

Views Reference (views.md)

  • Expanded variant sequence documentation with:
    • Clear syntax explanation
    • Common mistake example showing wrong use of -> for returns
    • Correct usage example with <- for return flows
    • Best practices for sequence diagrams

Predicates Reference (predicates.md)

  • Added detailed Wildcard depth selectors section
  • Added comparison table: * (direct children only) vs ** (all descendants)
  • Included practical examples showing common mistakes and correct usage
  • Explained relationship between selector and element styling

Configuration Reference (configuration.md)

  • Added Important callout emphasizing $schema inclusion
  • Added Common Mistake example showing config with/without schema
  • Clarified IDE benefits of including $schema

Benchmark Impact

Based on the benchmark results from issue #2636, these changes address the key improvement areas:

  1. P1 (Critical): CLI command validation - agents now know to use validate not check
  2. P1 (Critical): Sequence variant - agents now understand correct arrow directions
  3. P2 (Important): Wildcard selectors - agents now understand * vs ** difference
  4. P2 (Important): Schema inclusion - emphasized in all config examples

Testing

The improved documentation has been structured to help AI agents:

  • Avoid hallucinating non-existent CLI commands
  • Use correct syntax for sequence diagrams
  • Understand scope when including elements in views
  • Include schema for better IDE support

Closes feedback loop from #2636

cc @davydkov @a-scolan

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.
@changeset-bot

changeset-bot Bot commented Mar 24, 2026

Copy link
Copy Markdown

⚠️ No Changeset found

Latest commit: 8e6605c

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@vincent067 vincent067 mentioned this pull request Mar 24, 2026
@coderabbitai

coderabbitai Bot commented Mar 24, 2026

Copy link
Copy Markdown
Contributor
📝 Walkthrough

Walkthrough

The 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

Cohort / File(s) Summary
LikeC4 DSL Reference Documentation
skills/likec4-dsl/references/cli.md, skills/likec4-dsl/references/configuration.md, skills/likec4-dsl/references/predicates.md, skills/likec4-dsl/references/views.md
Added "Common Mistakes" and best practices sections: CLI command validation and incorrect command names, $schema property requirement for config files, wildcard depth selector behavior comparison (* vs **), and sequence diagram syntax with arrow direction semantics (-> for calls, <- for returns).

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~15 minutes

Possibly related PRs

Suggested reviewers

  • davydkov
🚥 Pre-merge checks | ✅ 3
✅ Passed checks (3 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly and concisely describes the main change: improving skill reference documentation based on benchmark feedback, which matches the primary objective of the PR.
Description check ✅ Passed The description is comprehensive and well-structured, detailing changes across all modified files with clear sections for CLI, Views, Predicates, and Configuration references, benchmark impact, and testing rationale.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

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.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

📥 Commits

Reviewing files that changed from the base of the PR and between d0f38c7 and 8e6605c.

📒 Files selected for processing (4)
  • skills/likec4-dsl/references/cli.md
  • skills/likec4-dsl/references/configuration.md
  • skills/likec4-dsl/references/predicates.md
  • skills/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` |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

🧩 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/ -C3

Repository: 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.

Comment on lines +66 to +89
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
}
}
```

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is unclear, though I know what it refers to : this note here. This sentence could be more affirmative of the correct behaviour

Comment on lines +250 to +268
**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
}
```

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@a-scolan

Copy link
Copy Markdown
Collaborator

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.
But we should probably modify it, to improve this chapter like this :
`## Model (Quick Reference)

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 { .. } with tags, properties, nested elements and relationships.
Relationships exist between any pair of elements, but not between parent-child elements. Relationships can be defined on any level of the hierarchy. Relationships, defined inside an element, implicitly have that element as their source.

Syntax:

model {
  // Elements, top-levels are global, can be referenced anywhere in the project
  IDENTIFIER = KIND                   // without title, without body (title defaults to ID)
  IDENTIFIER = KIND "title"           // with title, without body
  KIND IDENTIFIER "title"             // if preferred by user to have kind before OD  
  IDENTIFIER = KIND {
    TAGS                              // optional, but must come first if present, before any properties
    PROPERTIES                        // optional, but must come before nested elements and relationships

    // order of nested elements vs relationships doesn't matter
    // Nested elements, can be referenced in this file by id, but from other files only using FQN, i.e. parentid.childid
    IDENTIFIER = KIND "Child Title" {
       // Same as above, no limit to nesting levels
    }
    KIND IDENTIFIER "Child Title" // if preferred by user to have kind before name

    // Explicit Relationship, SOURCE and TARGET must be resolvable within the current scope
    SOURCE -> TARGET
    // Implicit Relationship (current element is SOURCE)
    -> TARGET "Relationship title"
    -> TARGET "Relationship title" {
      TAGS                            // optional, but must come first if present, before any properties
      PROPERTIES                      // optional
    }
    // Relationship with kind
    -[REL_KIND]-> TARGET "Relationship title" 
    .REL_KIND -> TARGET "Relationship title"   // Alternative syntax for relationship with kind
    // "it" and "this" refer to the current element
    SOURCE -> it     // relationship to current element
    this -> TARGET   // relationship from current element
  }

  // Relationships on top level MUST have SOURCE
  SOURCE -> TARGET "Relationship title"    //without body
  SOURCE -> TARGET "Relationship title" {
    TAGS                                   // optional, but must come first if present, before any properties
    PROPERTIES                             // optional
  }
  SOURCE -[REL_KIND]-> TARGET
  SOURCE .REL_KIND TARGET

  // Extend existing element by FQN, e.g. from another file
  extend FQN { 
    TAGS                   // additional tags to apply to this element
    PROPERTIES             // additional properties to merge into this element, allowed `metadata` and `link` only

    NESTED_ELEMENTS | RELATIONSHIPS
  }
  // Extend existing relationship (must match existing relationship identity)
  // SOURCE and TARGET are always required. If multiple relationships exist between the
  // same endpoints, include kind and/or title to disambiguate the exact relationship.
  extend SOURCE -> TARGET  {
    TAGS                   // additional tags to apply to this relationship
    PROPERTIES             // additional properties to merge into this relationship, allowed `metadata` and `link` only
  }
  extend SOURCE -[REL_KIND]-> TARGET "Relationship title" {
    TAGS                   // additional tags to apply to this relationship
    PROPERTIES             // additional properties to merge into this relationship, allowed `metadata` and `link` only
  }
}

For relationship extend, matching is not a loose "same endpoints only" lookup when the model contains distinct relationships between the same source and target. In practice, treat the matcher as needing the same relationship identity as the original declaration: source, target, and — when present or needed for disambiguation — relationship kind and title.

Example:

model {
  customer = actor "Customer" { description "End user" }

  cloud = system "Cloud" {
    ui = container "Frontend" {
      style { 
        shape browser
      }
      dashboard = app "Dashboard" { technology "React" }
    }
    backend = container "Backend" {
      api = service "API" { 
        #critical

        -[sql]-> db "reads/writes"
      }
      db = database "DB" { icon tech:postgresql }
    }
    ui.dashboard -> backend.api "calls" { technology "HTTPS" }
  }

  customer -> cloud.ui.dashboard "browses" {
    navigateTo browse-flow
    metadata { protocol "HTTPS" }
  }
}

Element properties: title, description, summary, technology, metadata, style, link
Relationship properties: title, description, technology, metadata, style, link, navigateTo
`

@davydkov davydkov merged commit 2f7e957 into likec4:main Mar 27, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants