corrections welcomed

pi-agent-notes.md

notes

Pi resources: skills vs prompts vs extensions (tools/commands)

Type	What it is	How it’s used	Auto-included from	settings.json keys	Notes / capabilities
Skill	SKILL.md (Agent Skills standard) or top-level .md in skills dir	Loaded on demand (/skill:name or auto-detected by model). Expands to instructions.	~/.pi/agent/skills/, .pi/skills/, packages (skills/), settings skills paths	"skills": ["/path", "./dir"], "packages": [...], "enableSkillCommands": true/false	Skill commands are optional (enableSkillCommands). Skills can include scripts/assets. Missing description prevents load.
Prompt template	Markdown snippet (prompt)	User invokes via /name in editor. Expands into full prompt.	~/.pi/agent/prompts/, .pi/prompts/, packages (prompts/), settings prompts paths	"prompts": ["/path", "./dir"], "packages": [...]	No special toggle besides discovery/CLI --no-prompt-templates. Supports positional args ($1, $@, etc.). prompts/ discovery is non-recursive.
Extension	TypeScript module	Runs on startup; can register tools/commands/shortcuts/UI/event handlers	~/.pi/agent/extensions/, .pi/extensions/, packages (extensions/), settings extensions paths	"extensions": ["/path", "./dir"], "packages": [...]	Extensions run with full permissions; can override built-in tools; can customize compaction, UI, etc.
Extension Tool	LLM-callable tool registered by extension	Invoked by the model during a turn	Same as extension (tool must be registered by loaded extension)	(same as extension)	Appears in system prompt; can be blocked via tool_call event; supports custom rendering.
Extension Command	User command registered by extension (/cmd)	Invoked by user in editor; bypasses LLM	Same as extension	(same as extension)	Good for interactive workflows. Supports argument completion. Runs before skill/template expansion.

Package-based reuse

Pi packages can bundle extensions, skills, prompts, themes. Package sources are configured in settings.json under "packages" (global or project). Project settings (.pi/settings.json) override global.

Project vs global scope

• Global: ~/.pi/agent/...
• Project: .pi/...

Project-local settings can be shared with teammates and pull in packages on startup.

CLI flags for resource loading

Flag	Effect	Notes
--no-extensions	Disable extension discovery	Use -e/--extension to load specific extensions even when disabled.
-e, `--extension <path	npm:	git:>`
--no-skills	Disable skill discovery	Use --skill <path> to load specific skills anyway.
--skill <path>	Load skill(s) explicitly	Repeatable. Adds to discovered skills.
--no-prompt-templates	Disable prompt template discovery	Use --prompt-template <path> to load explicit templates.
--prompt-template <path>	Load prompt template(s) explicitly	Repeatable.
--no-themes	Disable theme discovery	Use --theme <path> to load explicit theme(s).
--theme <path>	Load theme explicitly	Repeatable.
--no-tools	Disable built-in tools	Extension tools still available.
--tools <list>	Select built-in tools	e.g., read,bash,edit,write.

LLM vs user exposure (what gets shown to whom)

Resource	Exposed to user (UI)	Exposed to LLM	Notes
Skill	/skill:name command (if enabled) and skill list in header	Skill list (name+description) in system prompt; full SKILL.md only when loaded	Uses progressive disclosure.
Prompt template	/template autocomplete in editor	Expanded into user message when invoked	The LLM sees expanded prompt content.
Extension Tool	Tool call/result UI in chat	Tool schema in system prompt; tool result sent to LLM	Tools are part of agent loop.
Extension Command	Runs in UI only (no LLM)	None (unless it injects messages)	Runs before skill/template expansion.
Extension UI (ctx.ui)	Dialogs/notifications/widgets/etc.	None	Pure UI surface for user.
Extension messages	Custom message display (if display: true)	Sent to LLM as custom message (customType)	Depends on pi.sendMessage() usage.

Extension APIs: expose to LLM vs to user

Goal	API call(s)	Effect
Expose a new callable tool to the LLM	pi.registerTool({ name, description, parameters, execute })	Tool schema in system prompt; LLM can call tool.
Expose a user command	pi.registerCommand("name", { handler, description })	/name becomes a user command (no LLM unless you inject).
Send custom content to LLM (and optionally show in UI)	pi.sendMessage({ customType, content, display, details }, { deliverAs, triggerTurn })	Injects a custom message into session; sent to LLM with customType; display controls UI rendering.
Send a user message (acts like user typed it)	pi.sendUserMessage("text", { deliverAs })	Always triggers an LLM turn.
Show user-only dialogs/notifications	ctx.ui.notify(), ctx.ui.confirm(), ctx.ui.input(), ctx.ui.select(), ctx.ui.custom()	UI only; does not reach LLM.
Render custom message UI	pi.registerMessageRenderer(customType, renderer)	Controls display of custom messages created by sendMessage().