skill-creator git:20260908.31cc945A

Immutable. This exact content is served forever at /api/v1/blob/3f163321e4df5b39.

---
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

```text
<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:

```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.

## 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.