/skill-creator

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/R runtime 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
├── runtime.py             # optional helpers for the persistent Python runtime
├── runtime.r              # optional helpers for the persistent R runtime
├── 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

1. Define concrete user requests that should trigger the skill and the expected outputs. 2. Search existing skills before creating a duplicate. 3. Choose a lowercase hyphenated name and create `.wisp/skills/<name>/SKILL.md` with `write`. 4. Add reusable scripts before writing long inline code examples. Execute every new script on representative local data. 5. Add root-level `runtime.py` and/or `runtime.r` when helpers need to work with persistent interpreter state. The rendered skill supplies a one-time loading instruction for each file: `exec(compile(...))` through `python`, or `source(..., local = TRUE)` through `r`. Skill loading itself does not execute them or inject Wisp tools. These files run inside the selected runtime; do not invoke them as standalone CLI scripts. 6. Validate structure with this skill's `scripts/quick_validate.py <skill-directory>`. 7. 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`. 8. 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.

Runtime 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 the corresponding `python` or `r` tool after loading; reload when that

runtime restarts or the conversation/execution context changes;

• Python and R retain separate state; use prefixed names to avoid collisions

with other helpers within each language's namespace;

• Python loading runs in `__main__`, so put self-checks in explicitly called

functions rather than a `__main__` guard.

Use `scripts/` when a helper is a standalone CLI, needs argument parsing, or should run through `run_in_context`. Choose by state reuse and execution needs, not file length. `scripts/runtime.py` and `scripts/runtime.r` are ordinary scripts; only the reserved root-level filenames get runtime loading guidance.

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.