# Sysmlkit

> Author and edit SysML v2 model text that conforms to the program's placement standard and to Cameo's front-end behaviour. Use whenever writing, editing or reviewing a .sysml file, choosing which namespace or package an element belongs in, writing imports between namespaces, naming packages or elements, or interpreting a sysmlkit finding or rule id such as ORG-ROOT-CONTENT or M-51. Also use when asked where something goes in the model, why a Cameo view renders empty, or whether an import is allowed.

- Skill: `ddunnock/sysmlkit` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ddunnock/sysmlkit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ddunnock/sysmlkit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: ddunnock (https://skillmd.com/u/ddunnock)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ddunnock/sysmlkit

---


# Authoring SysML v2 with sysmlkit

Three rule systems govern whether model text is acceptable, and only one of them
is the language: the grammar, Cameo's front-end behaviour, and this program's
placement policy. `sysmlkit check` is the single findings stream over all three.

## The loop

1. Edit the `.sysml` file.
2. Run `sysmlkit check <file>` — or let the PostToolUse hook run it.
3. Every finding names a rule id. For anything you do not recognise, run
   `sysmlkit explain <RULE-ID>` before changing anything.
4. Fix, re-run, continue.

Do not guess at a rule from its id, and do not work around a finding by moving
the element somewhere the check does not look. `explain` prints the evidence,
the fix, and the observation that would retire the rule.

## What the ids mean

- `ORG-*` — placement. These come from the program's profile
  (`sysml-standards.toml`) and vary per program. The profile is the authority,
  not your memory of another model.
- `M-*` — Cameo behaviour. These ship with the tool and are the same on every
  program running the same Cameo build.
- `SPEC42-*` — language conformance, from the validator. Fix the text it names.
- `SYSKIT-*` — the tool reporting on itself: a file that did not parse, a check
  that examined nothing, an expired waiver, a generated block edited by hand.

## Grades, and what they entitle you to

Every rule carries an evidence grade: `V` verified, `O` observed, `R` reasoned,
`C` correlated, `U` unverified. `C` and `U` rules **cannot** gate and appear in
the context file under "unsettled — do not rely on". Treat those as open
questions, not instructions, and do not turn one into a rule by acting on it.

## Before writing new content

- Placement first: work the ladder in the profile's namespace list, and stop at
  the first match. If the element could be reused unchanged by another program
  it is vocabulary; if it names a count, a location or a specific sibling it is
  instance content.
- Imports go where the profile says (`structure.import_location`), scoped to a
  package rather than a namespace root, and only along a row of the import
  matrix.
- Never put a hyphen or a leading digit in a declared name. It goes in the short
  name: `requirement <'SYS-INT-0142'> TrackLatency`.
- Use `doc` comments, never `//`. Cameo strips line comments on save.

## When a view renders empty

Three shapes produce an empty table and none of them is an error: an `expose` at
a dead path, a filter on a marker nothing carries, and an attribute-reading
filter whose attribute type is not imported `public`. Run
`sysmlkit explain M-13` and `sysmlkit explain M-23` before assuming content is
missing.