| name | author-skill |
| description | Co-create a reusable skill with the user — capture their analysis flow, terminology, and preferred style as a loadable SKILL.md. Use when the user wants to "make/save a skill", asks you to remember how they like a task done, or after a task you could turn into a repeatable procedure. |
Co-author a skill with the user
A skill is a short, reusable instruction file the agent loads on demand. It
captures how the user wants a kind of task done — the steps of their analysis
flow, the terminology they use, and the output style they prefer — so next time
the work follows their way without re-explaining. Skills you save here load with
read_skill and can be downloaded and reused in another workspace.
Follow these steps. Keep the user in the loop — this is a conversation, not a
form. Write in the user's language.
1. Agree on scope and trigger
Ask (or confirm if it's already obvious from the conversation):
- What task is this skill for? Keep it to ONE kind of task — one skill, one
job. If they describe two, make two skills.
- When should it fire? This becomes the one-line
description — a concrete
"use this when…" so the agent (later) knows to reach for it. Prefer the user's
own trigger words.
State the scope back in one sentence and get a yes before drafting.
2. Extract the substance
Pull out three things — this is the valuable part, so dig:
- Process — the ordered steps the user follows. Number them. Note decision
points ("if X, then…") and what "done" looks like.
- Terminology — domain words, abbreviations, and what they mean here.
- Style — the shape of a good result: sections, tone, length, what to lead
with, what to leave out.
Don't rely only on Q&A. Read what's already in this workspace — the files,
the artifacts, and earlier messages in this chat often show the flow the user
just walked. Use list_files / read_file to mine a worked example, then
confirm "is this how you'd always want it?" Ask one focused question at a time;
stop when you can write the procedure without guessing.
3. Draft the SKILL.md body
Write the methodology as clear markdown the future agent will follow:
- Numbered steps mirroring the user's process; imperative voice ("Compute…",
"Group by…", "Report…").
- A short terminology list if the task has jargon.
- A "what good output looks like" note (or a tiny example).
- Keep it tight — a skill is guidance, not an essay. If it grows past a few
screens, split it into two skills.
If the task benefits from reference material (a long term table, a checklist,
a worked example), put it in a separate file under the skill's folder and point
to it from the body, e.g. "see references/glossary.md". The future agent reads
it with read_file only when needed.
If a repeatable computation is part of the flow, write a small Python script
under the skill's scripts/ folder and document how to run it, e.g.
exec(["python", ".skill/<name>/scripts/summarise.py", "data.csv"]). Scripts use
the workspace's bundled Python stack (pandas / numpy / scipy / matplotlib) — do
not assume any other package can be installed.
4. Review with the user
Show the draft (the description + the body, and any reference/script files).
Ask what's wrong or missing. Iterate until they approve. Do not save an
unreviewed skill.
5. Save it
Once approved, call save_skill(name, description, body):
name — a short title; it's slugified to kebab-case automatically.description — the one-line trigger from step 1.body — the markdown from step 3.
save_skill owns the file format, so you only pass those three fields. For any
reference or script files, write them with write_file into the same
.skill/<name>/ folder (e.g. .skill/<name>/references/glossary.md,
.skill/<name>/scripts/summarise.py) and make sure the body points to them.
Optional dry run: if it's quick, load the new skill with read_skill(<name>)
and walk it once on real data so the user can confirm it produces what they want
before relying on it.
6. Close out
Tell the user, plainly:
- The skill is saved and loads any time with
read_skill('<name>').
- To reuse it in another workspace, download its folder from the Skills panel and
import it there.
- If it proves stable and they want it built in for everyone, they can download
it and ask the team to add it to the starting profile.
