second-state/wasmedge-agent/skill-creator

Skill Creator

A skill is a directory with a SKILL.md file (YAML frontmatter + markdown instructions). At startup WasmEdge Agent reads only each skill's name and description into the system prompt; the full file loads on demand when a task matches. WasmEdge Agent follows the Agent Skills standard and extends it with Rust crate skills.

Before writing a Rust skill, read references/rust-skills.md for the crate contract.

Creating a Skill

1. Pick the kind. Default to markdown. Go Rust only when the agent should call the capability (agent_lib::skills::my_skill::run(...)?) instead of following instructions.
2. Pick the location. Ask the user when it is not obvious from context:

• Project skill, shared via the repo: .wasmedge-agent/skills/<name>/
• Personal global skill: ~/.wasmedge-agent/skills/<name>/
• Shipped with an npm package: a skills/ directory in the package, or pi.skills paths in its package.json

1. Scaffold and write the directory using the layout and frontmatter rules below. For a new project-local Rust skill, rlm::skills::package(name, description, instructions, source)? creates the crate and SKILL.md without overwriting existing files; see the Rust skill contract.
2. Verify the skill loads (see Verification).

On a name collision the first skill found wins. Precedence: explicit --skill paths and skills settings entries, then project, then global, then package, then built-in skills.

Layout

my-skill/
├── SKILL.md              # Required: frontmatter + instructions
├── Cargo.toml            # Rust skills only: makes the directory a crate
├── src/lib.rs            # Rust skills only: the callable implementation
├── scripts/              # Optional helper scripts the instructions reference
├── references/           # Optional detailed docs, loaded only when needed
└── assets/               # Optional templates and data files

Everything except SKILL.md is freeform. Reference files with paths relative to the skill directory; the agent resolves them against the directory containing SKILL.md.

Frontmatter

---
name: my-skill
description: What this skill does and when to use it. Be specific.
---

Unknown fields are ignored. Name violations produce warnings but the skill still loads.

Write the description for routing

The description is the only thing the model sees before deciding to load the skill. State what the skill does and the trigger conditions ("Use when ..."), naming the concrete tasks, tools, and phrases a request would contain.

Good: Extracts text and tables from PDF files, fills PDF forms, and merges PDFs. Use when working with PDF documents. Poor: Helps with PDFs.

Write the body for progressive disclosure

Keep SKILL.md short: the decision flow, the common commands, the contract. Push exhaustive detail (API schemas, full option lists, long examples) into references/*.md and link them, so they only enter context when actually needed. State setup steps (installs, env vars, credentials) explicitly and early.

For Rust skills, the SKILL.md body must document every public signature (the mounted crate has no runtime introspection — SKILL.md is the API reference the model reads before calling).

Verification

After writing the skill:

1. Re-read the frontmatter and check every rule in the table above, especially that name matches the directory name and the description is non-empty.
2. In an interactive session, /reload picks up new skills without a restart; other sessions pick them up on start. Loading problems (bad name, missing description, name collisions) surface as warnings — ask the user to check, or check diagnostics yourself if you can.
3. A loaded skill is also invocable as /skill:<name>, which the user can try directly.

For Rust skills, also run the checks in references/rust-skills.md.