Skills

The skills namespace is the platform's library of reusable playbooks. Where memory tells the agent what's happened, skills tell it how to do things.

What a skill is

A skill is a Markdown document with:

A trigger — describes when it should be pulled in (semantic match against the user's question + current surface).
A playbook — step-by-step instructions for the kind of task it handles.
Optional tool hints — which tools to favor.
Optional constraints — what the agent must NOT do.

Example (truncated):

---
trigger: "summarize a customer's pipeline status"
tools_preferred: [graph_semantic_search, dashboard_query]
---

# Customer pipeline summary

1. Search the knowledge graph for the customer's account node.
2. Walk to all linked deals via `belongs_to_account`.
3. Group by stage; surface stuck deals (>14d in stage) prominently.
4. If there are open opportunities, suggest the next outreach.
5. Cite every number with the source deal/contact rows.

DO NOT speculate about deals that aren't in the result set. If
the search returned nothing, say so.

Where skills come from

Three sources, all visible in Settings → Skills:

Source	Editable?	Update path
Platform default	Read-only	Ships with the product, updated via releases
Tenant-authored	Yes	Created by your admin in the skills editor
Promoted from runs	Yes	The promotion pipeline writes new skills when it sees a recurring task pattern

Tenant-authored + promoted skills are scoped to your tenant; the RLS contract is the same as memory.

How the orchestrator picks skills

At the start of every run, the context assembler runs a semantic match between the user's question + the surface name and the trigger field of every skill. The top-N (default 3) are pulled into the SKILLS namespace.

You can see which skills the agent picked for any run via View context in the run drawer.

If no skill matches above a relevance threshold, the orchestrator falls back to its built-in reasoning — no skill is better than a mismatched skill.

Writing your first skill

Settings → Skills → New skill. The editor is a Markdown surface with two structured fields (trigger + tools_preferred). Save and the skill becomes immediately discoverable by the orchestrator.

Tips:

Lead with the trigger. The semantic match is the only thing standing between "skill exists" and "skill gets used."
Be concrete in the playbook. Generic advice doesn't beat the orchestrator's built-in reasoning. Win by being more specific than the orchestrator can be on its own.
Use constraints liberally. "DO NOT" lines pull weight — the agent respects them.
Test by asking. Ask the orchestrator a question matching your trigger and check whether your skill shows up in View context.

Skill promotion

The promotion pipeline (same nightly job that compacts memory) also watches for recurring task patterns in episodes. When it sees the same kind of question handled 5+ times the same way, it proposes a new skill from the consensus pattern.

You see proposed skills in Settings → Skills → Proposed with an Accept / Reject toggle. The promotion process is conservative — it only proposes; it never auto-publishes.

Versioning

Every edit to a tenant-authored skill bumps its version. Old runs that used previous versions keep their reference (so audit trails stay accurate). The agent always pulls the latest version on new runs.

Limits

Maximum 200 active skills per tenant. Most tenants have 5–30.
Maximum 4 KB per skill body (the platform truncates with a warning beyond that). Skills are supposed to be tight playbooks, not manuals.
Maximum 3 skills pulled per agent run. The context budget is bounded; cherrypicking is a feature.