---
name: skill-creator
description: Create or update PicoBot skills. Use when the user wants a new skill, wants an existing skill revised, or needs a skill scaffold that follows PicoBot's workspace/skills mechanism.
---

# Skill Creator

Use this skill when building a new PicoBot skill or updating an existing one.

## About Skills

Skills are small, self-contained folders that give PicoBot procedural knowledge for a narrow task.
They are most useful when the same workflow, file format, or domain rule would otherwise be
re-explained over and over.

## PicoBot conventions

- Put `always: true` in the `SKILL.md` frontmatter when the skill should be injected on every turn.
- Prefer `{workspace}/skills/<skill-name>/` for skills created by the agent.
- `~/.picobot/skills/` is the built-in install location.
- `~/.agents/skills/` is the fallback shared location.
- Each skill must have a `SKILL.md` file.
- Add `agents/openai.yaml` when you want UI metadata or a default invocation prompt.
- Use `references/` for detailed docs and `assets/` for templates or bundled files.
- Keep `SKILL.md` concise; move long instructions into references.
- Use `always: true` only when the skill should be injected on every turn.

## Core Principles

### Keep It Concise

Only add information the model actually needs. Prefer short rules and concrete examples over
long explanations. If a rule can be implied from the task, leave it out.

### Set the Right Constraints

- Use high freedom when many approaches are valid.
- Use medium freedom when there is a preferred pattern but some variation is fine.
- Use low freedom when the workflow is fragile and should be followed closely.

### Protect Validation

When a skill changes, verify it against a realistic task path. Check that:

- the skill name is discoverable,
- the frontmatter is valid,
- any bundled references are actually reachable,
- and the instructions still lead to the intended output.

## Skill Anatomy

Every PicoBot skill should have:

- a required `SKILL.md`,
- optional `agents/openai.yaml` for UI metadata,
- optional `references/skill-template.md` as a starting scaffold,
- optional `references/` for longer docs,
- optional `assets/` for templates, icons, or sample files.

## Workflow

### 1) Capture Intent

Start by figuring out what the user actually wants the skill to do.

Check:

- what task the skill should enable,
- when it should trigger,
- what the expected output looks like,
- whether the task is objectively testable,
- whether the skill needs bundled references or assets.

If the request is vague, ask short, focused questions before writing files.

### 2) Draft the Skill

1. Choose a clear skill name and a narrow purpose.
2. Write `SKILL.md` with a trigger-focused `description` and a concise body.
3. Put `always: true` in the frontmatter only when the skill should be injected on every turn.
4. Add `agents/openai.yaml` for UI metadata if the skill should appear in a picker or chip list.
5. Add `references/` or `assets/` only when they reduce repetition.

### 3) Validate the Draft

Before treating the skill as done, check that:

- the frontmatter parses,
- the skill is discoverable through `get_skill`,
- the body is still concise,
- the references and assets are reachable,
- the instructions are specific enough to lead to the right output.

For objective workflows, also test the skill against a small set of representative prompts or files.

### 4) Iterate

Revise the skill based on what you learn.

- Tighten the description if the skill under-triggers.
- Narrow the instructions if the model wanders.
- Add examples if the output format keeps drifting.
- Move details into `references/` if `SKILL.md` starts to grow.

### 5) Optimize Triggering

The `description` is the main trigger surface.

- Make it specific.
- Include the contexts where the skill should be used.
- Prefer wording that helps the model notice the skill even when the user does not name it exactly.
- Keep it concise, but do not make it vague.

### 6) Re-open and Confirm

Use `get_skill action="get"` one more time to confirm the final shape if anything changed materially.

## Progressive Disclosure

Keep `SKILL.md` as the entry point and move detail into separate files when it starts to grow:

- Put setup steps, examples, and edge cases in `references/`.
- Put reusable templates or sample files in `assets/`.
- Link from `SKILL.md` to those files instead of duplicating content.
- Start new skills from `references/skill-template.md` when you want a consistent scaffold.

## What Not To Include

- Do not add general project docs that do not help create the skill.
- Do not dump every possible edge case into `SKILL.md`.
- Do not duplicate the same guidance in both `SKILL.md` and `references/`.
- Do not make the skill broad just because it can handle more cases.

## Skill scaffold

```md
---
name: example-skill
description: What this skill helps with and when to use it.
always: true
---

# Example Skill

Short, direct instructions for the agent.
```

## Good fit

- A reusable workflow with a clear trigger.
- A task that benefits from bundled references or templates.
- A skill that should be easy to discover and update inside PicoBot.

## Practical Rule of Thumb

If the skill is:

- **objective**: add test cases and validate output shape,
- **workflow-heavy**: spell out the sequence and the stop conditions,
- **content-heavy**: move examples and long references into `references/`,
- **trigger-sensitive**: spend more time on `description` than on the body.