pi-pkg #

Commit format #

Use [type/name] Message format for commits:

• [extensions/goal] Add a token budget to goal continuation
• [skills/shell] Add shell skill
• [themes/catppuccin] Tweak accent color

README #

When adding, changing, or removing anything user-facing (extension, skill, prompt, theme), update README.md in the same commit. The root README is an index, not a manual: one bullet per artifact —

- [name](./path) - one clause on what it does.

— and nothing else. Usage, flags, configuration, examples, troubleshooting, and credits belong in the artifact's own docs, never in the root index.

Where those docs live:

• Skills — skills/<name>/README.md for human-facing setup, configuration, invocation, and troubleshooting (every skill gets one, because the root entry links it). SKILL.md stays agent-facing usage only: no setup instructions, no credits.
• Everything else — the source file, whose header comment carries usage and attribution; add an item-local README.md when the artifact needs more prose than a docstring should hold, and point the root entry at it instead.

Every layer a change touches updates in the same commit.

Project-local artifacts #

.pi/ holds artifacts that are deliberately not part of the package — unvetted work in progress, loaded by Pi from this project only (.pi/skills/, .pi/extensions/, .pi/prompts/, .pi/themes/). They get no package.json entry, no root README entry, and no item README requirement until they are promoted into extensions/, skills/, prompts/, or themes/.

Credits #

Every derived or adapted artifact carries one credit sentence, in one fixed format, plus a matching NOTICE entry. The sentence is always:

<Verb> from [<owner>/<project> `<path/in/project>`](<url>) (<license>) — <what we changed>.

• Verb. Copied from — used verbatim. Derived from — substantial original code or prose retained. Inspired by — structure or idea only.
• Label. <owner>/<project> plus the backticked path of the file it came from. Never a description of the source ("mitsuhiko's github skill") in place of the path.
• Link. A blob/permalink to the original file. Docs sites and repo roots are not acceptable substitutes when a file link exists.
• License. The upstream license id, with the copyright line for MIT-style licenses: (MIT, Copyright (c) 2026 Madeleine Ostoja).
• Modification clause. Em-dash, then what we changed; omit the clause entirely when nothing changed. Keep it to the substantive deltas, not a changelog.

Placement — exactly one human-facing home per artifact:

A single-file extension needs no README just to hold a credit — the header comment is the normal home, and it already carries the usage the root index no longer repeats. Grow an item README.md when the artifact needs setup, configuration, or troubleshooting prose; move the credit there at that point and leave a pointer in the header.

In a README.md (## Credits is the last section, the sentence is its whole body):

## Credits

Inspired by [badlogic/pi-skills `brave-search/search.js`](https://github.com/badlogic/pi-skills/blob/main/brave-search/search.js) (MIT, Copyright (c) 2024 Mario Zechner) — same single-file CLI shape, rewritten against the Kagi API with OS-keyring key lookup.

In a file header comment (same sentence, Markdown kept, hard-wrapped with *):

 * Derived from [mitsuhiko/agent-stuff
 * `extensions/goal.ts`](https://github.com/mitsuhiko/agent-stuff/blob/main/extensions/goal.ts)
 * (Apache-2.0) — session-log-backed state instead of an external database.
 */

NOTICE is the legal record and lists every derived file regardless of where the human-facing sentence sits. Its shape is fixed — artifact path, then a <Verb> from <owner>/<project> (<license>): line, then the URL on its own line, then Modified::

extensions/goal.ts
  Derived from mitsuhiko/agent-stuff (Apache-2.0):
  https://github.com/mitsuhiko/agent-stuff/blob/main/extensions/goal.ts
  Modified: session-log-backed state; optional token budget; stricter audits.

Update the credit sentence and its NOTICE entry in the same commit as the artifact they describe.

Pi documentation #

Before customizing or extending Pi itself — extensions, skills, prompt templates, themes, TUI components, keybindings, packages, the SDK — read Pi's docs instead of working from memory or guessing at APIs. Pages are hosted at https://pi.dev/docs/latest/<page> (e.g. .../latest/skills for skill creation) and ship bundled with the installed binary: resolve docs/<page>.md and examples/ under Pi's install directory, found via dirname "$(readlink -f "$(command -v pi)")". Follow a page's cross-references before implementing, and treat upstream docs as authoritative over the conventions here.