contributing
Use when contributing to the Butterbase codebase, adding new MCP tools, creating API routes, writing migrations, or understanding the monorepo architecture
Profile →npx skills add butterbase-ai/butterbase-skills --skill contributing --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
## 1. Overview Contributor guide for the Butterbase monorepo. Covers architecture, how to add MCP tools, API routes, database migrations, and coding conventions. --- ## 2. Monorepo Map | Directory | Package | Purpose | |-----------|---------|---------| | `packages/cli` | `@butterbase/cli` (v0.1.3) | Published CLI tool (Commander.js). Commands: init, apps, schema, functions, storage, deploy, data, env, keys, realtime, status, open | | `packages/sdk` | `@butterbase/sdk` (v1.2.1) | Published TypeScript SDK. Modules: auth, storage, functions, AI, billing, realtime, admin | | `packages/shared` | `@butterbase/shared` | Internal shared types, constants, schema DSL, error types | | `packages/plugin` | `@butterbase/plugin` | Claude Code plugin (this package — skills for AI agents) | | `services/control-api` | `@butterbase/control-api` | Fastify API server — the brain. Routes, plugins, services. Port 4000 | | `services/mcp-server` | `@butterbase/mcp-server` | MCP server with ~28 tools (consolidated `manage_*` action-based tools + a few standalone ones like `init_app`, `deploy_function`, `select_rows`). Runs via stdio or HTTP (served by control-api at `/mcp`) | | `services/deno-runtime` | — |
- 1. Overview
- 2. Monorepo Map
- 3. Adding a New MCP Tool (4 Steps)
- Step 1: Create tool file at services/mcp-server/src/tools/my-new-tool.ts
- Step 2: Register in services/mcp-server/src/create-server.ts
- Step 3: Create the backing API route in services/control-api/src/routes/
- 4. Adding a Database Migration
- 5. Coding Conventions
- 6. Running Locally
- 7. Testing
docker-compose -f docker-compose.local.yml up
What does the contributing skill do?
Use when contributing to the Butterbase codebase, adding new MCP tools, creating API routes, writing migrations, or understanding the monorepo architecture
How do I install it?
Run `npx skills add butterbase-ai/butterbase-skills --skill contributing --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From butterbase-ai/butterbase-skills, a repository with 532 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.