Skills

A skill is a set of instructions agents follow the same way every time, for one kind of task, such as reviewing a quote, writing a status report or onboarding a customer. Agents see only each skill's name and description until a task matches. Then they read the whole skill. Instructions that apply to everything go in Instructions instead.

Add a skill⁠

  1. Open the Agents card for the layer. See Agents and setup.
  2. On the They know how to line, choose Add skill, then New skill.
  3. Enter a Skill name and choose Add skill.
  4. On the skill's page, fill in:
    • When agents use this skill: describe what the skill is for.
    • Skill instructions: write step by step what an agent should do.
  5. Choose Save changes.

The skill is available on the next run. Open a skill again from its chip on the card to edit it. Remove skill takes it away, and agents stop being able to use it.

A skill name uses lowercase letters, numbers, dashes and underscores. It names the task, such as quote-review.

Write the description well⁠

The description decides when an agent uses the skill, so most of a skill's quality is in it.

  • Say what the skill does, then when to use it, in the words people use. Include the names, systems and file types that should trigger it.
  • Put the main use first.
  • Keep it to one line and 500 characters or fewer.
  • Skip words like "ALWAYS" and "CRITICAL". They make the skill trigger when it should not.

Write the instructions⁠

  • Write steps a capable colleague could follow without asking.
  • Give the reason for any rule that is not obvious.
  • Include only what the agent cannot know: your systems, names, thresholds, formats and where things are.
  • End with a condition the agent can check, such as "Done when every line has been compared and each mark gives a reason."
Markdown
# Reviewing a quote

1. Read the quote from Files.
2. Compare each line with the price list in Files at Sales/Price list.xlsx.
3. Mark any discount over 10%, because those need a sales director's approval.
4. Reply with a table of lines, list price, quoted price and a Review column.

Done when every line has been compared and each mark gives a reason.

Which layer⁠

A skill belongs to a layer: the company, a Space, you or one Captain. A closer layer's skill with the same name replaces the whole skill for everyone that layer reaches, so reuse a name only to replace a skill on purpose. See Agents and setup.

Bigger skills⁠

A skill can be a folder with supporting files: reference documents the agent reads only when the instructions point to it, scripts for steps that must be exact, and templates. Edit the folder in Files or with the command line. See The whorl command. A skill folder has at most 256 files and 2,000,000 bytes, with no more than 200,000 bytes in a single file.

Skills written for other agent tools that use a SKILL.md file load unchanged.

Test it⁠

Try a few real requests that should use the skill, and one or two near-misses that should not, in a new Thread. Check that the agent used the skill and got the expected result. If it did not trigger, rewrite the description with the words from the request. If it triggered but did the work badly, fix the step that went wrong.

View as Markdown