Appearance
AI Engine — Agent Skills
A skill is a reusable block of instructions. When an LLM node runs, the engine picks the skills that fit the current turn and appends them to the node's system prompt. A skill is text only: no scripts, no resource files. The file format follows the open Agent Skills standard (agentskills.io), so a skill can be exported as SKILL.md and imported again.
Source: service/api/src/modules/ai/ — runtime/skills.ts, services/skills.service.ts, services/skill-md.ts, services/skill-preview.service.ts, controllers/skills.controller.ts. Admin UI: apps/webapp/modules/ai/pages/skills/ and components/skills/.
Data model
Both collections are part of the AI module schema (version 5). Run the AI setup wizard to add them to an existing install.
| Collection | Fields |
|---|---|
ai_skill_categories | name, description, parent_id (self-reference → tree), sort |
ai_skills | name, title, description, body, category_id, tags, status, load_mode, priority, license, metadata |
Rules that the API enforces:
name: 1–64 characters,a-z,0-9and single hyphens, no leading or trailing hyphen. Unique.description: 1–1024 characters. The router reads only this field to decide if the skill fits the turn.body: markdown, at most 5000 tokens (length / 4).status:draft|published|archived. Onlypublishedskills are loaded at runtime. There is no version pinning: apps and nodes always use the latest published body.load_mode:always— loaded on every turn where the skill is attached.auto— loaded when the router decides the user message needs it.manual— loaded only when the chat request names it inskills.
priority: 0–100. When the token budget is too small, lower priority skills are left out first.- A category with sub-categories or skills cannot be deleted (409). A parent change that makes a cycle is rejected.
- A skill that an app or node references by id cannot be deleted (409). Archive it instead. References by category or tag do not block the delete.
Attaching skills
Skills are attached by reference, in JSON config. There is no junction table.
jsonc
// ai_apps.config.skills (every LLM node of the app)
// ai_flow_nodes.config.skills (one LLM node)
{
"mode": "inherit", // node only: "inherit" = app ∪ node, "replace" = node only
"ids": ["<skill id>"],
"category_ids": ["<category id>"], // the whole branch below the category
"tags": ["vn"],
"top_k": 3, // max auto skills per turn (default 3)
"token_budget": 4000 // tokens for all skills of the node (default 4000)
}Chatbot and text-generation apps run through a synthetic graph with one LLM node, so ai_apps.config.skills applies to them too.
Runtime — one LLM node, one turn
- Merge the app and node refs (
inheritorreplace). Keep published skills that match by id, category branch or tag. alwaysskills are in.manualskills are in only if the chat request lists their name.autoskills go to the router:- first a SystemOne decision (one yes/no question per candidate, threshold 0.5);
- if SystemOne is not configured or fails, one small LLM call that returns
{"skills": [...]}; - if that also fails, no auto skill is loaded. The turn does not fail. The router result is cached per candidate set for the run, so several LLM nodes do not call it twice.
- Auto skills chosen on the previous turn stay for one more turn (stored in
ai_messages.meta.skills_auto). Thentop_kapplies to the auto skills. - Sort by priority, render each body, and drop what does not fit
token_budget. - Wrap and append to the system prompt:
xml
<active_skills>
<skill_content name="refund-policy">…rendered body…</skill_content>
</active_skills>The node output gets skills_loaded and skills_dropped. The assistant message meta gets skills and skills_auto.
Variables in a skill body
A body is rendered with the same {{path}} renderer as the node prompt (single pass, no helpers). App variables can be written three ways, all equal:
| Syntax | Value |
|---|---|
{{refund_days}} | app variable refund_days |
{{app.refund_days}} | same (alias) |
{{app.variables.refund_days}} | same |
The value comes from input.variables of the chat request. If the request does not send it, the engine uses config.variables[].schema.default_value of the app. A variable with no value renders as an empty string; the preview endpoint lists these in missing_variables.
Endpoints
All routes need the ai app module. Reads need view, writes need manage.
| Method | Path | Notes |
|---|---|---|
| GET | /ai/skill-categories | flat list; build the tree from parent_id |
| POST / PATCH / DELETE | /ai/skill-categories[/:id] | 409 on delete when not empty |
| GET | /ai/skills | list |
| GET / POST / PATCH / DELETE | /ai/skills[/:id] | 409 on duplicate name, 409 on delete when attached by id |
| GET | /ai/skills/:id/usage | apps and nodes that reference the skill, with via: id / category / tag |
| GET | /ai/skills/:id/export | { filename, content } — a SKILL.md file |
| POST | /ai/skills/import | body { content, overwrite? }; new skills are created as draft; 409 if the name exists and overwrite is not set; missing categories in the path are created |
| POST | /ai/skills/preview | body { app_id, node_key?, query?, variables?, skill_id?, body? } → final system prompt |
| POST | /ai/apps/:id/chat | accepts skills: string[] (names) for manual skills |
/ai/skills/preview returns { system_prompt, segments[], dropped[], total_tokens, missing_variables, node_key }. With skill_id (and an optional unsaved body) the skill is forced into the prompt, so an author can check a draft before publishing. Flow apps use the first LLM node unless node_key is given; chatbot apps use config.prompt.
SKILL.md format
The frontmatter keeps the standard fields (name, description, license, metadata). ODP fields go into metadata with an odp- prefix, so other Agent Skills clients still read the file:
markdown
---
name: refund-policy
description: Apply the refund and return policy. Use when the customer asks about refunds or returns.
license: Proprietary
metadata:
odp-title: Refund policy
odp-category: Customer care / Refunds
odp-tags: vn,policy
odp-load-mode: auto
odp-priority: "70"
---
# Refund policy
- Change of mind: accepted within {{app.refund_days}} days.