Skills
A Skill is a named procedure written in Markdown: a folder with a SKILL.md file in it. The
agent sees the name and description of every Skill it has. It runs one when the task fits,
or when you start it by name.
Where Skills live
The Runtime looks for a Skill in four places. When two places hold a Skill with the same name, the first one in this list wins:
| Place | Path | Who sees it |
|---|---|---|
| Project | <project>/.settings/skills/<name>/SKILL.md | Sessions in that Project |
| Home | $WISP_HOME/skills/<name>/SKILL.md (~/.wisp/skills/ by default) | every Session |
| Extra folders | <folder>/<name>/SKILL.md, for each folder in skillPaths | every Session |
| Built in | inside the Runtime | every Session |
- Project Skills need a Project. A Session without one, such as a Session from the Telegram bot, the Slack app or a run token, sees only the home, extra and built-in Skills.
skillPaths(SKILL_PATHS) lists extra folders, separated likePATH. Among them, the first folder wins. See the configuration.- The folder name is the Skill's name. The
namein the front matter must be exactly the folder's name. If it is not, the Runtime skips the Skill without an error. - Skills are read from disk each time. A new or edited
SKILL.mdcounts from the next message. There is nothing to reload.
To see what a Session would get:
wisp skills list # home, extra folders and built-in Skills
wisp skills list --project . # the same, plus this folder's Project Skills
Each line is a Skill's name and description. GET /v1/skills returns the same list.
Two Skills are built in:
create-skillteaches the agent to write a Skill; see below.wisp-self-helpanswers questions about Wisp from these docs rather than from memory, and, when something fails, reads the Runtime's recent errors first. It fetches pages withmcp__wisp_proxy__fetch_url, which asks by default; see Web search and fetch.
Three more come with the Runtime for office files. Ask for a report, a deck or a budget and the agent uses them on its own:
documentscreates, reads, edits and reviews Word files (.docx), tracked changes and comments included.presentationscreates, edits and reviews PowerPoint decks (.pptx) with real text, charts and tables.spreadsheetsreads, creates, edits and checks Excel workbooks (.xlsx, .xlsm) with live formulas, charts and formats.
They differ from the two above in a few ways:
- They live in the home folder. The Runtime unpacks them into
~/.wisp/skills/when it starts and brings them up to date after each update. - You can change them. Once you edit one, updates leave it as you made it. A Skill of your own with the same name is left alone too.
- They run Python scripts through
bash_run. Underwisp run, allowbash_runfirst (see Permissions). The first use downloads a Python toolchain, once for all Projects, which takes a while. - LibreOffice is optional. With it installed, the agent can render pages and slides to check how they look; without it, everything else works.
Writing a SKILL.md
---
name: open-case
description: Opens an incident case from an alert. Use when the message is an alert payload.
whenToUse: The input is JSON from the monitoring system.
arguments: severity, service
argumentHint: <severity> <service>
---
# Open a case
Severity is ${severity}, the service is ${service}.
1. Read the runbook for ${service}.
2. Open a case with the full alert: ${argument}
The front matter is flat key: value lines between two --- lines. It is not full YAML:
each key takes one line, quotes around a value are removed, and a list is a
comma-separated line (arguments: severity, service), not a YAML array. Everything after the
front matter is the body.
| Key | Required | Meaning |
|---|---|---|
name | yes | the Skill's name; must match its folder |
description | yes | what the Skill does and when to use it. This is what the agent reads to decide |
whenToUse | no | an extra hint, shown to the agent next to the description |
arguments | no | names for the words after the Skill's name, in order |
argumentHint | no | a short usage hint, such as <severity> <service> |
context | no | inline (the default) or fork, see below |
allowedTools | no | the tools a fork Skill may use, comma-separated |
paths | no | file patterns. The Runtime reads them but does not act on them yet |
A Skill without a name or a description, or with a context other than inline or
fork, is skipped. Unknown keys are ignored.
The agent sees each description and whenToUse cut to 250 characters. Put the trigger
early.
Arguments
The text after the Skill's name is its arguments. The Runtime fills these placeholders in the body:
| Placeholder | Becomes |
|---|---|
${argument} | the whole argument text |
${<name>} | a word given by position, for each name in arguments |
${<key>} | the value of a key=value word in the arguments |
${WISP_SKILL_DIR} | the Skill's folder, to point at files kept next to SKILL.md |
${WISP_SESSION_ID} | the Session's id |
Arguments are split on whitespace, so a positional argument is one word. A placeholder with no value is left as written.
Inline and fork
inline: the body is added to the conversation, and the agent follows it in the same Session, with the same tools.fork: a separate agent runs the body as its instructions and returns its conclusion. It does not see the conversation.allowedToolslimits the tools it gets; it never getsskill_invokeorspawn_agent. Rules still apply to every call it makes, and a tool that needs approval asks for it as in the main Session. It has no step or time limit by default;subagentTimeoutMssets a time limit, as for a subagent.
allowedTools has no effect on an inline Skill.
Running a Skill
Every way to run a Skill sends the same line: /<name> <arguments>. The Runtime finds the
Skill, fills in the arguments and gives the body to the agent. The name may use letters,
digits, - and _.
-
From the CLI:
wisp run --skill open-case "high payments" # a new Session on this folderwisp run 6b4f2a7e-… --skill summarise "" # an existing Session, no arguments -
In a message: a message whose text starts with
/<name>runs that Skill. Text marked as a third party's never does. -
Over
/v1: sendskilland an optionalargumentsinstead ofinputin the Run body. -
On a schedule:
wisp schedules create --skill <name>runs the Skill on each fire, with the job's input as its arguments. See Schedules. -
By the agent: the agent starts a Skill on its own with the
skill_invoketool when the task fits its description.skill_invokedefaults toallow. See Tools.
If no Skill has that name, or the Skill is a fork one, the line is not expanded: the agent
gets /<name> <arguments> as an ordinary message. The agent can still start a fork Skill
from it with skill_invoke.
Letting the agent write Skills
The built-in Skill create-skill teaches the agent how to write a Skill. Ask for one in
plain words ("make a Skill that…"), or run it:
wisp run --skill create-skill "a Skill that drafts the weekly status email"
The agent writes Skills with its skill_fs_* tools: to ~/.wisp/skills/ (every Session),
or to the Project's .settings/skills/ when the Session has a Project.
skill_fs_write, skill_fs_read and skill_fs_list default to allow. The agent can
create or change a Skill without asking, and that Skill is offered in later Sessions. Only
skill_fs_delete defaults to ask. To review every change, set a Rule:
wisp permissions set skill_fs_write ask
See Permissions.
Built-in Skills cannot be changed with these tools. A Skill of the same name in a Project, home or extra folder takes precedence over a built-in one.