| name | skill-creator |
| description | Create, update, validate, and evaluate Wisp skills. Use when authoring a project-local or installable skill, refining its trigger description, adding deterministic scripts or Python sidecars, or testing whether another Agent can follow the workflow. |
Create Wisp skills
Author project-local skills under .wisp/skills/<name>/. Wisp also discovers
bundled skills, user-installed skills, and paths configured by
WISP_SKILLS_PATH, but only normal project paths are directly writable through
Agent file tools.
Structure
<skill-name>/
├── SKILL.md # frontmatter trigger + procedure body
├── kernel.py # optional pure helper definitions
├── scripts/ # optional standalone deterministic programs
├── references/ # optional detailed domain material
└── assets/ # optional output templates or static inputs
Keep SKILL.md concise. Put triggering information in frontmatter
description; put essential procedure in the body; move detailed variants to
one-level-deep references. Add only resources the workflow actually uses.
Workflow
- Define concrete user requests that should trigger the skill and the expected
outputs.
- Search existing skills before creating a duplicate.
- Choose a lowercase hyphenated name and create
.wisp/skills/<name>/SKILL.md with write.
- Add reusable scripts before writing long inline code examples. Execute every
new script on representative local data.
- Add
kernel.py only for small reusable Python helpers. Loading a skill does
not inject Wisp tools into Python. The rendered skill supplies a one-time
exec(compile(open(...))) instruction that defines the sidecar names in the
persistent python kernel.
- Validate structure with this skill's
scripts/quick_validate.py <skill-directory>.
- Refresh or reopen the project if the new skill does not yet appear, then find
it with
search_skills and load it with use_skill.
- Exercise the skill on realistic tasks. When explicit Wisp delegation is
available, use a fresh bounded task with only the skill path and user-style
request; do not leak the expected answer into the evaluation prompt.
For a user-wide installation, ask the user to install the validated folder via
Settings → Skills. There is no Agent-side publish, overwrite, or delete API.
Frontmatter
At minimum include:
---
name: my-skill
description: Perform X. Use when the user asks for Y, Z, or related output.
---
The folder name and name should match. The description is the primary trigger;
state both what the skill does and when it should be selected.
Python sidecar rules
Keep top-level code definition-only:
- allow imports, function definitions, and literal constant assignments;
- defer optional third-party imports into function bodies;
- do not run work, access the network, or modify files at load time;
- do not depend on injected Agent, Run, credential, artifact, or model objects;
- pass paths and configuration explicitly;
- use
python to call helpers after the one-time loader instruction.
Use scripts/ instead when a helper is a standalone CLI, exceeds roughly one
hundred lines, needs argument parsing, or should run through run_in_context.
Bundled scripts
scripts/quick_validate.py <skill-dir> — checks frontmatter shape, kebab-case
naming, folder/name match, and length limits; prints every problem at once.scripts/package_skill.py <skill-dir> [out-dir] — validates, then zips the
folder into <name>.skill for user-wide installation, skipping build junk
and a root-level evals/ folder.
To evaluate a skill, run it on realistic tasks yourself (step 8 above) and keep
evaluation artifacts out of the skill folder unless they are intentional
reusable resources.
Wisp boundaries
search_skills and use_skill do not edit the catalog.- Project file tools cannot manage user-wide installed skills outside granted
workspace paths.
run_in_context executes deterministic work; it does not publish skills or
call models.- Specialist creation is separate. Load
customize and use
save_specialist only when that explicit tool is advertised.
