PicoBot/resources/skills/skill-creator/SKILL.md

name	description
skill-creator	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

---
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.