skill-creator git:20260816.42573ebA

Immutable. This exact content is served forever at /api/v1/blob/59d70c0d9866d937.

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

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

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

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.