162 lines
5.4 KiB
Markdown
162 lines
5.4 KiB
Markdown
---
|
|
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.
|