Files

T

mayatnikovandClaude Opus 4.7 fa0bbd8c59 docs: artifact-location rule + CONTRIBUTING for community growth

The whole point of this project is that the agent's growth is shareable.
If skills and extensions silently land in ~/.pi/ on the maintainer's
laptop, every clone starts from zero and the repo becomes a fancy
README. Fix that with an explicit hard rule and a contributor guide.

- AGENTS.md: new "Artifact location — hard rule" subsection spelling out
  that skills/extensions/prompts/state/.pi-settings ALL live in this repo,
  never in ~/.pi/. Pi's own built-in skills (skill-creator, etc.) stay
  user-global; the agent may use them, but their *output* must land here.
- README: new "Everything in the repo" subsection covering the same rule
  in user-facing language, plus a pointer to CONTRIBUTING.md.
- CONTRIBUTING.md (new): skill/extension formats, server-agnostic and
  no-secrets requirements, smoke-test recipe, PR checklist.
- .gitignore: switch from blanket `.pi/` ignore to `.pi/*` + explicit
  un-ignore of `.pi/settings.json`, so project Pi config is reproducible.
- "Don't push without operator confirmation" → "without human
  confirmation via the repo" — consistent with the new control model.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-25 10:23:20 +03:00

3.5 KiB

Raw Permalink Blame History

Contributing

This repo grows by accretion — skills, extensions, and prompts written by Pi agents (or humans) playing on real Minecraft servers. PRs welcome.

What you can contribute

Kind	Where	When
Skill	`skills/<name>.md`	You taught the agent a useful procedure (login flow, recovery routine, farming loop, etc.) and want others to skip the discovery cost.
Extension	`extensions/<name>.{ts,js}`	The skill needs real code — a new Pi tool, a Mineflayer plugin wrapper, an event subscription.
Prompt template	`prompts/<name>.md`	A reusable kickoff or tick prompt that works across servers.
Docs	`README.md`, `docs/*.md`, `AGENTS.md`	Clarifications, new safety rules, architecture notes.

If you change AGENTS.md, treat it as load-bearing — every agent that clones the repo starts from it. Discuss in a PR first.

Skill format

A skill is a single Markdown file with YAML frontmatter:

---
name: <short-kebab-case-slug>
description: <one-sentence summary; Pi uses this to decide whether to load the skill>
when_to_use: <one-sentence trigger; when in a session should the agent reach for this?>
---

# <Skill title>

## Steps

1. ...
2. ...

## Notes

- Edge cases, gotchas, known failure modes.

Keep skills short (under ~150 lines). If it gets longer, split into multiple skills that reference each other, or promote part of it to an extension.

Extension format

Extensions are TypeScript (preferred) or JavaScript modules. See pi.dev/docs/latest for the current extension API. Project-local install:

pi install -l ./extensions/your-extension.ts

The -l flag writes to ./.pi/settings.json (committed) so a fresh clone gets the same toolset.

Hard rules

Server-agnostic. No play.xmatic.team, no specific nicknames, no AuthMe password in any committed file. Everything that varies per server lives in .env.
No secrets in git. If you have to think about whether something is a secret, it is. Run git diff --staged before every commit.
No global writes. Skills, extensions, and Pi settings all live under this repo's tree, not under ~/.pi/. See AGENTS.md → Artifact location.
Don't loosen safety. The hard rules in AGENTS.md (no OP, no griefing, no chat-as-control, rate limits) are non-negotiable. PRs that weaken them get closed.

Testing a skill / extension

Quick smoke test before opening a PR:

# 1. Fresh clone in a temp dir
git clone git@github.com:xmatic-squad/pepa-pi-bot.git /tmp/pepa-test
cd /tmp/pepa-test

# 2. Minimal config — point at a throwaway local MC server if you have one
cp .env.example .env
$EDITOR .env

# 3. Install deps
npm install

# 4. Run Pi and ask it to dry-run your skill
pi
# > Please list the loaded skills. Then describe what skills/your-new-skill.md
# > would do, step-by-step, without actually executing it.

If Pi can't even find your skill, the frontmatter is wrong — check name: is a valid slug and the file is under ./skills/.

PR checklist

File lives in the correct directory (skills/, extensions/, prompts/, docs/).
Frontmatter is valid YAML; name matches the filename.
No hard-coded server hostnames, nicknames, passwords, or API keys.
README.md's Status section updated if this is a user-facing milestone.
Commit message is descriptive (feat(skill): add respawn-and-return for survival servers).

License

By contributing you agree that your work is released under the project's MIT License.

3.5 KiB Raw Permalink Blame History