Agent Skills
Package a system prompt, tools, and knowledge into a reusable configuration that any agent node can load.
An Agent Skill is a saved, versioned bundle of AI agent configuration: a system prompt, a list of enabled tools, one or more knowledge bases to search, and optional LLM defaults (model, temperature). You create a skill once, then use it across as many agent nodes and workflows as you like. When the underlying skill changes, every node that references it picks up the update automatically.
Agent Skills live in Agent Builder → Skills. They work alongside Workspace Skills (markdown instruction sets for the chat interface) — you can attach active workspace skills to an Agent Skill so their content is injected verbatim as reference material before every request the agent handles.
Why use Agent Skills?
| Without skills | With skills |
|---|---|
| Duplicate system prompts copy-pasted across nodes | One skill, referenced in many nodes |
| Changing a prompt means editing every workflow | Edit the skill; all nodes update |
| No version history for agent behavior | Every skill save creates a snapshot; rollback in one click |
| Testing requires running a full workflow | Test the skill directly from the skill editor |
Key Features
| 🧩 Composition | A skill can extend another skill via base_skill_id — overrides merge cleanly |
| 📚 Knowledge binding | Attach knowledge bases; the resolver injects relevant chunks at runtime via RAG |
| 📌 Reference Skills | Link active workspace skills to inject their full content verbatim before every request |
| 🛠️ Tool selection | Pick any subset of built-in tools to grant this skill |
| 🎛️ LLM defaults | Set model, temperature, and max tokens per skill |
| 🔢 Versioning | Snapshot any version; roll back instantly; compare two versions side-by-side |
| 📊 Analytics | Run count, average latency, and error rate per skill — updated on every workflow run |
| 🧪 Test panel | Send a test message directly to the skill without running a workflow |
| 📤 Export / Import | Share skills across instances as JSON |
Skill mode vs Prompt mode
Every agent node in the Agent Builder offers two configuration modes:
| Mode | How to activate | What the node uses |
|---|---|---|
| Skill mode | Select a skill from the dropdown in the node properties panel | Skill's system prompt, tools, knowledge, and LLM defaults — merged with any node-level overrides |
| Prompt mode | Leave skill blank and fill in the inline system prompt | Only the node's own configuration |
Switch between modes using the toggle at the top of the node properties panel.
You can attach a skill and add extra inline overrides. Node-level overrides always win — they layer on top of the skill, they don't replace it.
Composition and merge order
A skill can extend another skill by setting base_skill_id. The resolver walks the inheritance chain and merges all levels:
base_skill (lowest priority)
↓
skill
↓
node config overrides (highest priority)
Merge rules:
| Field | Merge behavior |
|---|---|
system_prompt | Joined with \n\n (base first, then skill, then node override) |
tools | Ordered union — deduped, preserving order |
knowledge_ids | Ordered union — deduped |
workspace_skill_ids | Ordered union — deduped |
llm_defaults | Shallow dict merge — later keys win |
This makes it easy to define a "base agent" skill with shared instructions and fork department-specific variants that only override what's different.
Reference Skills
Attach curated workspace skill documents to an agent skill so they are injected verbatim before every request.
Workspace Skills are markdown documents — policies, templates, checklists, style guides. Linking them to an Agent Skill gives the agent always-present reference material without using RAG or consuming permanent system-prompt tokens per model.
How it differs from Knowledge Bases
| Reference Skills (workspace) | Knowledge Bases | |
|---|---|---|
| Content | Small curated markdown cards | Large document corpora |
| Injection | Full content, always, verbatim | Top-k chunks, per query, via semantic search |
| Best for | Policies, templates, checklists, style rules | Manuals, FAQs, large knowledge repositories |
| Updated when | Workspace skill is edited — propagates automatically | Document is re-indexed |
Injection order
When an agent node runs, context is assembled in this order before the user message:
## Reference Material ← linked workspace skills (verbatim full content)
### GDPR Policy
...
---
### Contract Template
...
## Knowledge Context ← knowledge base results (RAG, top chunks)
[source, p.1] (score: 0.91)
...retrieved chunk...
{user message}
Linking workspace skills
In the skill editor, scroll to the Reference Skills section. A checkbox list shows all active workspace skills. Check the ones you want this agent skill to always inject.
Only workspace skills with Active status appear in the picker. Inactive skills are hidden from selection and silently skipped at runtime even if their IDs are stored in the skill record. Toggle a skill active from Workspace → Skills before linking it here.
Per-node extra reference skills
In the node properties panel (skill mode), you can add workspace skills beyond what the base skill defines using the Extra Reference Skills section. This is the workspace equivalent of Additional Knowledge Bases — it lets a single node load contextual reference documents without modifying the shared skill definition.
Extra reference skills are unioned with the skill's own workspace_skill_ids following the same merge order as other node overrides.
Creating a Skill
Go to Agent Builder → Skills and click + New Skill.
| Field | Description |
|---|---|
| Name | Display name (e.g. "Document Reviewer") |
| Description | Short summary — shown in the node picker and analytics |
| Base Skill | Optional parent skill to extend |
| System Prompt | Instructions for the agent |
| Reference Skills | Active workspace skill documents to inject verbatim before every request |
| Tools | Built-in tools this skill enables (web_search, code_executor, etc.) |
| Knowledge Bases | Knowledge base IDs to search on every run |
| Model | LLM model override (blank = instance default) |
| Temperature | 0.0–2.0 |
Click Save to create the first version. Every subsequent save snapshots the previous state for rollback.
Managing Skills
Delete Selected: On the Agent Builder → Skills list, a checkbox appears on each Draft skill's card (published skills go through the versioning lifecycle instead of a direct delete). Check the ones you want to remove and click Delete Selected (N) in the toolbar to delete them all after a single confirmation. If some fail, the result reports how many succeeded versus failed rather than a silent partial delete.
Import Bundle (.zip): Migrate SKILL.md/agents/*.md files from a Claude Code plugin repository straight into Agent Skills — see Import Bundle.
Using a Skill in a Node
- Open a workflow in the Agent Builder.
- Click an
agentnode to open its properties. - Switch to Skill mode using the toggle.
- Select a skill from the dropdown.
- Optionally override individual fields (system prompt addition, extra tools, different model).
The node properties panel shows a live preview of the resolved config — what the node will actually run after all inheritance and overrides are applied.
Versioning
Every Save on a skill creates a new snapshot. From the skill editor:
- Version history panel — shows every snapshot with timestamp and author.
- View — open any past version to inspect it.
- Roll back — promote a past version to current (this creates a new version, not a destructive rewrite).
- Diff — select two versions and compare system prompts, tools, and knowledge side-by-side.
When a workflow runs, it resolves the skill at the current version. To pin a node to a specific version, export the skill version and create a new skill from the snapshot.
Analytics
The Analytics tab on a skill shows aggregate metrics across all workflow runs that used it:
| Metric | Description |
|---|---|
| Total runs | Number of times this skill was invoked in a workflow run |
| Success rate | Percentage of invocations that completed without error |
| Avg latency | Mean time from node start to node end |
| Recent errors | Last 10 error messages for debugging |
Analytics are updated in real time as workflows execute.
Testing a Skill
From the skill editor, open the Test tab:
- Type a message in the input box.
- Click Run.
- The response streams back immediately — same as a workflow run, but isolated to this skill.
The result panel shows the full resolved configuration used for the test:
| Section | What it shows |
|---|---|
| Resolved System Prompt | The merged system prompt (base + skill + any override) |
| Resolved Tools | Every tool enabled after inheritance |
| Resolved Knowledge IDs | Knowledge bases that were searched |
| Reference Skills Injected | Workspace skills whose content was prepended — shown by name |
Test runs don't appear in workflow run history and don't count toward trigger quotas.
Where the test's LLM credentials come from
The Test panel resolves its LLM provider through the exact same node → space → catalog → global chain used by real workflow runs — it does not use the global tier exclusively. If the skill is scoped to a catalog and space (via catalog_id/space_id, set when the skill is created inside an active space), that catalog's or space's provider takes precedence; the skill's own Model / Temperature / Max Tokens fields always apply on top of whichever provider resolves.
This means none of the four tiers resolved to a provider — most commonly because the skill has no catalog/space association (so only the global tier is checked) and Admin → Models has no enabled connection. See Troubleshooting "No LLM provider configured" for the full checklist.
API Reference
| Endpoint | Description |
|---|---|
GET /api/v1/agent-skills/ | List all skills (paginated) |
POST /api/v1/agent-skills/ | Create a new skill |
GET /api/v1/agent-skills/{id} | Get skill details |
PUT /api/v1/agent-skills/{id} | Update skill (creates a new version) |
DELETE /api/v1/agent-skills/{id} | Delete skill |
POST /api/v1/agent-skills/{id}/version | Snapshot the skill into a new immutable version |
GET /api/v1/agent-skills/{id}/versions | List every version in the skill's chain, newest first |
POST /api/v1/agent-skills/{id}/versions/{version_id}/revert | Restore a prior version's content as a new version (the Roll back action above) — history itself is never mutated, only the current content changes |
GET /api/v1/agent-skills/{id}/analytics | Usage analytics |
POST /api/v1/agent-skills/{id}/test | Test the skill with a message |
Default Skill
Every workflow has a default skill — a skill that is automatically created when the workflow is first saved and permanently linked to it.
What it is
The default skill is a regular Agent Skill whose name follows the pattern:
{Workflow Name} [{first 6 chars of workflow ID}]
For example: Invoice Pipeline [a1b2c3]
It is shown alongside the workflow in the Agent Builder → Skills list and can be edited like any other skill. Its purpose is to act as the "house prompt" for the workflow — the system prompt and tool configuration that makes this workflow unique.
Auto-wire on create
When you create a workflow that already contains an agent node (for example via the AI Assist panel or an import), the first agent node with no skill configured is automatically wired to the default skill. You do not have to manually select the skill in the node properties panel.
This happens at creation time only. If you add more agent nodes later, you must wire them manually.
Rename sync
When you rename the workflow (via the editor header or the PUT /api/v1/agent-workflows/{id} API), the default skill's name updates automatically to match:
New Name [wfid6]
This keeps the skill name consistent with the workflow it belongs to, so it is easy to identify in the Skills list and in analytics.
If the rename sync fails (e.g. a transient DB error), the workflow is still renamed — the skill name update is best-effort and non-blocking. Retry a manual skill rename from the skill editor if needed.
Stage gate
The default skill must have a non-empty system prompt before the workflow can be staged. See Stage gate: default skill must have a system prompt for details.
Lifecycle
| Event | What happens to the default skill |
|---|---|
| Workflow created | Default skill auto-created and linked |
| Workflow renamed | Default skill name updated to match |
| Workflow deleted | Default skill deleted (cascade) |
| Workflow exported | Default skill embedded in the export bundle |
| Workflow imported | Default skill recreated from the bundle; blank auto-created skill is discarded |
Related
- Node Types → agent — how skills are loaded into agent nodes
- Built-in Tools — tools skills can enable
- Workflow Lifecycle — publishing a workflow that uses skills
- Workspace Skills — markdown instruction sets; active ones can be linked as Reference Skills