@tunglam/pi-inline-skills

Codex-style inline $skill references for the pi coding agent.

Reference a skill anywhere in your prompt — start, middle, several at once — and the full SKILL.md body is injected alongside your message. Your original text is never rewritten.

you type:   Use $example to help me with X
model sees: ① your message, verbatim ($ token kept)
            ② a companion message with the skill body:

<skill>
<name>example</name>
<path>/abs/path/example/SKILL.md</path>
...SKILL.md body, frontmatter stripped...
</skill>

Install

pi install npm:@tunglam/pi-inline-skills

Requires pi >= 0.79.1 (extension autocomplete triggerCharacters support).

Features

• $ autocomplete at any whitespace boundary, backed by pi's discovered skill list.
• Codex-shaped injection: same <skill><name><path> fragment codex uses, but the body has frontmatter intentionally stripped.
• Multiple mentions per message; each becomes its own <skill> block in one companion message.
• Reminder dedup (default on): if a skill's full body is already in the active session context, a re-mention injects a one-line reminder instead. Edits to SKILL.md (mtime change), compaction, or switching to a branch without the injection all restore full injection automatically.
• Visible receipt: a collapsed aside under your message shows what was injected and its token cost (expand for the raw XML). Toggle with display off.

Configuration

These are user preferences, so config is a single user-level file in your pi agent dir — ~/.pi/agent/inline-skills.json (or ~/.pilot/agent/inline-skills.json on rebranded distributions), the same place other extensions keep their config. Both keys default to true:

{ "reminderDedup": true, "display": true }

Session-scoped toggles (do not persist):

/inline-skills reminder on|off
/inline-skills display on|off

pi has no channel for extension config inside its own settings.json, so this file is the idiomatic home — matching e.g. zentui.json in the same directory.

How it relates to native /skill:name

They coexist. Native /skill:name only works at the very start of a message and replaces your text with the skill body. $name works anywhere and keeps your text intact. Use whichever fits.

Comparison

	codex $skill	pi native /skill:	@tunglam/pi-inline-skills
Position	anywhere	message start only	anywhere
User text	preserved	replaced	preserved
Body	raw file (frontmatter included)	frontmatter stripped	frontmatter stripped
Multiple per message	yes	no	yes
Cross-turn dedup	no (per turn only)	n/a	yes (reminder)

Known limitations

• Messages queued while the agent is streaming (steer / follow-up) do not pass through before_agent_start, so $ mentions in them are not injected — idle turns only.
• Mentions resolve by plain name against the discovered skill list; there is no structured path binding (codex's linked-mention disambiguation). Ambiguous duplicate names resolve to the first discovered skill.
• Autocomplete is TUI-only. Injection still applies to prompts submitted from any client (RPC / GUI), since it runs in the backend.

Development

npm install
npm test
npm run typecheck

Design references: codex skill fragments, pi-skillrefs (MIT) for the injection/receipt architecture, and mention-skills (MIT) for the mention grammar.

License

MIT