skill-creator · diff
git:20260816.42573eb to git:20260908.31cc945
20 added, 10 removed. Audit A to A.
---
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.
+ 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
```text
<skill-name>/
├── SKILL.md # frontmatter trigger + procedure body
- ├── kernel.py # optional pure helper definitions
+ ├── 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 `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.
+ 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:
```yaml
---
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
+ ## 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 `python` to call helpers after the one-time loader instruction.
+ - 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/` instead when a helper is a standalone CLI, exceeds roughly one
- hundred lines, needs argument parsing, or should run through `run_in_context`.
+ 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.