Skills

A skill is procedure made portable: a folder with a SKILL.md file carrying instructions the model follows when the skill is active, on the open Agent Skills format. Where a system prompt says who the agent IS, a skill says how a particular JOB is done: the triage checklist, the report template, the house style. Because a skill is a file, it gets what files get: versioning, review, diffing, and reuse across every agent and client that speaks the format.

1The anatomy#

Each skill is one folder in the server's skills directory: a SKILL.md whose front matter declares the name, description, and optional metadata (version, license), and whose body is the instructions; supporting resources ride in the folder beside it. The server loads the directory into a registry at startup and WATCHES it, so editing a skill on disk is live without a restart, and a folder whose SKILL.md fails to parse is reported in the admin panel rather than silently dropped. The admin Skills section is the operator's view: the inventory, a built-in editor, and the enablement switches.

2Two activation paths#

• Pinned: the request (or the agent bundle) names one skill in skill, and its instructions ride the system turn for the exchange. Deterministic, the right path when the caller knows the job.
• Model-driven: skills lists names the model MAY use; the server exposes them through an activation tool, and the model reads the descriptions and activates what the task needs. This is progressive disclosure: instructions enter the context only when chosen, so a large skill library costs nothing until a skill is actually used. A skill can opt out of this path (disable-model-invocation), keeping it pinnable-only.

The two compose: pin the job's main skill, offer the utility skills for discovery.

3Skills that ask: activation inputs#

A skill parameterizes itself by asking. Any {{ask:Question?|default}} token inside the instructions declares one activation question AND marks where the answer lands:

Write the summary in {{ask:Which language?|English}}, at most
{{ask:How many bullet points?|5}} bullets.

The declaration is the substitution site, so any skill gains inputs by typing one. The playground asks the questions when the skill is pinned; API callers answer through skill_inputs, keyed by each question's slug; unanswered questions take their declared defaults, and model-driven activation (which cannot ask) always uses the defaults. One mechanism, no schema files, and a skill without tokens behaves exactly as before.

4Fleet behavior: sources and allowlists#

Two configuration levers make skills operable beyond one machine:

• Sources: Skills:Sources lists URLs whose skills the server installs when absent, so a deployment seeded with a settings file reproduces its skill set without hand-copying folders. A sync never overwrites: a skill already present is left alone, so local edits survive, and per-source outcomes (installed, present, failed) are reported in the admin inventory.
• Allowlists: Skills:AllowedSkills narrows which skills exchanges may use at all, the governance lever for a server whose skills directory is broader than what every caller should reach.

5Writing skills that work#

• Description is the trigger. Under model-driven activation the model chooses by the description; write it as "use when ...", naming the situations, not the implementation.
• Instructions are procedure, not personality. Voice belongs to the agent's system prompt; the skill should read like a runbook a competent colleague could follow.
• Parameterize with ask-tokens instead of forking. One "summarize" skill with language and length questions beats five near-copies.
• Let the file lifecycle work for you. Review skill edits like code; the live watcher makes iteration immediate, and testing closes the loop.

6Stated plainly#

• A skill is a versioned procedure file on the open SKILL.md format, live-loaded from disk and edited from the admin console.
• Pinning is deterministic; model-driven activation is progressive disclosure over a library, and both ride any chat request or agent bundle.
• {{ask:...}} tokens make skills parametric with zero ceremony, and sources plus allowlists make them a fleet artifact instead of a local file.