mirror of
https://github.com/Piebald-AI/claude-code-system-prompts.git
synced 2026-05-30 13:45:23 +08:00
112 lines
3.0 KiB
Markdown
112 lines
3.0 KiB
Markdown
<!--
|
|
name: 'Skill: Run web server API example'
|
|
description: Example file for the Run app skill showing how to document a server or API lifecycle with background launch, readiness checks, curl verification, and shutdown
|
|
ccVersion: 2.1.145
|
|
-->
|
|
# Example: Web server / API
|
|
|
|
The distinguishing concern for servers is **lifecycle**: an agent needs to
|
|
start the server in the background, verify it's up, interact with it, then
|
|
cleanly shut it down. A foreground `npm start` that blocks the shell is
|
|
useless to an agent.
|
|
|
|
## Structure to follow
|
|
|
|
A good server run skill has:
|
|
|
|
1. **Prerequisites & setup** — same as any project.
|
|
2. **Run** — the background-launch pattern (below), not a blocking command.
|
|
3. **Verify** — a `curl` or similar that confirms the server is actually up.
|
|
4. **Stop** — how to cleanly terminate the background process.
|
|
|
|
If the background-launch + readiness-poll + smoke-curl sequence is more
|
|
than a couple of lines, put it in a `smoke.sh` inside the skill directory
|
|
and have `SKILL.md` say "run the smoke script." One command, exit code
|
|
tells you if the server is healthy.
|
|
|
|
## Background-launch pattern
|
|
|
|
Don't write:
|
|
|
|
> ```bash
|
|
> npm start
|
|
> ```
|
|
|
|
That blocks. Instead, show how to launch in the background, wait for
|
|
readiness, and find the PID later:
|
|
|
|
> ```bash
|
|
> npm start &> /tmp/server.log &
|
|
> SERVER_PID=$!
|
|
>
|
|
> # Wait for the server to come up (adjust timeout/port as needed)
|
|
> for i in {1..30}; do
|
|
> curl -sf http://localhost:3000/health > /dev/null && break
|
|
> sleep 1
|
|
> done
|
|
> ```
|
|
|
|
Then the verification step:
|
|
|
|
> ```bash
|
|
> curl http://localhost:3000/health
|
|
> # → {"status":"ok"}
|
|
> ```
|
|
|
|
And stopping:
|
|
|
|
> ```bash
|
|
> kill $SERVER_PID
|
|
> # or, if you've lost the PID:
|
|
> pkill -f "node.*server.js"
|
|
> ```
|
|
|
|
## Details worth documenting
|
|
|
|
- **Which port.** Make it explicit and say how to override it (`PORT=4000 npm start`).
|
|
- **What "ready" looks like.** A specific log line or a health endpoint to hit.
|
|
- **Required env vars.** Database URL, API keys, etc. — with a template `.env`
|
|
if the list is long.
|
|
- **Hot reload vs production mode.** If they differ meaningfully, say which
|
|
to use and when.
|
|
- **Dependent services.** If the server needs Redis/Postgres/etc., either
|
|
point at a docker-compose that brings them up, or include the `docker run`
|
|
command directly.
|
|
|
|
## Example snippet
|
|
|
|
Here's what a Run section for a typical Node API might look like:
|
|
|
|
> ## Run
|
|
>
|
|
> Start the dev server in the background:
|
|
>
|
|
> ```bash
|
|
> npm run dev &> /tmp/api.log &
|
|
> ```
|
|
>
|
|
> The server listens on port 3000. Wait for it to be ready, then verify:
|
|
>
|
|
> ```bash
|
|
> for i in {1..20}; do
|
|
> curl -sf http://localhost:3000/health && break
|
|
> sleep 0.5
|
|
> done
|
|
> curl http://localhost:3000/health
|
|
> # → {"status":"ok","version":"1.2.3"}
|
|
> ```
|
|
>
|
|
> Logs are at `/tmp/api.log`. Stop with:
|
|
>
|
|
> ```bash
|
|
> pkill -f "tsx watch src/index.ts"
|
|
> ```
|
|
>
|
|
> ### Environment
|
|
>
|
|
> | Variable | Required | Default | Notes |
|
|
> |---|---|---|---|
|
|
> | `DATABASE_URL` | Yes | — | Postgres connection string |
|
|
> | `PORT` | No | `3000` | |
|
|
> | `LOG_LEVEL` | No | `info` | `debug` / `info` / `warn` / `error` |
|