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.

You can provide recipes in two ways:

Scope	Where you manage them	When they apply
Baseline (team)	Admin Settings → Design recipes, then referenced from a project baseline	For every user on projects that use that baseline
User-specific (personal)	User settings → Design recipes	For you only — on every Design Assistant query, independent of the project baseline

Baseline recipes standardize assistant behaviour across teams and project types. User-specific recipes add your own skills and commands on top — they do not replace baseline recipes.

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

At runtime, the Design Assistant combines:

1. Baseline recipes — linked to the project’s baseline (same for everyone on that baseline).
2. Your enabled user-specific recipes — from User settings (only for you; available in every project, regardless of baseline).

Commands from both sources appear together (for example as / slash commands in the chatbot and as actions on selected model elements). Skills from both sources are considered when you send a message. Disabled user recipes stay in your list but do not contribute skills or commands.

Baseline recipes (team)

Baseline 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 baseline 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.

User-specific recipes (personal)

Any authenticated user can upload personal design-recipe packages in User settings → Design recipes. No admin role is required.

Unlike baseline recipes, user-specific recipes are not referenced from a baseline. When a personal recipe is enabled, the Design Assistant applies it on every query — in every project you open — independently of which baseline that project uses.

Typical uses:

• Keep personal commands and skills (shortcuts and expertise you use often, without changing team baselines).
• Try out new skills and commands before an administrator adds them to a baseline and rolls them out to other projects.

💡tip

Upload a draft recipe in User settings, enable it, and verify behaviour in the Design Assistant. When it works as intended, hand the same ZIP to an administrator to publish under Admin Settings and attach it to the relevant baselines.

For step-by-step management (add, enable/disable, replace, download, delete), see Manage design recipes.

Baseline vs user-specific recipes

	User settings	Admin Settings
Scope	Per user	Tenant / shared; referenced from project baselines
Who manages	Any authenticated user (their own recipes)	Administrators
Enable / Disable	Yes	Not in the admin UI (presence is controlled by baseline references)
Runtime effect	Enabled recipes add skills and commands for that user on every query, independent of baseline	Baseline-linked recipes apply for all users on projects using that baseline
Replaces the other?	No — adds alongside baseline recipes	No — user recipes remain separate

Managing baseline design recipes

Administrators manage shared 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 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 reference and to existing example recipes in your environment.

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. Commands come from recipes linked to the project baseline and from your enabled personal design recipes.

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?

To insert a reference to a project, diagram, or model element instead of a command, type @ — see Mentions.

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

• Manage design recipes — upload, enable, and maintain your personal recipes
• 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, including @ mentions
• 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