@chankov/agent-skills 0.1.0

package/.versions/0.1.0/.claude/commands/prime.md

@@ -0,0 +1,22 @@
+---
+description: Load foundational context for the agent-skills repository
+---
+
+# Purpose
+
+Orient yourself in **agent-skills** — a collection of production-grade engineering skills
+for AI coding agents, plus pi extensions, specialist agent personas, and lifecycle
+commands that map to the software development lifecycle.
+
+## Workflow
+
+1. Run `git ls-files` to see the full project file tree
+2. Read `README.md` and `CLAUDE.md` for the project overview and conventions
+3. Read `docs/skill-anatomy.md` to learn the required skill format
+4. Skim `skills/*/SKILL.md` — the core skills, grouped by lifecycle phase
+   (Define → Plan → Build → Verify → Review → Ship)
+5. Read `agents/*.md` — the specialist review personas
+6. Read `docs/pi-extensions.md`, `.pi/extensions/*/README.md` (always-on utilities), and `.pi/harnesses/*/README.md` (selectable session harnesses)
+7. Summarize your understanding: purpose, structure, key files, and entry points
+
+Do this directly — read the files yourself rather than delegating to subagents.

package/.versions/0.1.0/.claude/commands/review.md

@@ -0,0 +1,16 @@
+---
+description: Conduct a five-axis code review — correctness, readability, architecture, security, performance
+---
+
+Invoke the agent-skills:code-review-and-quality skill.
+
+Review the current changes (staged or recent commits) across all five axes:
+
+1. **Correctness** — Does it match the spec? Edge cases handled? Tests adequate?
+2. **Readability** — Clear names? Straightforward logic? Well-organized?
+3. **Architecture** — Follows existing patterns? Clean boundaries? Right abstraction level?
+4. **Security** — Input validated? Secrets safe? Auth checked? (Use security-and-hardening skill)
+5. **Performance** — No N+1 queries? No unbounded ops? (Use performance-optimization skill)
+
+Categorize findings as Critical, Important, or Suggestion.
+Output a structured review with specific file:line references and fix recommendations.

package/.versions/0.1.0/.claude/commands/setup.md

@@ -0,0 +1,19 @@
+---
+description: Guided setup — install agent-skills artifacts into a workspace for a chosen coding agent
+---
+
+Invoke the agent-skills:guided-workspace-setup skill.
+
+Run the guided install for a target workspace. If the user passed a workspace path, use it; otherwise ask for it. Detect the running coding agent and confirm it with the user.
+
+Analyse the workspace. If prior install state is found (`.ai/agent-skills-setup.md` or a populated agent directory), run the **Doctor preflight** first (Step 5) — scan for broken symlinks and stale persona references, present findings as a table, and apply the fixes the user picks before continuing.
+
+Then present the install menu as **one multi-select per group** (18 groups across skills, personas, commands, pi extensions/harnesses, references, hooks) with `★` marking recommendations. Each group renders as a `Pick | Item | Status | Rec | Purpose` table; every row carries an explicit status text — `installed · up to date`, `installed · outdated`, `installed · modified`, `not installed`, or `broken · skipped in preflight`. Installed items are **pre-checked `[x]`** so unchecking = remove; not-installed items start `[ ]`. Per-group reply shortcuts: `all`, `recommended` (adds `★` items on top of the pre-selection — never unticks installed ones), `none`, `keep` (accept the pre-selection unchanged), or a list of picks. Never offer `setup`, `doctor`, or `guided-workspace-setup` — those are installer-only and live in the source agent-skills repo.
+
+Unchecking an installed item means *remove it*, but **removal is scoped**: only act on items whose name is in the agent-skills inventory **and** that are recorded in `## install-status` (or are symlinks resolving into the source repo). User-authored skills, custom commands, third-party plugins, and unrelated settings/env keys are left untouched and logged as "Skipped — not owned by agent-skills".
+
+**No cross-tool substitution.** Each row is offered only when the source file the chosen agent needs already exists — for `pi`, that means `.pi/prompts/<name>.md`, `.pi/extensions/<name>/`, etc. Never fall back to `.claude/commands/` (or another agent's tree) to satisfy a pi prompt request; items missing their per-agent source are filtered out of the menu entirely.
+
+**No mid-apply overwrite prompts.** The Step 6 status text already warns that `installed · modified` rows will have local edits overwritten if kept ticked. The user's tick is the consent; the Step 9 confirmation is the single gate. During apply, refresh ticked items unconditionally — never pause to ask "should I overwrite this file?". Genuine errors (permission denied, missing source) still stop and report.
+
+Offer override sections for the workspace's `.ai/agent-skills-overrides.md` based on the analysis, and record what was installed in `.ai/agent-skills-setup.md`. Summarise the full plan and wait for explicit confirmation before writing anything, then perform the setup, re-scan for any new breakage, and report what changed.

package/.versions/0.1.0/.claude/commands/ship.md

@@ -0,0 +1,17 @@
+---
+description: Run the pre-launch checklist and prepare for production deployment
+---
+
+Invoke the agent-skills:shipping-and-launch skill.
+
+Run through the complete pre-launch checklist:
+
+1. **Code Quality** — Tests pass, build clean, lint clean, no TODOs, no console.logs
+2. **Security** — npm audit clean, no secrets in code, auth in place, headers configured
+3. **Performance** — Core Web Vitals good, no N+1 queries, images optimized, bundle sized
+4. **Accessibility** — Keyboard nav works, screen reader compatible, contrast adequate
+5. **Infrastructure** — Env vars set, migrations ready, monitoring configured
+6. **Documentation** — README current, ADRs written, changelog updated
+
+Report any failing checks and help resolve them before deployment.
+Define the rollback plan before proceeding.

package/.versions/0.1.0/.claude/commands/spec.md

@@ -0,0 +1,15 @@
+---
+description: Start spec-driven development — write a structured specification before writing code
+---
+
+Invoke the agent-skills:spec-driven-development skill.
+
+Begin by understanding what the user wants to build. Ask clarifying questions about:
+1. The objective and target users
+2. Core features and acceptance criteria
+3. Tech stack preferences and constraints
+4. Known boundaries (what to always do, ask first about, and never do)
+
+Then generate a structured spec covering all six core areas: objective, commands, project structure, code style, testing strategy, and boundaries.
+
+Save the spec to the location the `spec-driven-development` skill defines (default `docs/prds/{area}/PRD{n}-{topic}.md`; overridable per project via `.ai/agent-skills-overrides.md`). Confirm with the user before proceeding.

package/.versions/0.1.0/.claude/commands/test.md

@@ -0,0 +1,19 @@
+---
+description: Run TDD workflow — write failing tests, implement, verify. For bugs, use the Prove-It pattern.
+---
+
+Invoke the agent-skills:test-driven-development skill.
+
+For new features:
+1. Write tests that describe the expected behavior (they should FAIL)
+2. Implement the code to make them pass
+3. Refactor while keeping tests green
+
+For bug fixes (Prove-It pattern):
+1. Write a test that reproduces the bug (must FAIL)
+2. Confirm the test fails
+3. Implement the fix
+4. Confirm the test passes
+5. Run the full test suite for regressions
+
+For browser-related issues, also invoke agent-skills:browser-testing-with-devtools to verify with Chrome DevTools MCP.

package/.versions/0.1.0/.opencode/commands/as-build.md

@@ -0,0 +1,17 @@
+---
+description: Implement the next task incrementally - build, test, verify, commit
+---
+
+Invoke the `incremental-implementation` skill and the `test-driven-development` skill via the `skill` tool.
+
+Pick the next pending task from the plan. For each task:
+
+1. Read the task's acceptance criteria.
+2. Load relevant context: existing code, patterns, and types.
+3. Write a failing test for the expected behavior.
+4. Implement the minimum code to pass the test.
+5. Run the relevant test suite to check for regressions.
+6. Run the build to verify compilation.
+7. Mark the task complete and move to the next one.
+
+If any step fails, invoke the `debugging-and-error-recovery` skill via the `skill` tool.

package/.versions/0.1.0/.opencode/commands/as-code-simplify.md

@@ -0,0 +1,16 @@
+---
+description: Simplify code for clarity and maintainability without changing behavior
+---
+
+Invoke the `code-simplification` skill via the `skill` tool.
+
+Simplify recently changed code, or the scope specified in `$ARGUMENTS`, while preserving exact behavior:
+
+1. Read the project's agent instructions and study project conventions.
+2. Identify the target code: recent changes unless a broader scope is specified.
+3. Understand the code's purpose, callers, edge cases, and test coverage before touching it.
+4. Scan for simplification opportunities: deep nesting, long functions, nested ternaries, generic names, duplicated logic, or dead code.
+5. Apply each simplification incrementally and run relevant tests after each change.
+6. Verify tests pass, the build succeeds, and the diff is clean.
+
+If tests fail after a simplification, revert only that simplification and reconsider. Invoke `code-review-and-quality` via the `skill` tool to review the result.

package/.versions/0.1.0/.opencode/commands/as-design-agent.md

@@ -0,0 +1,15 @@
+---
+description: Design and write a new agent persona, workflow skill, or pi harness
+---
+
+Invoke the `designing-agents` skill via the `skill` tool.
+
+Begin by understanding what the user wants to author:
+
+1. Is this a persona (a role or lens the agent adopts), a skill (a repeatable workflow with gated steps and verification), or a pi harness (a TypeScript pi extension that reshapes the session)?
+2. What is the one-sentence purpose and when should it be invoked?
+3. What framework or steps should it follow?
+4. What are the explicit non-goals and scope limits?
+5. What output shape should a typical invocation produce?
+
+Then scan the target location — `agents/`, `skills/`, or `.pi/harnesses/` — for overlap. Draft the artifact using the matching template, verify the draft against prompting guidance when available, and confirm with the user before writing the file(s).

package/.versions/0.1.0/.opencode/commands/as-doctor.md

@@ -0,0 +1,11 @@
+---
+description: Scan agent-skills install targets for broken symlinks and stale persona references, then offer repairs
+---
+
+Invoke the Doctor step from the `guided-workspace-setup` skill (Step 10) via the `skill` tool — without running the rest of the install flow.
+
+Walk every install-target directory the chosen coding agent uses (`agents/`, `.claude/agents/`, `.opencode/agents/`, `.codex/agents/`, `.gemini/agents/`, `.github/agents/`, `.pi/agents/` and `pi-pi/`, `.claude/skills/`, `.opencode/skills/`, `.pi/skills/`, `.agents/skills`, `.claude/commands/`, `.opencode/commands/`, `.pi/prompts/`, `.claude/references/`, `.claude/hooks/`). For each broken symlink, resolve where it pointed, look for a canonical replacement in the source `agents/` and `skills/` trees, and offer to repoint or delete. Common stale names from the pre-merge persona layout: `reviewer` → `code-reviewer`, `red-team` → `security-auditor`.
+
+Also flag and offer to rewrite any YAML configs (`teams.yaml`, `agent-chain.yaml`, etc.) that still reference removed persona names.
+
+Never overwrite a regular file — only act on symlinks whose target is missing. Report `repaired`, `deleted`, and `skipped` counts, and append a `## doctor-runs` line to `.ai/agent-skills-setup.md` with the date and counts.

package/.versions/0.1.0/.opencode/commands/as-plan.md

@@ -0,0 +1,16 @@
+---
+description: Break work into small verifiable tasks with acceptance criteria and dependency ordering
+---
+
+Invoke the `planning-and-task-breakdown` skill via the `skill` tool.
+
+Read the existing spec, such as `SPEC.md`, and relevant codebase sections. Then:
+
+1. Enter planning mode: read only, no code changes.
+2. Identify the dependency graph between components.
+3. Slice work vertically, with one complete path per task rather than horizontal layers.
+4. Write tasks with acceptance criteria and verification steps.
+5. Add checkpoints between phases.
+6. Present the plan for human review.
+
+Save the plan to the location the `planning-and-task-breakdown` skill defines (default `docs/plans/{area}/PLAN-{prd-name}-{phase}.md`, with the task list embedded — no separate todo file; overridable per project via `.ai/agent-skills-overrides.md`), only after the user confirms the plan should be written.

package/.versions/0.1.0/.opencode/commands/as-prime.md

@@ -0,0 +1,22 @@
+---
+description: Load foundational context for the agent-skills repository
+---
+
+# Purpose
+
+Orient yourself in **agent-skills** — a collection of production-grade engineering skills
+for AI coding agents, plus pi extensions, specialist agent personas, and lifecycle
+commands that map to the software development lifecycle.
+
+## Workflow
+
+1. Run `git ls-files` to see the full project file tree
+2. Read `README.md` and `CLAUDE.md` for the project overview and conventions
+3. Read `docs/skill-anatomy.md` to learn the required skill format
+4. Skim `skills/*/SKILL.md` — the core skills, grouped by lifecycle phase
+   (Define → Plan → Build → Verify → Review → Ship)
+5. Read `agents/*.md` — the specialist review personas
+6. Read `docs/pi-extensions.md`, `.pi/extensions/*/README.md` (always-on utilities), and `.pi/harnesses/*/README.md` (selectable session harnesses)
+7. Summarize your understanding: purpose, structure, key files, and entry points
+
+Do this directly — read the files yourself rather than delegating to subagents.

package/.versions/0.1.0/.opencode/commands/as-review.md

@@ -0,0 +1,15 @@
+---
+description: Conduct a five-axis code review - correctness, readability, architecture, security, performance
+---
+
+Invoke the `code-review-and-quality` skill via the `skill` tool.
+
+Review the current changes, staged changes, or scope specified in `$ARGUMENTS` across these axes:
+
+1. Correctness: Does it match the spec? Are edge cases handled? Are tests adequate?
+2. Readability: Are names clear? Is the logic straightforward and well organized?
+3. Architecture: Does it follow existing patterns? Are boundaries clean? Is the abstraction level right?
+4. Security: Is input validated? Are secrets safe? Is authorization checked? Invoke `security-and-hardening` via the `skill` tool when relevant.
+5. Performance: Are there N+1 queries, unbounded operations, or avoidable frontend regressions? Invoke `performance-optimization` via the `skill` tool when relevant.
+
+Categorize findings as Critical, Important, or Suggestion. Output a structured review with specific file and line references plus fix recommendations.

package/.versions/0.1.0/.opencode/commands/as-setup.md

@@ -0,0 +1,11 @@
+---
+description: Guided setup — install agent-skills artifacts into a workspace for a chosen coding agent
+---
+
+Invoke the `guided-workspace-setup` skill via the `skill` tool.
+
+Run the guided install for a target workspace. If the user passed a workspace path, use it; otherwise ask for it. Detect the running coding agent and confirm it with the user.
+
+Analyse the workspace, then present a checklist of installable artifacts — skills, agent personas, commands/prompts, pi extensions and harnesses, references, and hooks — marking what is already installed.
+
+Offer override sections for the workspace's `.ai/agent-skills-overrides.md` based on a brief analysis of the project, and record what was installed in `.ai/agent-skills-setup.md`. Summarise the full plan and wait for explicit confirmation before writing anything, then perform the setup and report what changed.

package/.versions/0.1.0/.opencode/commands/as-ship.md

@@ -0,0 +1,16 @@
+---
+description: Run the pre-launch checklist and prepare for production deployment
+---
+
+Invoke the `shipping-and-launch` skill via the `skill` tool.
+
+Run through the complete pre-launch checklist:
+
+1. Code quality: tests pass, build clean, lint clean, no stray TODOs or console logs.
+2. Security: dependency audit checked, no secrets in code, auth in place, headers configured where applicable.
+3. Performance: Core Web Vitals or relevant performance checks are acceptable, no N+1 queries, images and bundles are reasonable.
+4. Accessibility: keyboard navigation works, screen reader semantics are acceptable, contrast is adequate.
+5. Infrastructure: environment variables are set, migrations are ready, monitoring is configured.
+6. Documentation: README is current, ADRs are written when needed, changelog is updated when relevant.
+
+Report any failing checks and help resolve them before deployment. Define the rollback plan before proceeding.

package/.versions/0.1.0/.opencode/commands/as-spec.md

@@ -0,0 +1,16 @@
+---
+description: Start spec-driven development by writing a structured specification before code
+---
+
+Invoke the `spec-driven-development` skill via the `skill` tool.
+
+Begin by understanding what the user wants to build. Ask clarifying questions about:
+
+1. The objective and target users.
+2. Core features and acceptance criteria.
+3. Tech stack preferences and constraints.
+4. Known boundaries: what to always do, ask first about, and never do.
+
+Then generate a structured spec covering objective, commands, project structure, code style, testing strategy, and boundaries.
+
+Confirm with the user before saving, then save the spec to the location the `spec-driven-development` skill defines (default `docs/prds/{area}/PRD{n}-{topic}.md`; overridable per project via `.ai/agent-skills-overrides.md`).

package/.versions/0.1.0/.opencode/commands/as-test.md

@@ -0,0 +1,21 @@
+---
+description: Run a TDD workflow - write failing tests, implement, verify
+---
+
+Invoke the `test-driven-development` skill via the `skill` tool.
+
+For new features:
+
+1. Write tests that describe the expected behavior and confirm they fail.
+2. Implement the code to make them pass.
+3. Refactor while keeping tests green.
+
+For bug fixes, use the Prove-It pattern:
+
+1. Write a test that reproduces the bug and must fail.
+2. Confirm the test fails.
+3. Implement the fix.
+4. Confirm the test passes.
+5. Run the relevant full test suite for regressions.
+
+For browser-related issues, also invoke `browser-testing-with-devtools` via the `skill` tool to verify with Chrome DevTools MCP.

package/.versions/0.1.0/.pi/agents/agent-chain.yaml

@@ -0,0 +1,49 @@
+plan-build-review:
+  description: "Plan, implement, and review — the standard development cycle"
+  steps:
+    - agent: planner
+      prompt: "Plan the implementation for: $INPUT"
+    - agent: builder
+      prompt: "Implement the following plan:\n\n$INPUT"
+    - agent: code-reviewer
+      prompt: "Review this implementation for bugs, style, and correctness:\n\n$INPUT"
+
+plan-build:
+  description: "Plan then build — fast two-step implementation without review"
+  steps:
+    - agent: planner
+      prompt: "Plan the implementation for: $INPUT"
+    - agent: builder
+      prompt: "Based on this plan, implement:\n\n$INPUT"
+
+scout-flow:
+  description: "Triple-scout deep recon — explore, validate, verify"
+  steps:
+    - agent: scout
+      prompt: "Explore the codebase and investigate: $INPUT\n\nReport your findings with structure, key files, and patterns."
+    - agent: scout
+      prompt: "Validate and cross-check the following analysis. Look for anything missed, incorrect, or incomplete:\n\n$INPUT\n\nOriginal request: $ORIGINAL"
+    - agent: scout
+      prompt: "Final review pass. Verify the analysis below is accurate and complete. Add any missing details or corrections:\n\n$INPUT\n\nOriginal request: $ORIGINAL"
+
+plan-review-plan:
+  description: "Iterative planning — plan, critique, then refine with feedback"
+  steps:
+    - agent: planner
+      prompt: "Create a detailed implementation plan for: $INPUT"
+    - agent: plan-reviewer
+      prompt: "Critically review this implementation plan. Challenge assumptions, find gaps, and suggest improvements:\n\n$INPUT\n\nOriginal request: $ORIGINAL"
+    - agent: planner
+      prompt: "Revise and improve your implementation plan based on this critique. Address every issue raised and incorporate the recommendations:\n\nOriginal request: $ORIGINAL\n\nCritique:\n$INPUT"
+
+full-review:
+  description: "End-to-end pipeline — scout, plan, build, and review"
+  steps:
+    - agent: scout
+      prompt: "Explore the codebase and identify: $INPUT"
+    - agent: planner
+      prompt: "Based on this analysis, create a plan:\n\n$INPUT"
+    - agent: builder
+      prompt: "Implement this plan:\n\n$INPUT"
+    - agent: code-reviewer
+      prompt: "Review this implementation:\n\n$INPUT"

package/.versions/0.1.0/.pi/agents/bowser.md

@@ -0,0 +1,19 @@
+---
+name: bowser
+description: Headless browser automation agent using Playwright CLI. Use when you need headless browsing, parallel browser sessions, UI testing, screenshots, or web scraping. Supports parallel instances. Keywords - playwright, headless, browser, test, screenshot, scrape, parallel, bowser.
+model: opus
+color: orange
+skills:
+  - playwright-bowser
+---
+
+# Playwright Bowser Agent
+
+## Purpose
+
+You are a headless browser automation agent. Use the `playwright-bowser` skill to execute browser requests.
+
+## Workflow
+
+1. Execute the `/playwright-bowser` skill with the user's prompt — derive a named session and run `playwright-bowser` commands
+2. Report the results back to the caller

package/.versions/0.1.0/.pi/agents/pi-pi/agent-expert.md

@@ -0,0 +1,98 @@
+---
+name: agent-expert
+description: Pi agent definitions expert — knows the .md frontmatter format for agent personas (name, description, tools, system prompt), teams.yaml structure, agent-team orchestration, and session management
+tools: read,grep,find,ls,bash
+---
+You are an agent definitions expert for the Pi coding agent. You know EVERYTHING about creating agent personas and team configurations.
+
+## Your Expertise
+
+### Agent Definition Format
+Agent definitions are Markdown files with YAML frontmatter + system prompt body:
+
+```markdown
+---
+name: my-agent
+description: What this agent does
+tools: read,grep,find,ls
+---
+You are a specialist agent. Your system prompt goes here.
+Include detailed instructions about the agent's role, constraints, and behavior.
+```
+
+### Frontmatter Fields
+- `name` (required): lowercase, hyphenated identifier (e.g., `scout`, `builder`, `red-team`)
+- `description` (required): brief description shown in catalogs and dispatchers
+- `tools` (required): comma-separated Pi tools this agent can use
+  - Read-only: `read,grep,find,ls`
+  - Full access: `read,write,edit,bash,grep,find,ls`
+  - With bash for scripts: `read,grep,find,ls,bash`
+
+### Available Tools for Agents
+- `read` — read file contents
+- `write` — create/overwrite files
+- `edit` — modify existing files (find/replace)
+- `bash` — execute shell commands
+- `grep` — search file contents with regex
+- `find` — find files by pattern
+- `ls` — list directory contents
+
+### Agent File Locations
+- `.pi/agents/*.md` — project-local (most common)
+- `.claude/agents/*.md` — cross-agent compatible
+- `agents/*.md` — project root
+
+### Teams Configuration (teams.yaml)
+Teams are defined in `.pi/agents/teams.yaml`:
+
+```yaml
+team-name:
+  - agent-one
+  - agent-two
+  - agent-three
+
+another-team:
+  - agent-one
+  - agent-four
+```
+
+- Team names are freeform strings
+- Members reference agent `name` fields (case-insensitive)
+- An agent can appear in multiple teams
+- First team in the file is the default on session start
+
+### System Prompt Best Practices
+- Be specific about the agent's role and constraints
+- Include what the agent should and should NOT do
+- Mention tools available and when to use each
+- Add domain-specific instructions and patterns
+- Keep prompts focused — one clear specialty per agent
+
+### Session Management
+- `--session <file>` for persistent sessions (agent remembers across invocations)
+- `--no-session` for ephemeral one-shot agents
+- `-c` flag to continue/resume an existing session
+- Session files stored in `.pi/agent-sessions/`
+
+### Agent Orchestration Patterns
+- **Dispatcher**: Primary agent delegates via dispatch_agent tool
+- **Pipeline**: Sequential chain of agents (scout → planner → builder → reviewer)
+- **Parallel**: Multiple agents query simultaneously, results collected
+- **Specialist team**: Each agent has a narrow domain, orchestrator routes work
+
+## CRITICAL: First Action
+Before answering ANY question, you MUST search the local codebase for existing agent definitions and team configurations:
+
+```bash
+firecrawl scrape https://raw.githubusercontent.com/badlogic/pi-mono/refs/heads/main/packages/coding-agent/docs/extensions.md -f markdown -o /tmp/pi-agent-ext-docs.md || curl -sL https://raw.githubusercontent.com/badlogic/pi-mono/refs/heads/main/packages/coding-agent/docs/extensions.md -o /tmp/pi-agent-ext-docs.md
+```
+
+Then read /tmp/pi-agent-ext-docs.md for the latest extension patterns (agent orchestration is built via extensions). Also search `.pi/agents/` for existing agent definitions and `extensions/` for orchestration patterns.
+
+## How to Respond
+- Provide COMPLETE agent .md files with proper frontmatter and system prompts
+- Include teams.yaml entries when creating teams
+- Show the full directory structure needed
+- Write detailed, specific system prompts (not vague one-liners)
+- Recommend appropriate tool sets based on the agent's role
+- Suggest team compositions for multi-agent workflows

package/.versions/0.1.0/.pi/agents/pi-pi/cli-expert.md

@@ -0,0 +1,41 @@
+---
+name: cli-expert
+description: Pi CLI expert — knows all command line arguments, flags, environment variables, subcommands, output modes, and non-interactive usage
+tools: read,grep,find,ls,bash
+---
+You are a CLI expert for the Pi coding agent. You know EVERYTHING about running Pi from the command line.
+
+## Your Expertise
+- Basic usage: `pi [options] [@files...] [messages...]`
+- Output modes: interactive (default), `--mode json` (for programmatic parsing), `--mode rpc`
+- Non-interactive execution: `-p` or `--print` (process prompt and exit)
+- Tool control: `--tools read,grep,ls`, `--no-tools` (read-only and safe modes)
+- Discovery control: `--no-session`, `--no-extensions`, `--no-skills`, `--no-themes`
+- Explicit loading: `-e extensions/custom.ts`, `--skill ./my-skill/`
+- Model selection: `--model provider/id`, `--models` for cycling, `--list-models`, `--thinking high`
+- Session management: `-c` (continue), `-r` (resume picker), `--session <path>`
+- Content injection: `@file.md` syntax, `--system-prompt`, `--append-system-prompt`
+- Package management subcommands: `pi install`, `pi remove`, `pi update`, `pi list`, `pi config`
+- Exporting: `pi --export session.jsonl output.html`
+- Environment variables: PI_CODING_AGENT_DIR, API keys (ANTHROPIC_API_KEY, GEMINI_API_KEY, etc.)
+
+## CRITICAL: First Action
+Before answering ANY question, you MUST run the `pi --help` command to fetch the absolute latest flag definitions:
+
+```bash
+pi --help > /tmp/pi-cli-help.txt && cat /tmp/pi-cli-help.txt
+```
+
+You must also check the main README for CLI examples using firecrawl:
+```bash
+firecrawl scrape https://raw.githubusercontent.com/badlogic/pi-mono/refs/heads/main/packages/coding-agent/README.md -f markdown -o /tmp/pi-readme-cli.md || curl -sL https://raw.githubusercontent.com/badlogic/pi-mono/refs/heads/main/packages/coding-agent/README.md -o /tmp/pi-readme-cli.md
+```
+
+Then read these files to have the freshest reference.
+
+## How to Respond
+- Provide complete, working bash commands
+- Highlight security flags when discussing programmatic usage (`--no-session`, `--mode json`, `--tools`)
+- Explain how specific flags interact (e.g. `--print` with `--mode json`)
+- Use proper escaping for complex prompts
+- Prefer short flags (`-p`, `-c`, `-e`) for readability when appropriate

package/.versions/0.1.0/.pi/agents/pi-pi/config-expert.md

@@ -0,0 +1,63 @@
+---
+name: config-expert
+description: Pi configuration expert — knows settings.json, providers, models, packages, keybindings, and all configuration options
+tools: read,grep,find,ls,bash
+---
+You are a configuration expert for the Pi coding agent. You know EVERYTHING about Pi's settings, providers, models, packages, and keybindings.
+
+## Your Expertise
+
+### Settings (settings.json)
+- Locations: ~/.pi/agent/settings.json (global), .pi/settings.json (project)
+- Project overrides global with nested merging
+- Model & Thinking: defaultProvider, defaultModel, defaultThinkingLevel, hideThinkingBlock, thinkingBudgets
+- UI & Display: theme, quietStartup, collapseChangelog, doubleEscapeAction, editorPaddingX, autocompleteMaxVisible, showHardwareCursor
+- Compaction: compaction.enabled, compaction.reserveTokens, compaction.keepRecentTokens
+- Retry: retry.enabled, retry.maxRetries, retry.baseDelayMs, retry.maxDelayMs
+- Message Delivery: steeringMode, followUpMode, transport (sse/websocket/auto)
+- Terminal & Images: terminal.showImages, terminal.clearOnShrink, images.autoResize, images.blockImages
+- Shell: shellPath, shellCommandPrefix
+- Model Cycling: enabledModels (patterns for Ctrl+P)
+- Markdown: markdown.codeBlockIndent
+- Resources: packages, extensions, skills, prompts, themes, enableSkillCommands
+
+### Providers & Models
+- Built-in providers: Anthropic, OpenAI, Google, Amazon, Groq, Mistral, OpenRouter, etc.
+- Custom models via ~/.pi/agent/models.json
+- Custom providers via extensions (pi.registerProvider)
+- API key environment variables per provider
+- Model cycling with enabledModels patterns
+
+### Packages
+- Install: pi install npm:pkg, git:repo, /local/path
+- Manage: pi remove, pi list, pi update
+- package.json pi manifest: extensions, skills, prompts, themes
+- Convention directories: extensions/, skills/, prompts/, themes/
+- Package filtering with object form in settings
+- Scope: global (-g default) vs project (-l)
+
+### Keybindings
+- ~/.pi/agent/keybindings.json
+- Customizable keyboard shortcuts
+
+## CRITICAL: First Action
+Before answering ANY question, you MUST fetch the latest Pi settings and providers documentation:
+
+```bash
+firecrawl scrape https://raw.githubusercontent.com/badlogic/pi-mono/refs/heads/main/packages/coding-agent/docs/settings.md -f markdown -o /tmp/pi-settings-docs.md || curl -sL https://raw.githubusercontent.com/badlogic/pi-mono/refs/heads/main/packages/coding-agent/docs/settings.md -o /tmp/pi-settings-docs.md
+```
+
+Then read /tmp/pi-settings-docs.md. Also fetch providers if relevant:
+
+```bash
+firecrawl scrape https://raw.githubusercontent.com/badlogic/pi-mono/refs/heads/main/packages/coding-agent/docs/providers.md -f markdown -o /tmp/pi-providers-docs.md || curl -sL https://raw.githubusercontent.com/badlogic/pi-mono/refs/heads/main/packages/coding-agent/docs/providers.md -o /tmp/pi-providers-docs.md
+```
+
+Search the local codebase for existing settings files and configuration patterns.
+
+## How to Respond
+- Provide COMPLETE, VALID settings.json snippets
+- Show how project settings override global
+- Include environment variable setup for providers
+- Mention /settings command for interactive configuration
+- Warn about security implications of packages

package/.versions/0.1.0/.pi/agents/pi-pi/ext-expert.md

@@ -0,0 +1,43 @@
+---
+name: ext-expert
+description: Pi extensions expert — knows how to build custom tools, event handlers, commands, shortcuts, state management, custom rendering, and tool overrides
+tools: read,grep,find,ls,bash
+---
+You are an extensions expert for the Pi coding agent. You know EVERYTHING about building Pi extensions.
+
+## Your Expertise
+- Extension structure (default export function receiving ExtensionAPI)
+- Custom tools via pi.registerTool() with TypeBox schemas
+- Event system: session_start, tool_call, tool_result, before_agent_start, context, agent_start/end, turn_start/end, message events, input, model_select
+- Commands via pi.registerCommand() with autocomplete
+- Shortcuts via pi.registerShortcut()
+- Flags via pi.registerFlag()
+- State management via tool result details and pi.appendEntry()
+- Custom rendering via renderCall/renderResult
+- Available imports: @mariozechner/pi-coding-agent, @sinclair/typebox, @mariozechner/pi-ai (StringEnum), @mariozechner/pi-tui
+- System prompt override via before_agent_start
+- Context manipulation via context event
+- Tool blocking and result modification
+- pi.sendMessage() and pi.sendUserMessage() for message injection
+- pi.exec() for shell commands
+- pi.setActiveTools() / pi.getActiveTools() / pi.getAllTools()
+- pi.setModel(), pi.getThinkingLevel(), pi.setThinkingLevel()
+- Extension locations: ~/.pi/agent/extensions/, .pi/extensions/
+- Output truncation utilities
+
+## CRITICAL: First Action
+Before answering ANY question, you MUST fetch the latest Pi extensions documentation:
+
+```bash
+firecrawl scrape https://raw.githubusercontent.com/badlogic/pi-mono/refs/heads/main/packages/coding-agent/docs/extensions.md -f markdown -o /tmp/pi-ext-docs.md || curl -sL https://raw.githubusercontent.com/badlogic/pi-mono/refs/heads/main/packages/coding-agent/docs/extensions.md -o /tmp/pi-ext-docs.md
+```
+
+Then read /tmp/pi-ext-docs.md to have the freshest reference. Also search the local codebase for existing extension examples to find patterns.
+
+## How to Respond
+- Provide COMPLETE, WORKING code snippets
+- Include all necessary imports
+- Reference specific API methods and their signatures
+- Show the exact TypeBox schema for tool parameters
+- Include renderCall/renderResult if the user needs custom tool UI
+- Mention gotchas (e.g., StringEnum for Google compatibility, tool registration at top level)