Skip to main content

Design recipe reference

This reference describes the ZIP archive structure, the k5-design-recipe.yaml metadata file, and the SKILL.md and COMMAND.md formats used in design recipes.

Design recipe ZIP archive structure​

A design recipe is distributed as a ZIP archive with the following layout:

my-design-recipe-1.0.0.zip
├── k5-design-recipe.yaml     # Recipe metadata (required)
├── skills/                   # Skills folder (optional)
│   └── <skill-id>/
│       └── SKILL.md          # One skill per subfolder
└── commands/                 # Commands folder (optional)
    └── <command-id>/
        └── COMMAND.md        # One command per subfolder

File requirements​

RequirementDetails
Required root filek5-design-recipe.yaml at the archive root (not inside a nested bundle folder).
SkillsEach skill lives under skills/<skill-id>/SKILL.md. The folder name should match the skill identifier.
CommandsEach command lives under commands/<command-id>/COMMAND.md. The folder name should match the command name in COMMAND.md.
Allowed contentMarkdown (.md) and YAML (.yaml, .yml) under skills/ and commands/.

At least one of skills/ or commands/ should contain definitions if the recipe is meant to extend the Design Assistant. An empty bundle (metadata only) is valid but has no effect on behaviour.

k5-design-recipe.yaml format​

The root metadata file identifies the recipe and its version. The combination of id and version must be unique in Admin Settings; uploading the same pair again replaces the existing definition.

Complete example​

# Unique recipe identifier (stable across versions)
id: "ddd-design-recipe"
# Semantic version
version: "1.0.0"
# Name, displayed in the UI
name: "DDD design recipe"
# optional description
description: "Skills and commands for ddd modelling baselines"
# optional tags
tags:
  - ddd
  - validation

After upload, reference the recipe in k5-oml.yaml under designRecipes for the relevant project baselines so projects load it automatically. See Project baseline reference and OML Configuration Reference.

SKILL.md format​

Each skill is a single SKILL.md file with YAML frontmatter and a markdown body. The frontmatter declares the capability; the body is the expertise the Design Assistant applies when the skill is selected.

Frontmatter fieldRequiredDescription
nameYesSkill identifier. Should match the parent folder name under skills/.
descriptionYesWhen this skill applies. Used to choose among similar skills.

The markdown body below the frontmatter is the skill content: procedures, checks, conventions, and constraints.

Example skill​

skills/validate-ddd-design/SKILL.md:

---
name: validate-ddd-design
description: Use when the user asks to validate, review, or check the DDD design for gaps or consistency.
---

Perform the following checks on the current branch and report every gap:

1. Each DDD aggregate contains exactly one DDD entity that is the root entity.
2. Every command triggers at least one business event.

Return a structured list of findings. Do not change the model unless the user explicitly asks to fix the reported issues.

Skills may reference other skills by name in the body (for example “Apply the checks from validate-ddd-design and additionally …”).

COMMAND.md format​

Each command is a single COMMAND.md file with YAML frontmatter and a markdown body, in the same pattern as SKILL.md. The frontmatter declares how the command is registered in the UI; the body is the command prompt—the text inserted into the Design Assistant when the user triggers the command from the chat (/command-name) or from a shortcut on selected elements.

Common fields (all commands)​

Frontmatter fieldRequiredDescription
nameYesUnique command identifier (kebab-case). Used for /name in the chat and for UI registration. Should match the parent folder name under commands/.
labelNoShort label shown in menus (for example Clean up). Falls back to name if omitted.
descriptionNoLonger help text shown in command pickers and / completion.
BodyRequiredDescription
Markdown below the frontmatterYesCommand prompt copied into the chat input. Write plain text or a single quoted line; the product uses the body content as-is (after placeholder substitution).

Element command fields​

When a command should appear on diagrams, lists, or detail views for selected model elements, also set in the frontmatter:

Frontmatter fieldRequiredDescription
elementTypesYesList of OML element type patterns the command applies to. Supports wildcards: * (all types), ddd.* (all types in the ddd namespace), or a full type id.
singleNoIf true, the command is available when exactly one matching element is selected. Default false.
multiNoIf true, the command is available when multiple matching elements are selected. Default false.

Set both single and multi to true if the command should appear in either selection mode.

Placeholder: In the prompt body, use ${elements} to substitute the selected element names. For a single selection, one name is inserted; for multiple selections, names are combined as defined by the product (typically a comma-separated list).

General commands​

General commands are chat-only shortcuts. Set name and the prompt in the body; add optional label and description in the frontmatter. Omit elementTypes, single, and multi.

Example command (element command)​

commands/cleanup-entity/COMMAND.md:

---
name: cleanup-entity
label: Clean up
description: Move property definitions from entity descriptions into formal DDD properties.
elementTypes:
  - "ddd.*"
single: true
multi: true
---
"Clean up the following entities: ${elements}"

Example command (general command)​

commands/project-overview/COMMAND.md:

---
name: project-overview
label: Project overview
description: Give a short project overview
---
In a nutshell, what is the content of this project?

After the prompt is inserted, the user can edit it before sending. The assistant may then apply a matching skill if the prompt fits a skill's scope.

Upload validation​

When a bundle is uploaded in Admin Settings → Design recipes, the system typically validates:

  • The archive is a readable ZIP file.
  • k5-design-recipe.yaml is present and contains required fields (id, version, name).
  • Each SKILL.md and COMMAND.md parses correctly, includes required frontmatter, and has a non-empty markdown body.
  • Command name values are unique within the recipe.
  • elementTypes patterns are non-empty for element commands.

If validation fails, the upload response or UI shows the error; fix the bundle and upload again. Replacing a recipe uses the same id and version as an existing entry.