mirror of
https://github.com/Piebald-AI/claude-code-system-prompts.git
synced 2026-05-30 05:35:24 +08:00
148 lines
4.2 KiB
Markdown
148 lines
4.2 KiB
Markdown
<!--
|
|
name: 'Skill: Run skill template'
|
|
description: Template file for the Run skill generator showing the frontmatter and section structure for a project-specific run skill
|
|
ccVersion: 2.1.145
|
|
-->
|
|
---
|
|
name: run-<unit-name>
|
|
description: Build, run, and drive <unit-name>. Use when asked to start <unit-name>, run its tests, build it, take a screenshot of its UI, or interact with the running app.
|
|
---
|
|
|
|
<One-sentence description: what this is and how an agent drives it.
|
|
Name the handle here — "drive it via
|
|
`.claude/skills/run-<unit-name>/driver.mjs` under xvfb" for a desktop
|
|
app, or "start the dev server then drive it via `chromium-cli`" for a
|
|
web app — so an agent knows where to look first.>
|
|
|
|
<If the unit isn't at repo root:>
|
|
All paths below are relative to `<unit-dir>/`.
|
|
|
|
## Prerequisites
|
|
|
|
<System-level requirements. The exact `apt-get install` line you ran —
|
|
not a generic list, the one that actually worked. Target Ubuntu.>
|
|
|
|
```bash
|
|
sudo apt-get update
|
|
sudo apt-get install -y <packages-you-actually-installed>
|
|
```
|
|
|
|
<Runtime versions if they matter:>
|
|
|
|
```bash
|
|
# Example: Node 20 via nvm, Python 3.12 via uv, etc.
|
|
```
|
|
|
|
## Setup
|
|
|
|
<One-time setup after clone: install deps, configure, apply any
|
|
patches (feature-gate overrides, config stubs) with the exact command.>
|
|
|
|
```bash
|
|
<commands>
|
|
```
|
|
|
|
<Env vars — required vs optional, with sensible defaults:>
|
|
|
|
```bash
|
|
export FOO_API_KEY=... # required — get from <where>
|
|
export BAR_MODE=dev # optional — default is prod
|
|
```
|
|
|
|
## Build
|
|
|
|
<Skip if no separate build step. Otherwise the exact command:>
|
|
|
|
```bash
|
|
<command>
|
|
```
|
|
|
|
## Run (agent path)
|
|
|
|
<This is the section a future agent actually uses. If you built a
|
|
driver/REPL/smoke script, this documents how to launch it and what it
|
|
does. If the app is simple enough that `curl` or a one-liner suffices,
|
|
that one-liner goes here.>
|
|
|
|
```bash
|
|
<launch-the-driver-or-smoke-script>
|
|
```
|
|
|
|
<For REPL-style drivers, show the tmux wrapping. Poll for a ready marker
|
|
between send-keys and capture-pane — faster than a fixed sleep and fails
|
|
loudly instead of capturing a half-rendered screen:>
|
|
|
|
```bash
|
|
tmux new-session -d -s app -x 200 -y 50
|
|
tmux send-keys -t app '<launch command>' Enter
|
|
timeout 30 bash -c 'until tmux capture-pane -t app -p | grep -q "<ready-marker>"; do sleep 0.2; done'
|
|
tmux send-keys -t app '<first driver command>' Enter
|
|
tmux capture-pane -t app -p
|
|
```
|
|
|
|
<Where artifacts land (screenshots, logs) — absolute paths:>
|
|
|
|
Screenshots → `/tmp/shots/`. Logs → `/tmp/<app>.log`.
|
|
|
|
<If the driver has commands, a table:>
|
|
|
|
| command | what it does |
|
|
|---|---|
|
|
| `<cmd>` | <description> |
|
|
|
|
## Run (human path)
|
|
|
|
<If meaningfully different from the agent path. Brief — agents won't
|
|
use this, humans can figure it out.>
|
|
|
|
```bash
|
|
<command> # → <what happens>. <how to stop>.
|
|
```
|
|
|
|
## Test
|
|
|
|
```bash
|
|
<command>
|
|
```
|
|
|
|
<Expected result — "N suites pass", or specific known-flaky tests.>
|
|
|
|
---
|
|
|
|
<Optional sections below — include only if relevant and only with
|
|
content you actually hit, not generic advice.>
|
|
|
|
## Gotchas
|
|
|
|
<Non-obvious traps. The things that look like they should work but
|
|
don't, with the workaround. If this section is generic, delete it.>
|
|
|
|
- **<specific thing>** — <why it breaks> → <what to do instead>
|
|
|
|
## Troubleshooting
|
|
|
|
<Symptom → fix. Only errors you actually encountered.>
|
|
|
|
- **<exact error message or symptom>**: <cause>. <fix>.
|
|
|
|
<---
|
|
|
|
NOTE ON THE FRONTMATTER ABOVE:
|
|
- Replace <unit-name> in both `name:` and `description:`. The `name:`
|
|
becomes the slash command (/run-<unit-name>) and must match the
|
|
directory name.
|
|
- The `description:` is what Claude scans to decide whether to load this
|
|
skill automatically. Keep the verbs — "start," "run," "build," "test,"
|
|
"screenshot" — they're what an asking agent will actually type.
|
|
|
|
NOTE ON THE DRIVER:
|
|
- If you wrote a driver script, it lives in this same directory (next
|
|
to this file) by default. Reference it from the Run section.
|
|
- For a web app there's usually no driver file — the `chromium-cli`
|
|
heredoc in the Run section is the harness.
|
|
- If the driver grows into something the project's test suite wants —
|
|
shared launch helpers, a real e2e harness — move it to scripts/ or
|
|
e2e/ in the unit, and update the paths here. The skill stays put.
|
|
|
|
Delete everything from `---` above onwards before committing. --->
|