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.