# pi-dollar-skills

Add Codex-style `$skill-name` invocation to [Pi](https://github.com/earendil-works/pi-mono). Explicitly load skills at the beginning, middle, or end of a message, with skill-name autocomplete when you type `$`.

## Installation

Requires **Pi 0.85.1 or later** (uses the `addAutocompleteProvider` and `getCommands().sourceInfo` APIs).

```sh
pi install git:github.com/ALLLLLL703/pi-dollar-skills
```

Run `/reload` in an existing Pi session, or restart Pi.

To try it from a local checkout:

```sh
pi -e ./src/index.ts
```

## Usage

Type directly into Pi's input box, without wrapping the invocation in backticks:

```text
$code-review Review the current changes
Use $planning to make a plan, then $code-review to check the implementation
$stop-that-shit change -- Fix the failing tests
```

The example skills must already be installed in Pi. This extension does not bundle any skills.

- Type `$` to list available skills, continue typing to filter by name prefix, and select one using Pi's completion controls.
- Chinese text can directly border a skill mention, without spaces. Skill names are parsed as ASCII letters, digits, underscores, and hyphens.
- Invoke multiple skills in one message. Each skill is loaded once per message, in order of first appearance.
- The original message and arguments remain unchanged. Full skill bodies are appended with their file locations and base directories for relative references.
- Skill bodies are read fresh on each submission. After adding or removing skills, use `/reload` to refresh Pi's resources.
- Idle input, mid-run steering, queued follow-ups, and RPC user input use the same input transformation hook, preserving delivery behavior and attachments.

## Matching Rules

Only **skills currently loaded by Pi** are expanded. Pi handles discovery, trust, and name-collision priority for global, project, package, and CLI skills. This extension does not scan additional directories.

The following do not trigger loading:

- Unknown names, such as an uninstalled `$unknown` (left unchanged).
- Escaped mentions such as `\$skill-name`, inline code, and backtick- or tilde-fenced code blocks.
- `$$name`, `${name}`, `$name$`, `path/$name`, and `$name/file`.
- `!` / `!!` shell input and messages generated by other extensions through `sendUserMessage`.

A variable such as `$HOME` in ordinary prose will trigger a skill if its name exactly matches an installed skill. Escape it or put it in code to keep it literal.

Native `/skill:name` commands remain handled by Pi. Pi dispatches extension `/command` invocations before this hook, so their arguments are not processed by this extension. Use `$name` in ordinary messages instead.

If a skill cannot be read, the error is appended to the message and shown as a notification when a UI is available. Other successfully read skills still load. Loading a skill does not execute shell commands or grant additional tool permissions.

## Development

Node.js >= 22.19:

```sh
npm ci
npm run check
npm test
```

Tests cover name boundaries, Chinese text, multi-skill deduplication, code and escaping, error handling, autocomplete, input sources and queue modes, and Pi's actual extension loader.

## License

MIT