---
name: microservices-sh
description: Help users build, inspect, customize, and deploy applications created with microservices.sh. Use when working in a generated microservices.sh app, choosing templates or modules, reading module contracts, planning module additions or upgrades, changing config/hooks/overlays, running local checks, or handling approval-gated secrets, migrations, email, payment, webhook, Cloudflare, preview, or production deployment workflows.
---

# microservices.sh

## Overview

Use this skill to work on user-owned applications generated by microservices.sh. The app source is inspectable and owned by the user; prefer documented module contracts, lockfiles, config, hooks, and plans before editing module internals.

## First Read

When inside a microservices.sh app, read these files before changing behavior:

- `README.agent.md` for project-specific agent rules.
- `docs/llms.txt` for compact project and module guidance.
- `microservices.template.json` for template identity, runtime, modules, slots, and deployment model.
- `microservices.config.json` for user-editable app and module settings.
- `microservices.lock.json` for pinned template/module versions and upgrade context.
- `docs/api-boundary.md` when changing routes, adapters, or server boundaries.
- `modules/<module-id>/README.agent.md`, `llms.txt`, `module.json`, and `openapi.json` before changing a module.

## User Workflows

### Create an app

Start from a published template when the user wants a new app. Example:

```bash
pnpm create microservices-app@latest studio-booking --template booking-sveltekit
cd studio-booking
pnpm install
pnpm microservices local setup
pnpm dev
```

Use the user's package manager when obvious. Do not require a microservices.sh account or Cloudflare account for local generation and local development unless a command actually crosses into managed services.

### Inspect the app

Use read-only commands before changing source:

```bash
pnpm microservices modules list --json
pnpm microservices docs <module-id>
pnpm microservices check --json
pnpm microservices secrets status --json
pnpm microservices updates --json
```

If a command is unavailable in the generated app, inspect the files listed in "First Read" and explain the limitation instead of inventing behavior.

### Customize behavior

Prefer the safest customization path that satisfies the request:

1. Config: edit `microservices.config.json` or documented module config.
2. Hooks: edit documented hook files or hook exports.
3. Overlay: add routes, components, adapters, or schema overlays around the module.
4. Fork: edit module internals only when the user accepts manual upgrade burden.

Keep app route handlers thin. Put domain logic in modules or documented use-case files, and keep provider details behind adapters/ports.

### Add or upgrade modules

Plan before mutating source or resources:

```bash
pnpm microservices add <module-id> --plan --json
pnpm microservices upgrade <module-id> --plan --json
```

Read the plan for version changes, route changes, bindings, resources, permissions, secrets, hooks, events, migrations, and likely files touched. Ask for approval before applying a plan that adds provider side effects, secrets, migrations, or managed resources.

### Run locally

Use local setup and smoke checks after source changes:

```bash
pnpm microservices local setup
pnpm dev
pnpm microservices local smoke
pnpm microservices check --json
```

Run the smoke command in a second terminal after the dev server is ready. If the app uses a different port, pass the documented `--url`.

### Deploy

Managed deploys must be plan-first and approval-gated:

```bash
pnpm microservices auth status
pnpm microservices deploy doctor
pnpm microservices deploy preview --plan
pnpm microservices deploy preview --confirm deploy
pnpm microservices deploy provision <deployment-id> --plan
pnpm microservices deploy provision <deployment-id> --confirm provision
pnpm microservices deploy upload-plan <deployment-id>
pnpm microservices deploy status <deployment-id>
pnpm microservices preview smoke --url <preview-url>
```

Never run confirm commands, apply remote migrations, provision Cloudflare resources, upload Worker artifacts, activate domains, or deploy production without explicit user approval.

## Approval Gates

Ask for explicit approval before actions that touch:

- Secrets or secret values.
- Auth, tokens, signing keys, scopes, sessions, or permission boundaries.
- PII, customer data, booking data, audit logs, payments, email, webhooks, or external providers.
- D1/KV/R2/Queue resources, migrations, production data, or remote Cloudflare resources.
- Preview deploy, production deploy, provisioning, uploads, custom domains, activation, or rollbacks.
- Billing-impacting or destructive behavior.

Never ask the user to paste secret values into chat. It is acceptable to discuss secret names, scopes, status, and where the user should configure them.

## Finish Checklist

Before responding, report:

- What changed and which module/template/app surface it affected.
- Which docs, manifests, or lockfiles were used.
- Which checks ran and their result.
- Any approval-gated work that was planned but not executed.
- Any manual next step the user must perform outside the agent.