| name | new-scriptlet |
| description | Create or update scriptlet bundles for text expansions, snippets, shell commands, and lightweight helpers in a single markdown file. |
New Scriptlet
Use a scriptlet bundle when the user wants text expansions, snippets, quick shell commands, or several lightweight helpers grouped in one markdown file.
Write Here
~/.scriptkit/plugins/main/scriptlets/<name>.md
Do not create new user bundles in app-managed or example plugins.
Read These Files In Order
~/.scriptkit/plugins/examples/scriptlets/howto.md~/.scriptkit/plugins/examples/scriptlets/main.md~/.scriptkit/plugins/examples/scriptlets/advanced.md
Canonical Bundle Shape
---
name: My Bundle
description: Personal helpers
icon: sparkles
---
## Email Sign-off
```metadata
keyword: !bye
description: Quick email sign-off
Thanks,
Your Name
Quick Note
description: Save a quick note
import "@scriptkit/sdk";
const note = await arg("Note");
await Bun.write(`${env.HOME}/quick-note.txt`, note);
hud("Saved");
## Fence Map
| Fence | Use for |
|------|---------|
| `paste` | Static text expansion |
| `bash` | Shell command |
| `tool:<name>` | TypeScript with the Script Kit SDK |
| `template:<name>` | Template expansion |
| `open` | URL or file target |
`tool:<name>` fences still need `import "@scriptkit/sdk";` as the first line.
## Metadata
Prefer `metadata` code fences for:
- `keyword`
- `description`
- `shortcut`
- `alias`
- `schedule`
- `cron`
- `icon`
- boolean flags
Legacy HTML comments still work, but do not generate them for new harness-authored bundles unless the user explicitly asks for legacy format.
## Choose Script vs Scriptlet Bundle
Choose a `.ts` script when the request needs:
- rich UI
- multi-step logic
- file/network workflows
- external APIs
Choose a scriptlet bundle when the request is:
- a snippet
- a text expansion
- a quick shell command
- a small grouped helper set
## Companion Actions Files
To add shared actions to every command in a bundle, create a matching companion file:
- Parent bundle: `~/.scriptkit/plugins/main/scriptlets/<name>.md`
- Shared actions: `~/.scriptkit/plugins/main/scriptlets/<name>.actions.md`
Use `{{content}}` inside the companion action to access the selected parent command content.
See [add-actions](../add-actions/SKILL.md) for the canonical pattern.
## Focused Feature Examples
Generic examples are flat files under `~/.scriptkit/plugins/examples/scriptlets/`. Focused feature examples are **nested bundles**:
- `~/.scriptkit/plugins/examples/scriptlets/agent_chat-chat/main.md` — Agent Chat-oriented scriptlet helpers
- `~/.scriptkit/plugins/examples/scriptlets/custom-actions/main.md` — shared Actions Menu patterns
- `~/.scriptkit/plugins/examples/scriptlets/custom-actions/main.actions.md` — companion actions file
- `~/.scriptkit/plugins/examples/scriptlets/notes/main.md` — Notes automation as a scriptlet bundle
Flat mirrors (`~/.scriptkit/plugins/examples/scriptlets/agent_chat-chat.md`, `custom-actions.md`, `custom-actions.actions.md`, `notes.md`) are generated from the nested bundles above.
## Related Skills
- [add-actions](../add-actions/SKILL.md) — shared Actions Menu patterns for scriptlet bundles
- [start-chat](../start-chat/SKILL.md) — Agent Chat-oriented scriptlet helpers
- [manage-notes](../manage-notes/SKILL.md) — package Notes automation examples as scriptlet bundles
## Done When
- the file lives in `~/.scriptkit/plugins/main/scriptlets/`
- each `##` heading is one scriptlet
- the fence type matches the intended behavior
- the bundle is the smallest artifact that fits
