pi-extensions-and-skills

Personal skills and extensions for pi, distributed as a pi package. Install on any machine with one command; develop on this repo with live edits.

What's included

Skills (15; penpot ships a dependency-free fetch script and its vendored reference under skills/penpot/docs/, and create-issues ships the fetcher that vendors dependency docs into a repo's docs/reference/):

Skill	What it does
bruno-cli	Run Bruno API collections from the CLI (.bru files, test suites, OpenAPI/WSDL imports)
commit-changes	Commit working-tree changes via branch → PR → merge workflow (issue-driven for feature/bug/enhancement, no-issue date-driven for chore/documentation)
commit-docs	Commit existing docs via a no-issue, date-driven branch → PR → squash-merge workflow (always labeled documentation)
create-issues	Convert an implementation plan into standalone, agent-implementable issues (milestones → steps, self-contained bodies with researched doc URLs) and vendor the referenced dependency docs into docs/reference/<slug>/, shipped as a docs PR — see skills/create-issues/SKILL.md
explain	Walk through the current branch's diff in plain English — new functions plus recursive call-site tracing to entry points
forgejo-cli	Interact with a Forgejo instance via the fj CLI
forgejo-plumber	Debug failed Forgejo Actions runs via the forgejo extension — failed-run triage (find → view → jobs → log → root-cause), log-grep strategy, common failure categories, tool cheat-sheet
furnish-repo	Furnish a new repo (structure, config, docs)
github-cli	Interact with GitHub via the gh CLI
init-project	Scaffold a new project
meilisearch	Work with Meilisearch
penpot	Design in Penpot over the RPC API — bootstrap colour/typography assets, import and link the committed component library, compose and commit screens with the penpot extension, and reconstruct a screenshot or mockup as editable shapes (image → design; needs PENPOT_URL/PENPOT_TOKEN). Ships a vendored Penpot reference pinned to Penpot 2.17.2 (skills/penpot/docs/)
review	Review code, PRs, and changes
tdd-implementation	Drive implementation via test-driven development
victorialogs-debugging	Debug issues by searching VictoriaLogs via the victorialogs extension — error-spike triage, known-entity tracing, missing-log investigation, LogsQL cheat-sheet

Extensions (12):

Extension	What it does
rg	Overrides the built-in grep tool with ripgrep (faster, regex-native)
postgres	Postgres client tools (runs via pg, dotenv, pgpass)
mssql	SQL Server query tools (mssql; read-only credentials are the write control, with a minimal guard)
pr-comments	Forgejo PR review tools: detect branch, find PR, list unresolved comments, reply
forgejo	Forgejo REST API tools: issue/PR/label/milestone suites + read-only Actions run/job/log tools (calls the API directly, no shell interpolation)
grillme	Socratic planning/grilling sessions (customized fork of @majorgilles/pi-grill-me, vendored at extensions/grillme/)
learn-repo	Guided repo onboarding with an enforced mastery gate — traces one feature end to end then generalises into architecture, quizzes after every section, code-graded answers that the model cannot skip or reveal, writes .learn-repo/<repo>/PROGRESS.md and CONCEPTS.md
victorialogs	VictoriaLogs log-querying tools (logs_search, logs_hits, logs_facets) against a running VictoriaLogs instance
searxng	Web search via a self-hosted SearXNG metasearch instance (web_search tool); base URL from SEARXNG_URL (defaults to http://localhost:8888)
mongodb	Read-only MongoDB querying tools (mongo_find, mongo_count, mongo_list_collections) against a configured MongoDB instance (via MONGODB_URI in .env; zero tools registered when unconfigured)
vision	Analyze local image files (JPEG, PNG, GIF, WebP) with the DeepSeek deepseek-flash vision model (vision tool; DEEPSEEK_API_KEY/VISION_* config; zero tools registered when unconfigured)
penpot	Penpot design-creation tools over the Penpot RPC API (colour/typography assets, screen composition, component instancing) — currently registers penpot_whoami (verify PENPOT_URL/PENPOT_TOKEN), penpot_list_projects (teams → projects), penpot_get_file (revision, pages and library assets), penpot_list_library (library assets as resolved name → id lookups, with duplicate-name detection), the staged penpot_create_color / penpot_create_typography / penpot_discard token primitives and penpot_add_frame (staged add-obj frame with auto-layout props, returning its shape id), penpot_add_rect / penpot_add_text (staged add-obj rect/text primitives with library-colour and library-typography reference resolution) and penpot_add_image (staged add-obj image primitive that uploads the media object first, after the designated-target guard), penpot_add_svg (imports an SVG — an .svg file path or inline svg markup — as native shapes, linking fills to matching file/library colours and preserving unsupported nodes as svg-raw, which it reports as not rendered by Penpot 2.17), penpot_instance_component (stages a real library-component instance by cloning the main-instance subtree with fresh ids, resolved by name against the file and its linked libraries, with unknown/ambiguous names, nested instances and unlinked libraries refused), penpot_import_library (imports a committed .penpot library artifact into a nominated project as a new file via the multipart streaming import-binfile command), penpot_export_library (exports a file as a .penpot ZIP artifact to disk via the streaming export-binfile command, verifying the ZIP magic before writing), penpot_list_libraries (lists the library files linked to a file — read-only), penpot_link_library / penpot_unlink_library (link and unlink a library file on a consumer file, each verified by re-reading get-file-libraries and behind the designated-target guard), penpot_authorize_target (records a user-named file/project in the session write allow-list), and the write control tools penpot_status (staged state, never writes) / penpot_commit (one update-file per commit behind the designated-target guard — fail-closed when a file's project cannot be resolved — with live revn read + one conflict retry + re-read verification, and dry_run preview)

Prerequisites

• pi installed
• rg binary on PATH for the rg extension (e.g. sudo apt install ripgrep)
• A reachable Postgres instance + credentials (via env / .env) for the postgres extension
• A reachable SQL Server and MSSQL_URL in .env for the mssql extension
• FORGEJO_TOKEN for the forgejo extension (Forgejo → Settings → Applications → Generate New Token)
• The fj CLI installed and authenticated (fj auth login) for the pr-comments extension
• A reachable VictoriaLogs instance for the victorialogs extension (optional — defaults to http://localhost:9428 if unset)
• A reachable SearXNG instance for the searxng extension (optional — defaults to http://localhost:8888 if unset); extensions/searxng/docker-compose.yml runs one locally, and its config/settings.yml is required because a stock SearXNG answers 403 to format=json
• A reachable MongoDB instance for the mongodb extension, configured via MONGODB_URI in the project's .env (the extension registers no tools when unconfigured); prefer a dedicated read-only DB user (read role)
• DEEPSEEK_API_KEY for the vision extension, configured via DEEPSEEK_API_KEY in the project's .env (the extension registers zero tools when unconfigured); keep it out of commits — the .env file is never committed
• PENPOT_URL (instance base URL, without the /api suffix) and PENPOT_TOKEN (personal access token from your Penpot account settings) for the penpot extension, whose vendored reference is pinned to Penpot 2.17.2 in skills/penpot/docs/VERSION; the token needs edit rights on a project to write, and penpot_link_library/penpot_unlink_library additionally need edit rights on the library file itself

Install

On any machine — one command

pi install https://git.excelera.net/david/pi-extensions-and-skills@main

Then /reload (or restart pi). Verify:

pi list                     # shows the package
# /reload, then check /skills lists the 15 skills and extension tools are callable

If the repo is private, use a URL that carries your Forgejo credentials, or the SSH form (pi install git:git@git.excelera.net:david/pi-extensions-and-skills@main). If public, the HTTPS URL above works as-is.

pi clones the package to ~/.pi/agent/git/git.excelera.net/david/pi-extensions-and-skills, runs npm install (installing the hoisted pg/dotenv/pgpass/adm-zip/mongodb/mssql/image-size deps), and loads the skills and extensions declared in the pi manifest.

From a checkout of this repo — one command

From any git checkout (dev machine or fresh clone), one command updates and registers everything:

git clone https://git.excelera.net/david/pi-extensions-and-skills
cd pi-extensions-and-skills
npm run install:local

install:local is an explicit script — it never runs on npm install, only when you run it. It does, in order:

1. Preflight checks (fail fast with an actionable message): pi CLI present, not inside pi's managed clone, a git checkout of this repo, on main, clean working tree. A missing rg binary only prints a warning and skips the rg extension; a missing fj CLI only prints a warning and skips pr-comments/forgejo-cli, while an installed-but-unauthenticated fj only prints a warning and still installs them — install continues either way. A missing FORGEJO_TOKEN only prints a warning — install continues (it's a per-machine env var, not a hard requirement).
2. git pull --ff-only — only runs on clean main.
3. npm install — installs the runtime deps (pg, dotenv, pgpass, adm-zip, mongodb, mssql, image-size) and the host-provided peers (@earendil-works/pi-coding-agent, @earendil-works/pi-tui, typebox). The peers are declared, not bundled: pi supplies its own copy at load time, so extensions must not ship a second one.
4. Global pi registration with URL-entry dedupe — any existing settings entry (global, or this checkout's project scope at .pi/settings.json) that references this repo's URL (https://…, git:…, ssh://…) is removed, then the repo is registered as a local-path package. One clean identity, no duplicate skills/extensions.
5. Reminder — run /reload in pi to pick up the changes.

Examples of the preflight messages:

Problem	Message
pi not installed	install pi first (see the pi README)
running inside pi's managed clone	run from your own checkout
not a checkout of this repo	git clone … first
not on main	git checkout main
dirty working tree	git commit / git stash
git pull fails	check your network/credentials
npm install fails	the npm error output
rg missing	warning only — skips the rg extension; install sudo apt install ripgrep and re-run to include it (install continues)
FORGEJO_TOKEN missing	warning only — generate in Forgejo → Settings → Applications (install continues)
fj missing/not authenticated	warning only — missing fj skips pr-comments and forgejo-cli, unauthenticated fj still installs them; run fj auth login (install continues)

Note: pi does not run npm install for local-path packages; install:local does it for you (including after git pull brings in new deps).

Updating

• Dev machine / any checkout: npm run install:local — pulls, reinstalls deps, re-registers with dedupe, then /reload.
• Installed machines: re-run the install command — pi install https://git.excelera.net/david/pi-extensions-and-skills@main. pi pins refs at install time and pi update does not move pins to newer refs, so re-installing is the update path.

Uninstalling

pi remove https://git.excelera.net/david/pi-extensions-and-skills

For a local-path (checkout) setup, remove the local-path entry instead: pi remove /absolute/path/to/this/repo. Then /reload.

Extension notes

• rg — registers a grep tool (same name as the built-in, overrides it) backed by ripgrep; needs the rg binary.
• postgres — reads connection config from .env via dotenv; see extensions/postgres/README.md.
• mssql — SQL Server query tools; use a read-only login (the real write control); reads MSSQL_URL from .env; see extensions/mssql/README.md.
• pr-comments — tools for listing unresolved review comments and replying; see extensions/pr-comments/README.md.
• forgejo — Forgejo issue/PR/label/milestone + Actions run/job/log tools; token from FORGEJO_TOKEN; see extensions/forgejo/README.md.
• grillme — Socratic planning/grilling sessions; a customized fork of @majorgilles/pi-grill-me vendored at extensions/grillme/; see extensions/grillme/README.md.
• victorialogs — VictoriaLogs log-querying tools (logs_search, logs_hits, logs_facets); base URL from VICTORIALOGS_URL (defaults to http://localhost:9428); see extensions/victorialogs/README.md.
• searxng — web search over a self-hosted SearXNG metasearch instance (web_search); base URL from SEARXNG_URL (defaults to http://localhost:8888); results cap at 50 and details.unresponsiveEngines explains a thin result set; see extensions/searxng/README.md.
• mongodb — read-only MongoDB querying tools (mongo_find, mongo_count, mongo_list_collections); URI from MONGODB_URI in the project's .env only (case-insensitive + nested config__MONGODB_URI lookup; a process-env MONGODB_URI is not read; zero tools when unconfigured); see extensions/mongodb/README.md.
• vision — analyze local image files (JPEG, PNG, GIF, WebP) with the DeepSeek deepseek-flash vision model (vision tool); key from DEEPSEEK_API_KEY, options from VISION_MODEL/VISION_BASE_URL/VISION_MAX_TOKENS/VISION_TIMEOUT/VISION_THINKING (zero tools when unconfigured); see extensions/vision/README.md.
• penpot — Penpot design-creation tools (penpot_whoami … penpot_commit); needs PENPOT_URL/PENPOT_TOKEN, and a token with edit rights for writes; the vendored reference is pinned in skills/penpot/docs/VERSION (2.17.2); see extensions/penpot/README.md.

Caveats

• Refs are pinned at install; updates require re-running the install command (not pi update).
• Local-path packages don't get npm install run by pi — use npm run install:local (or install deps manually in the repo).

Repository layout

skills/            # 15 skills, each a dir with SKILL.md (frontmatter name = skill name); penpot/ ships scripts/fetch-penpot-docs.mjs + the generated docs/ reference, and create-issues/ ships scripts/fetch-reference-docs.mjs (vendors dependency docs into a repo's docs/reference/)
extensions/
  rg/              # ripgrep grep override (single index.ts)
  postgres/        # postgres client tools (needs pg, dotenv, pgpass)
  mssql/           # SQL Server query tools (needs mssql; minimal guard, read-only credentials; node --test)
  pr-comments/     # Forgejo PR comment tools (typebox from the host)
  forgejo/         # Forgejo REST API tools (typebox from the host; needs adm-zip)
  grillme/         # Socratic planning/grilling sessions (customized fork of @majorgilles/pi-grill-me)
  mongodb/         # read-only MongoDB querying tools (mongo_find, mongo_count, mongo_list_collections; needs mongodb, bson, dotenv; bun test)
  vision/          # DeepSeek vision analysis tool (vision; needs dotenv, image-size; typebox from the host; node --test)
  penpot/          # Penpot design-creation tools over the RPC API (penpot_whoami, penpot_list_projects, penpot_get_file, penpot_list_library, penpot_list_libraries, staged penpot_create_color/penpot_create_typography/penpot_discard/penpot_add_frame/penpot_add_rect/penpot_add_text/penpot_add_image/penpot_add_svg/penpot_instance_component, penpot_import_library, penpot_export_library, penpot_link_library/penpot_unlink_library, penpot_authorize_target, penpot_status/penpot_commit; needs PENPOT_URL/PENPOT_TOKEN)
  victorialogs/    # VictoriaLogs log-querying tools (typebox from the host; bun test)
  searxng/         # SearXNG web-search tool (web_search; typebox from the host; bun test; docker-compose.yml + config/settings.yml for a local instance)
scripts/
  local-install.mjs    # npm run install:local implementation (preflight → pull → install → register)
  local-install.test.mjs  # unit tests for local-install.mjs (npm test)
package.json       # pi package manifest (extensions + skills globs, hoisted deps)