playbooks

home / skills / petekp / agent-skills / dev-server

dev-server skill

/skills/dev-server

This skill starts development servers with intelligent port management, auto-open, and conflict resolution across projects.

This is most likely a fork of the dev-server skill from petekp
npx playbooks add skill petekp/agent-skills --skill dev-server

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
2.4 KB
---
name: dev-server
description: Start development servers with intelligent port management. Use when asked to "start the dev server", "run dev", "start development", "launch the server", "spin up the app", "get this running", "boot the frontend", or any request to run a local development server. Handles port conflicts, detects project type, cleans up stale processes, and opens the browser automatically.
license: MIT
metadata:
  author: petekp
  version: "0.1.0"
---

# Dev Server

## Workflow

1. **Check ports** - Run `scripts/check_ports.sh` to scan common dev ports
2. **Resolve conflicts**:
   - **Same project**: Use `--kill-if-same` to kill without asking
   - **Different project**: Ask user before killing or use alternate port
3. **Detect environment** - Check for docker-compose.yml, monorepo structure, or package.json
4. **Start server** - Use detected package manager with `--open` flag; add `--port <n>` if needed

## Port Script

```bash
scripts/check_ports.sh                   # Scan ports, show which project each belongs to
scripts/check_ports.sh 3000              # Check specific port with project info
scripts/check_ports.sh --find 3000       # Find first available port
scripts/check_ports.sh --kill-if-same 3000   # Kill only if same project (safe)
scripts/check_ports.sh --kill 3000       # Force kill (ask user first if different project)
```

The script detects project ownership by comparing the process's working directory to the current directory. "Same project" means the process was started from this directory or a parent/child of it.

## Environment Detection

**Docker projects**: If `docker-compose.yml` exists with a web/app service, suggest `docker compose up` instead.

**Monorepos**: Check if current directory has package.json with `dev` script. If not, look for:
- `apps/web/package.json` or `packages/app/package.json` (Turborepo/Nx pattern)
- Root package.json with workspace `dev` script that delegates

**Package manager**: Detect from lockfile (bun.lockb → bun, pnpm-lock.yaml → pnpm, yarn.lock → yarn, otherwise npm).

## Framework Notes

Most frameworks support `--open` and `--port` flags. Exceptions:

| Framework | Default Port | Notes |
|-----------|--------------|-------|
| Create React App | 3000 | Uses `PORT=3001` env var instead of `--port` |
| Gatsby | 8000 | Uses `-p` instead of `--port` |
| Remix | 3000 | `--port` works in dev mode |

When `--open` doesn't work, fall back to `open http://localhost:PORT` after server starts.

Overview

This skill starts local development servers with smart port management and environment detection. It handles port conflicts, cleans up stale processes, detects project type (including monorepos and Docker), and opens the browser automatically when possible. Use it to reliably boot frontend or full-stack dev servers without manual port juggling.

How this skill works

The skill scans common development ports and inspects running processes to determine project ownership. It resolves conflicts by choosing an alternate port or killing a conflicting process (with options to force or only kill processes from the same project). It detects environment clues—docker-compose files, monorepo layouts, package.json scripts, and lockfiles—to pick the right start command and package manager. Finally, it launches the server with appropriate flags (open/port) or falls back to opening the browser URL.

When to use it

  • When you ask to start or run a local dev server (e.g., "start the dev server", "run dev").
  • When a common dev port is already in use and you want automated conflict resolution.
  • When working in monorepos or projects with delegated dev scripts.
  • When you prefer automatic environment detection (Docker, package manager, framework).
  • When you want the browser opened automatically after the server starts.

Best practices

  • Prefer --kill-if-same for safe cleanup of stale processes started from the same project.
  • Check for docker-compose.yml first and use docker compose up for containerized web services.
  • Ensure package.json has a dev script at the correct workspace path in monorepos.
  • Rely on lockfile detection to choose the correct package manager (bun/pnpm/yarn/npm).
  • If framework flags differ, use documented alternatives (e.g., Gatsby -p or CRA PORT env var).

Example use cases

  • Boot a Create React App project and automatically set PORT via env when 3000 is busy.
  • Start a Gatsby site with -p when the default port conflicts with another process.
  • Spin up a workspace app inside a monorepo by locating apps/web or packages/app dev scripts.
  • Detect docker-compose web service and suggest docker compose up instead of npm start.
  • Find an available port with --find and open the browser to the new localhost URL.

FAQ

How does it decide whether to kill a conflicting process?

It compares process working directories to the current project. Use --kill-if-same to only kill processes from the same project, or --kill to force (with confirmation for different projects).

What if the framework doesn't support --open or --port?

The skill uses framework-specific flags when needed (e.g., Gatsby -p, CRA uses PORT env). If --open isn't supported it will open the browser URL after the server starts.