Design recipes

Available in product edition: Professional

Introduction

The Design Assistant helps you explore and change your design through natural-language chat in the Solution Designer. Design recipes let you tailor those capabilities to your workflows. They bundle skills (specialized expertise you give the assistant, in the same spirit as skills in other AI agents) and commands (shortcuts into the chat) that reflect your terminology, standards, and typical design tasks — so the assistant can do more on your behalf and you spend less time crafting long, repetitive prompts.

Recipes are managed centrally and linked to project baselines, so every team member working from the same baseline gets the same assistant behaviour. That streamlines and optimizes design workflows across projects and project types without each person maintaining their own prompts.

Design recipes are not the same as implementation recipes shipped with project baselines for coding assistants.

What is in a design recipe?

A design recipe is a versioned bundle that groups:

Building block	Purpose
Skills	Specialized capabilities and expertise to be applied to the design assistant when the users request matches the skill's scope.
Commands	Shortcut actions that insert a prepared prompt into the chat — from the assistant panel or from selected model elements.

Each recipe has an id, a version (semantic versioning), and a name. The version lets you evolve recipes over time without breaking projects that reference a specific release.

You decide how skills and commands are grouped: by domain, by project type, by baseline, or for reuse across several baselines. The platform does not prescribe a single organization scheme.

How design recipes are applied

Design recipes take effect when they are associated with the project baseline your project uses — similar to how OML profiles are referenced from a baseline.

1. An administrator uploads design recipe bundles in Admin Settings (see Managing design recipes).
2. The baseline configuration lists which design recipes apply to projects created from that baseline.
3. When anyone on the team opens the Design Assistant in a project that uses that baseline, the linked recipes load automatically. No per-user or per-session setup is required.

Because association happens at baseline level, architects and administrators can streamline workflows for whole teams: the same skills, commands, and terminology apply to every user on architecture baselines, DDD service baselines, or any other baseline you define.

The platform also ships default design recipes with example profiles and baselines. After installation, your administrator can load them using Install or upgrade the initial design recipes, profiles and baselines.

Managing design recipes

Administrators manage design recipes in Admin Settings under Design recipes (same lifecycle pattern as OML profiles and baselines: upload, replace, delete). Recipes are shared across the organization and referenced from one or more project baselines.

Typical uses:

• Standardize design workflows for all projects on a given baseline.
• Align assistant behaviour with enterprise modelling standards so teams work the same way.
• Publish a recipe once and attach it to multiple baselines.
• Optimize recurring workflows centrally instead of relying on each designer to remember long prompts.

Uploading a design recipe

1. Open Admin Settings from the header Settings icon.
2. Go to Design recipes.
3. Upload a ZIP bundle that contains your skills and commands (see Authoring skills and commands).
4. Associate the recipe with the relevant project baselines so all projects—and every user on those projects—pick it up automatically.

When you upload a bundle with the same id and version as an existing recipe, the new content replaces the previous definition for that version.

Design recipe format

Recipe bundles are ZIP archives with k5-design-recipe.yaml at the root plus optional skills/ and commands/ folders. For the full structure, field definitions, and file examples, see the Design recipe reference.

If upload fails, check the error message in Admin Settings and compare your bundle to the example design recipes.

Skills

In AI agents, skills extend what the agent can do well: they add capabilities and expertise beyond the default model behaviour. Design recipe skills work the same way for the Design Assistant. You teach it how to handle specific design situations (validation rules, decomposition patterns, conversions between model elements) by packaging that knowledge in a skill.

Each skill is a self-contained unit of expertise. Users do not invoke skills by name; they ask in natural language, and the assistant decides whether a skill applies.

How skills are used

When you send a message, the Design Assistant considers which skills are relevant, using each skill's name and description (when to use this capability). If a skill matches, the assistant draws on the skill content—the detailed know-how, and plans its work accordingly, rather than improvising only from general training.

Skills can reference other skills, so you can build layered expertise: a broad skill composes narrower ones (for example a general “validate design” skill that applies “validate DDD design” and adds further checks).

Authoring a skill

Each skill is defined in a markdown file (conventionally SKILL.md in a folder named after the skill), following the same idea as SKILL.md files used by other AI agents. The structure separates what capability you are adding from how the assistant should exercise it:

Field	Role
Name	Identifies the capability (for example Validate DDD design).
Description	When this expertise applies; helps the assistant pick the right skill among similar ones.
Content	The expertise itself: procedures, checks, conventions, examples, and constraints the assistant should follow when the skill is active.

Write content as clear, imperative guidance—the operational knowledge you want the assistant to rely on, not a one-off chat prompt.

Commands

Commands are shortcuts that pre-fill the Design Assistant input with a prompt. They reduce typing and keep wording consistent across the team.

Every command has a unique command name (identifier) in the file frontmatter. Optional label and description improve discoverability in the UI. The prompt is the markdown body of COMMAND.md; it is inserted into the chat when the command is chosen.

General commands

General commands cover use cases are not tied to a model element (e.g. like "Project overview"). They can be triggered directly from the chatbot textbox:

1. Type / to open the command list.
2. Select a command from the dropdown (names and descriptions are shown).
3. The command's prompt is inserted into the text box. Edit if needed, then send.

Example: A project-overview command might insert In a nutshell, what is the content of this project?

Element commands

Element commands run in the context of one or more selected model elements. You configure:

Setting	Meaning
Element types	Which OML element types the command applies to. Use wildcards: * (all types), ddd.* (all DDD types), or a specific type identifier. (Array)
single	Show the command when exactly one element is selected.(boolean)
multi	Show the command when multiple elements are selected. (boolean)

You may enable both single and multi so the same command appears in either selection mode.

When the command applies, shortcut actions appear in the diagram or canvas element boxes of the matching type. To trigger the commands, select the model element, open the chatbot menu (purple chatbot icon) and choose one of the displayed commands.

Triggering element command opens the Design Assistant and inserts the prompt. Placeholders in the prompt are replaced automatically:

Placeholder	Replaced with
${elements}	Names of the selected element(s)

Example — single and multi cleanup

• Command name: cleanup-entity
• Label: Clean up
• Element types: entity types your profile defines
• Flags: single: true, multi: true
• Prompt: Clean up the following entities: ${elements}

Example — multi-only aggregation

• Command name: sum-up-user-stories
• Label: Sum up
• Element types: user story types
• Flags: multi: true only
• Prompt: Sum up user stories ${elements}

After the prompt appears, review it and press Enter to run — the assistant may then apply a matching skill (for example a “clean up entity” skill) if one exists.

For COMMAND.md and SKILL.md field definitions and examples, see the Design recipe reference.

Related documentation

• Design recipe reference — ZIP layout, k5-design-recipe.yaml, SKILL.md, and COMMAND.md formats
• Design Assistant — prerequisites, chat usage, and built-in example prompts
• Use the Design Assistant — day-to-day prompting patterns
• Project baselines — associating profiles, recipes, and design recipes with projects
• OML profiles — modelling vocabulary referenced by baselines
• Implementation recipes — skills and commands for coding assistants in Git
• Install initial design recipes, profiles and baselines — loading default bundles after installation