1-skills.md
Skills
A skill is a reusable recipe that teaches the AI assistant how to handle one recurring question or task in your environment. You write it once instead of every user re-explaining it.
Skills are managed by environment administrators and benefit everyone in the environment.
When a Skill Helps
The assistant already knows how to explore your graph. A skill is worth it when your way of answering is specific to your environment:
- A recurring question that always needs the same steps
- A report or comparison your team asks for repeatedly
- A rule about which objects or relations to use
- Team vocabulary that does not appear literally in the data
How They Are Used
Each turn, the assistant sees only the names and descriptions of available skills. If a description matches the question, it loads that skill and follows it. Reference files are read only when needed.
The description decides everything — it is all the assistant sees when choosing whether to load the skill.
Users can also force a skill by typing /skill-name.
Writing the Description
Answer “when should this be used?”, with phrasings your users would actually type:
Good — “Use when the user compares two structures and wants the differences. Triggers: ‘compare A and B’, ‘what changed between’.”
Too vague — “Handles comparisons.” → never loads
Too broad — “Use for any data question.” → loads everywhere
Triggers are examples, not a fixed list: matching is by meaning, in any supported language.
Writing the Body
- Imperative steps, in order
- Generic placeholders, not hard-coded identifiers
- State the expected output — table, chart, key columns
- Say what not to do
- Move long examples into reference files
Fields
| Field | Meaning |
|---|---|
| Name | Short identifier, also the /name command. Unique per environment. |
| Description | When to use it |
| Version | Informational |
| Active | Whether the assistant can see it |
| Reference files | Optional attachments, read on demand |
Each skill belongs to one environment and never leaks to another.
Activating and Testing
New skills start inactive. Admins see drafts marked (draft); users do not see them at all.
- Confirm it is listed and active
- In a new conversation, force it with
/skill-name - In another new conversation, ask a natural question that should trigger it — this is what validates your description
Use a fresh conversation per test: once loaded, a skill stays active for that whole conversation. Changes apply on the assistant’s next turn.
Good to Know
- Renaming is not supported — create the new name, delete the old one
- Reference files are text, replaced by exact path; old paths are not auto-removed
- Built-in platform skills are read-only
- Deleting a skill deletes its reference files
- Two skills with overlapping descriptions compete — prefer one clear skill