# pi-skills-mention
> **Codex-style `$` skill mentions for Pi** · type `$` to pull up the skill list, and reference any number of skills from anywhere in a prompt.
**pi-skills-mention** brings [Codex]-style `$` mentions of skills to the [Pi coding agent]. Instead of remembering `/skill:name` — which only works at the *start* of a message and expands one skill at a time — you write `$` + a skill name **anywhere** in any prompt:
```
review this code with $code-review, then polish the summary with $humanize
```
Type `$` in the input editor and the skill list appears **immediately** — filter as you type, accept with Enter, mention many at once. Just like Codex.
> [**中文文档** → `README.zh.md`](README.zh.md)
---
## ✨ Features
- **`$` anywhere** — mention skills in the middle or end of any message, not just at the start.
- **Multiple at once** — `$code-review $humanize` loads any number of skills in a single message.
- **Instant autocomplete** — type `$` and the skill list pops up immediately; filter live as you type.
- **Safe by default** — only *known* skill names load; `$PATH`, `$FOO`, `$(cmd)` etc. pass through untouched.
- **Prompt never rewritten** — pi stores and displays exactly what you typed, so `/fuck`-style recovery, rewind and re-editing always see your original `$skill` mentions.
- **Escape hatch** — `$$name` renders as a literal `$name`.
---
## Install
```bash
pi install npm:pi-skills-mention
```
Or run from source while developing:
```bash
pi -e /path/to/pi-skills-mention/src/index.ts
```
Restart pi (or `/reload`) after installing, then type `$` in the editor to try it.
---
## Usage
Mention any skill by name, anywhere:
```
$tdd 实现这个功能
先审查 $code-review 再提交
帮我把这份总结 $humanize 一下，顺便 $rewrite 精简
$code-review 与 $humanize 帮我审查 auth 模块的改动，并把结论润色成自然的中文。
```
Each `$skill-name` loads that skill's full `SKILL.md` instructions before the agent runs — the same `` blocks pi itself uses for `/skill:name`. Your prompt itself is **never rewritten**: pi stores and displays exactly what you typed (with the `$skill` mentions), and the skill contents arrive as a separate context message. The TUI renders it as a compact `✦ skills-mention: name + name (ctrl+o to expand)` line — expand it to see the full skill contents.
Because the stored prompt is your original text, prompt-recovery commands like `/fuck` (pi-wtf), rewind and re-editing all work on your original mentions — no skill-text dump in the editor.
**Autocomplete:** press `$`, the skill picker opens immediately with the full list. Keep typing to narrow it. Press Enter (or arrow + Enter) to insert the selected `$skill-name`.
### Tips & edges
- **Loaded-skills rendering** — mentioned skills show up in the chat as one compact line (`✦ skills-mention: a + b`, `ctrl+o` to expand the full contents). Skills already loaded on the same session branch are not injected again.
- **Fuzzy autocomplete** — `$` matching is fuzzy, not prefix-only: `$impv` matches `improve-codebase`-style skills (letters in order, not necessarily consecutive). Prefix matches still rank first.
- Skills resolve greedily to the **longest known match**: if both `code-review` and `code-review-module` exist, `$code-review-module` uses the bigger one.
- A token that isn't a known skill stays literal — `$HOME`, `$PATH`, `$(cmd)` are untouched.
- Use `$$name` to force a literal `$name`.
- Skill names come from the same set pi already loaded into the session (`systemPromptOptions.skills`), kept in sync every turn; on the very first turn it falls back to pi's own discovery (`~/.pi/agent/skills`, `/.pi/skills`, `~/.agents/skills`, ancestor `.agents/skills`).
---
## How it works
| Module | Role |
| --- | --- |
| `src/mention.ts` | `$token` → skill-block expansion |
| `src/autocomplete.ts` | `$`-triggered autocomplete provider wrapper |
| `src/discover.ts` | session skill cache + first-turn discovery |
| `src/skill-registry.ts` | skill indexing + block building |
- **Discovery** uses the skills pi already loaded into the session; on the first turn it falls back to pi's exported `loadSkills` seeder.
- **Expansion** happens in the `input` event (via `transform`), so `$` works on every turn and in any position — escaping pi's single-start-only `/skill:` limitation.
- **Autocomplete** wraps pi's built-in provider through `ctx.ui.addAutocompleteProvider`: it only takes over when the cursor sits inside a `$` mention token, otherwise it delegates to the original (commands, files, `@`-paths …). **Native `/` commands and `/skill:` are never disabled** — `$` is purely additive.
---
## Development
```bash
npm install
npm test # unit tests (expansion + autocomplete)
npm run typecheck
npm run build
npm pack # inspect publish contents
```
## Gallery preview
The image below is what shows up on the [pi.dev package gallery](https://pi.dev/):
---
## License
MIT
[Codex]: https://openai.com/codex
[Pi coding agent]: https://pi.dev