---
name: skill-builder
description: "Guide the user through creating a new lean skill — collect name, description, behaviour rules, and references, then save the skill to memory."
---

# Skill Builder

Invoked by the admin agent directly.

A deterministic walkthrough for creating new lean skills. Follow each step in order. Be conversational — one question at a time.

## When to Activate

The admin requests a new skill, asks to "create a skill", "add a skill", or "teach you something new".

## Before Starting

Load `references/lean-pattern.md` for the template and examples. Use it throughout as your reference for correct structure.

## Step 1: Understand the Purpose

Ask: **"What should this skill do?"**

Listen for:
- What capability it adds (scheduling, quoting, inventory, etc.)
- When it should activate (what triggers it)
- What tools or data it needs (memory, web search, file access, etc.)

Clarify until you can describe the skill in one sentence. This becomes the `description` in frontmatter.

## Step 2: Choose a Name

Propose a name based on the purpose. Names must be:
- Lowercase
- Hyphen-separated (e.g. `inventory-management`)
- Short and descriptive

Confirm with the user.

## Step 3: Define Behaviour

Ask what rules the agent should follow when using this skill:
- **Tone and style** — formal, casual, WhatsApp-short?
- **Activation conditions** — when exactly should the agent use this skill?
- **Hard boundaries** — what should the agent never do?
- **Data sources** — where does the skill's knowledge live? (memory, external API, files)
- **Escalation** — when should it hand off to admin?

Not every skill needs all of these. Only include what's relevant.

If the skill involves generating PDFs or print-ready documents, load `references/pdf-generation.md` for the constraints on HTML layout and the `browser-pdf-save` rendering path.

## Step 4: Decide on References

If the skill has detailed procedures, templates, or data formats, those belong in `references/` files — not inline in SKILL.md.

Ask: **"Are there any detailed procedures, templates, or formats this skill needs?"**

For each reference file:
- Give it a descriptive filename (e.g. `event-format.md`, `quoting-rules.md`)
- Collect the content from the user — they can dictate, paste, or describe it and you draft it

If the skill is simple enough to fit in SKILL.md alone (under ~30 lines of instructions), skip references.

## Step 5: Choose an Icon

Ask: **"Would you like to pick an icon for this skill?"**

Icons give skills a visual identity. They use [Lucide](https://lucide.dev) icon names. Offer a few suggestions that match the skill's purpose — the reference file `references/lean-pattern.md` has a curated list.

If the user picks one, note it as part of the skill record. If they skip this, omit it — it's optional.

## Step 6: Compose the Skill

Using the lean pattern from `references/lean-pattern.md`, compose:

1. **SKILL.md** — frontmatter (`name`, `description`) + activation conditions + behaviour rules + references index
2. **Reference files** — one per detailed topic

Show the user the complete SKILL.md content and each reference file. Ask them to review.

## Step 7: Save the Skill as a Plugin File

Use `store-skill` to write the composed skill to disk as part of an admin-managed plugin. The tool computes the path internally — supply the names and content only.

Pick a `pluginName` that groups related operator-authored skills (e.g. `beacons-skills`, `my-utils`). Reuse the same `pluginName` across calls so the skill joins existing operator skills under one plugin. If this is the first skill in a new plugin, the tool creates the `PLUGIN.md` automatically.

```
store-skill({
  pluginName: "{kebab-case plugin name}",
  skillName: "{kebab-case skill name}",
  description: "{the one-sentence description from Step 1}",
  publicEmbed: false,
  body: "{SKILL.md body content WITHOUT frontmatter — activation conditions, behaviour rules, references index}",
  references: [
    { filename: "{kebab-case-name}.md", content: "{full reference body}" }
  ]
})
```

Set `publicEmbed: true` only when the user wants this skill surfaced to the public agent. Default to `false` for admin-only skills.

`references` is optional — pass `[]` (or omit) when the skill has no detailed procedures or templates.

## Step 8: Confirm

Tell the user:

> "Your skill is saved on disk as part of the `{pluginName}` plugin and is active right now for the admin agent. I can use it when the situation matches. To edit it later, ask me to update the skill — I'll re-run `store-skill` with the new content."

If `publicEmbed: true`, add: "It will surface in the public agent on the next session start."

---

**Remember:** Be conversational. Don't dump all questions at once. Guide through each step one at a time.