obsidian-vault/300 areas/350 AI/Pi Agent Extensions & Skills.md

created, modified, type, tags, aliases

created	modified	type	tags	aliases
2026-05-16	2026-05-16	note	ai dev-ops

Pi Agent Extensions & Skills

Source Repositories

Source	Location
Gitea (package)	git:https://gitea.lab.audasmedia.com.au/sam/pi-config
Local filesystem	~/.agents/
Project settings	sys_config/.pi/settings.json, ai_setup/.pi/settings.json

---

Extensions

Extension	Source	Purpose
pi-config	~/.agents	/config-add, /config-remove, /config-show, /config-setup — manage which extensions/skills are active in a project
tavily-search	Gitea	tavily_search — web search via Tavily API (AI-optimized)
web-fetch	~/.agents	web_fetch — fetch any URL and return clean markdown (HTML, PDF, JS-rendered with Jina fallback)
ask-user-question	~/.agents	ask_user_question — LLM presents structured multiple-choice / text questions with keyboard UI
video-extract	~/.agents	video_extract — extract frames from YouTube/local video + full Gemini analysis (requires ffmpeg + yt-dlp + GEMINI_API_KEY)
filechanges	~/.agents	/filechanges, /filechanges-accept, /filechanges-decline — tracks every file LLM edits/writes, diff review, revert
pi-subagents (nicopreme)	npm (global)	Spawn child Pi agents with chains, parallel execution, async dispatch. /agents command. Integrates with pi-prompt-template-model for delegated prompt execution
pi-prompt-template-model	npm (global)	Model-switching prompt templates with frontmatter. See #Prompt Templates section below
pi-mcp-adapter	npm (global)	Single proxy tool (~200 tokens) replaces hundreds of MCP tool definitions. /mcp command for management. Lazy server connections
pi-graphify	~/.agents	Knowledge graph tools: build, query, path tracing, explain, watch, add, update
plannotator	~/.agents	Interactive plan review with browser UI, annotations, code review
caveman	~/.agents	Ultra-compressed communication mode

---

Skills

Skill	Purpose
nixos-workflow	STRICT workflow for managing Pi assets via Gitea on NixOS
system-architect	Multi-machine NixOS infrastructure (Snapcast, MQTT, Docker, Nvim)
obsidian-cli	Interact with Obsidian vault (notes, search, plugin dev, theme dev)
graphify	Full-pipeline knowledge graph orchestration
caveman	Caveman communication mode
openspec-propose	Propose new changes with design docs, specs, tasks
openspec-apply-change	Implement tasks from an OpenSpec change
openspec-archive-change	Archive completed changes
openspec-explore	Explore ideas and clarify requirements

---

Prompt Templates

Prompt templates are .md files in ~/.pi/agent/prompts/ with YAML frontmatter. Each defines a slash command that auto-switches model, thinking level, and injects skills — then restores your previous model when done.

Installed Templates

Command	Tier	Model	Use
/quick	⚡ flash	deepseek-v4-flash	General everyday tasks
/think	🧠 ultra	openrouter/deepseek-pro	Deep thinking, hard problems
/check	🔷 pro	opencode-go/deepseek-pro	Code review, quality checks
/nix-check	⚡ flash	deepseek-v4-flash	Nix flake checks, config debug
/note	⚡ flash	deepseek-v4-flash	Create Obsidian .md with frontmatter
/sort	🔷 pro	opencode-go/deepseek-pro	Classify files, suggest Obsidian folder
/read	⚡ flash	deepseek-v4-flash	Batch read and synthesize many files
/debug	🧠 ultra	openrouter/deepseek-pro	Complex NixOS/infra debugging
/vault	🔷 pro	opencode-go/deepseek-pro	Obsidian vault setup and management
/chat	⚡ flash	deepseek-v4-flash	Chat with automatic web search
/img	🧠 ultra	openrouter/deepseek-pro	Image analysis and description
/make-img	⚡ flash	deepseek-v4-flash	Generate images via OpenRouter API (Flux/Stable Diffusion)

Audio/Voice note: Pi runs in a text-based terminal (TUI) with no microphone access or audio playback. Qwen supports audio processing, but it's not practical in Pi's current architecture regardless of model.

How to use

/quick what's the weather?
/think design the architecture for this feature
/check review the changes in this file
/nix-check analyze the nix flake check output
/note document the new service setup
/sort read this config file and tell me where it goes
/read skim these three config files and compare them
/debug why is my NixOS build failing?
/vault set up a template for daily notes
/chat what's new in NixOS 25.11?
/img what's wrong in this screenshot?
/make-img a futuristic cityscape with neon lights

Template format

---
description: Quick task — fast model, minimal thinking
model: openrouter/deepseek-v4-flash
restore: true
---
$@

Key frontmatter fields:

• model — provider/model-id or comma-separated fallback list
• thinking — off, minimal, low, medium, high, xhigh
• restore — (default true) restore previous model when done
• skill — auto-inject a skill
• deterministic — run a command/script before the LLM turn (e.g. nix eval .#checks)

Adding new templates

Create a new .md file in ~/.pi/agent/prompts/ with frontmatter. The filename becomes the command name. Restart Pi or run any extension command to pick them up.

---

MCP Servers

pi-mcp-adapter connects Pi to external services via the Model Context Protocol.

Config file: ~/.config/mcp/mcp.json

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/sam"]
    }
  }
}

Find MCP servers at:

• github.com/modelcontextprotocol/servers
• smithery.ai — community registry

Usage:

• /mcp — interactive panel to manage servers
• mcp({ search: "..." }) — search available tools
• mcp({ tool: "tool_name", args: '{}' }) — call a tool
• Servers are lazy (connect on first use, disconnect after 10 min idle)

---

Configuration Files

Global (~/.pi/agent/settings.json)

• Nix store symlink — managed via /etc/nixos/home/sam/home.nix
• Contains: providers (opencode-go, openrouter, google), packages (pi-memctx, pi-prompt-template-model, Gitea)
• Read-only — cannot be modified by pi install or /config-add

Project (<project-dir>/.pi/settings.json)

• Overrides global settings (arrays replace, not merge)
• Contains: ~/.agents package (extensions + skills), Gitea package (tavily-search)
• Modified via /config-add / /config-remove commands

Per-folder Memory (via pi-memctx)

• Memory stored in <chat-folder>/.pi/memory-vault/packs/
• Workspace map at ~/.pi/agent/memory-vault/00-system/workspace-map.json
• Each chat folder has isolated memory (prevents sibling directory contamination)

---

Useful Commands

Command	What it does
/quick <task>	Fast model for everyday tasks
/think <task>	Ultra model for deep analysis
/check <path>	Pro model for code review
/nix-check <task>	Nix-specific analysis
/note <description>	Create Obsidian note with frontmatter
/sort <path>	Classify file, suggest Obsidian folder
/read <paths>	Batch read and synthesize files
/debug <issue>	Complex NixOS/infra debugging
/vault <task>	Obsidian vault setup and management
/chat <topic>	Conversation with web search
/img <prompt>	Image analysis and description
/make-img <prompt>	Generate image via OpenRouter API
/config-setup	One-shot: creates .pi/, settings.json, memory vault in current folder
/config-add ext <name>	Activate an extension from ~/.agents
/config-add skill <name>	Activate a skill from ~/.agents
/config-show	Show active extensions and skills
/memctx-init	Scan folder, build initial memory pack
/memctx-status	Show memory status
/memctx-refresh	Re-scan and enrich memory
/filechanges	Review changed files, diffs, accept/decline
/filechanges-accept	Accept all changes
/filechanges-decline	Revert all changes

---

Skipped / Bookmarked

Extension/Skill	Reason
web-search (amosblomqvist)	❌ Redundant — Tavily does this
subagents (amosblomqvist)	❌ Redundant — pi-subagents already installed
bash-guard (amosblomqvist)	❌ Too aggressive — would interrupt flow
google-image-search (amosblomqvist)	❌ Would need Google Search API + CSE setup
pdf-reader (amosblomqvist)	⏳ Bookmarked — Python + pymupdf setup needed
notify (mitsuhiko)	⏳ Minor QoL — desktop notifications on task complete
audio/voice	⏳ Not practical

---

Tasks

• Rebuild NixOS to activate new packages (Google provider, ffmpeg/yt-dlp, pi-prompt-template-model, pi-mcp-adapter, pi-subagents)
• Add MCP servers to ~/.config/mcp/mcp.json or .mcp.json as needed (Home Assistant, databases, etc.)
• Run /reload in Pi to activate filechanges and new templates
• Add more prompt templates to ~/.pi/agent/prompts/ as needed
• Verify video-extract works with Gemini
• Clean up workspace-map.json entries for any stale memory packs