---
name: create-skill
description: Capture a repeatable task or a just-produced output (a document/deck house style, a report format, a workflow) as a reusable skill the agent can load and reuse later. Use when the user asks to "create/save a skill", "make this reusable", or "remember how to do this" — and proactively offer it after producing polished, reusable, style-bearing work.
loading: on-demand
---

# Create Skill

A **skill** is reusable agent instructions saved as a `skill` entry in the workspace. Once saved it appears in the skill index and is loaded on demand, so the next time a similar task comes up the house style / recipe / steps are applied consistently. This is how a workspace teaches itself: capture a good output once, reuse it forever.

## When to create a skill

- **Explicit** — the user says "create a skill", "save this as a skill", "make this reusable", "remember how to do this", "do it like this from now on".
- **Proactive** — you just produced something polished and reusable that has a repeatable RECIPE (a branded document or deck style, a standard report format, a multi-step workflow). Offer ONCE, in one short line: *"Want me to save this as a reusable '<name>' skill so I can produce it consistently next time?"*
  - Only offer for genuinely reusable, style-bearing work — NOT for one-off answers, edits, searches, or trivial outputs.
  - Offer at most once for a given piece of work; if the user declines or ignores it, drop it and don't re-offer.

## Author a good skill

1. **Distill the RECIPE, not the instance.** If you just made an artifact, extract the reusable pattern — the structure, the CSS / house style, the steps — and drop the one-off content. Generalize "Acme's offer letter to Jordan Lee" into "an offer letter on the company's letterhead". Parameterize what varies (company, names, figures); keep what's stable (layout, tone, sections, format).
2. **Write a sharp `description` — this is the most important field.** It is what ROUTES the skill: the agent reads skill descriptions to decide when to load one. State exactly WHEN to use it, in the user's words, in one or two sentences. A vague description means the skill is never loaded.
3. **Write the body as concrete, runnable instructions** — the steps, the key patterns, and a **worked example** (the actual CSS / structure / template). Concrete examples beat abstract prose. Keep it tight: instructions, not an essay.
4. **Don't over-fit and don't bloat.** One skill = one coherent capability. If it's trying to do five unrelated things, it's five skills.

## Save it

**Always ask the user which folder to save the skill in** before creating it — don't assume. A personal folder makes it the user's own skill; a shared/team folder makes it available to the whole team. Confirm the destination.

Then create it with `create_entity`:
- `entity_type: 'skill'`
- `entity_id`: a kebab-case skill name (e.g. `offer-letter`) — the id IS the skill name.
- `data`: `{ name: '<Display Name>', description: '<the sharp when-to-use line>', loading: 'on-demand' }`
- `content`: the markdown instructions body (recipe + worked example). Do NOT open the body with an `#` H1.

`loading: 'on-demand'` is almost always right — the skill loads only when its description matches the task. Reserve `'eager'` for guidance that must shape every response.

## After saving

Confirm to the user and link the new skill with a wikilink — e.g. *"Saved the **Offer Letter** skill ([[offer-letter]]) — next time you ask for an offer letter I'll use this format."* The skill is loadable immediately via `load_skill`; no restart needed.
