contribute - SKILL.md Agent Skill

name: contribute description: Contributing to plyr.fm — an audio streaming app built on ATProto. Use when making changes to the plyr.fm codebase, fixing bugs, adding features, or opening pull requests. metadata: author: zzstoatzz repo: https://github.com/zzstoatzz/plyr.fm

how to contribute to plyr.fm

step 1: orient yourself

read these files in the repo — they have everything you need:

CLAUDE.md — project rules, stack, structure, conventions
STATUS.md — active tasks and known issues
backend/.env.example — all environment variables with comments
docs/internal/local-development/setup.md — full local dev walkthrough

check open issues for things to work on.

step 2: fork and set up

gh repo fork zzstoatzz/plyr.fm --clone
cd plyr.fm
uv sync && cd frontend && bun install && cd ..
cp backend/.env.example backend/.env
# edit backend/.env — DATABASE_URL is required, see the file for details

if you need to run the full stack locally, read docs/internal/local-development/setup.md. for frontend-only changes you may not need the backend running at all.

step 3: make your change

branch from main
for bug fixes, add a regression test
run just --list to see available commands (linting, tests, etc.)

step 4: validate

just backend lint       # python: type check + ruff
just frontend check     # svelte: type check
just backend test       # runs tests with isolated docker postgres + redis

step 5: open a PR

open a PR from your fork to zzstoatzz/plyr.fm:main. describe what changed and why.

PRs are the only way changes land — the main branch is protected.