Skip to content

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.

CollectionFields
ai_skill_categoriesname, description, parent_id (self-reference → tree), sort
ai_skillsname, title, description, body, category_id, tags, status, load_mode, priority, license, metadata

Rules that the API enforces:

  • name: 1–64 characters, a-z, 0-9 and 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. Only published skills 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 in skills.
  • 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 ​

  1. Merge the app and node refs (inherit or replace). Keep published skills that match by id, category branch or tag.
  2. always skills are in. manual skills are in only if the chat request lists their name.
  3. auto skills 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.
  4. Auto skills chosen on the previous turn stay for one more turn (stored in ai_messages.meta.skills_auto). Then top_k applies to the auto skills.
  5. Sort by priority, render each body, and drop what does not fit token_budget.
  6. 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:

SyntaxValue
{{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.

MethodPathNotes
GET/ai/skill-categoriesflat list; build the tree from parent_id
POST / PATCH / DELETE/ai/skill-categories[/:id]409 on delete when not empty
GET/ai/skillslist
GET / POST / PATCH / DELETE/ai/skills[/:id]409 on duplicate name, 409 on delete when attached by id
GET/ai/skills/:id/usageapps 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/importbody { 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/previewbody { app_id, node_key?, query?, variables?, skill_id?, body? } → final system prompt
POST/ai/apps/:id/chataccepts 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.

ODP Internal API Documentation