mayatnikovandClaude Opus 4.7
fa0bbd8c59
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>
93 lines
3.5 KiB
Markdown
93 lines
3.5 KiB
Markdown
# 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:
|
|
|
|
```markdown
|
|
---
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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](./LICENSE).
|