| name | surface-runner |
| description | Use when a user describes a Surface UI audit, capture, explain, backlog, validate, gate, status, next-step, or trace intent in natural language and needs it mapped to the correct surface CLI or MCP command with confirmation before action. |
Surface Runner
Map conversational requests onto the public Surface interfaces. The runner skill is a thin adapter over CLI and MCP; it is not a third protocol.
Workflow
- Identify the requested action, target, and identifiers from the user request.
- Prefer MCP tools when the current agent environment exposes them. Use the POSIX CLI as the universal fallback.
- Before executing, confirm the mapped action unless the user explicitly asked you to run it.
- If a command needs a missing target or identifier, ask one concise clarifying question.
For deterministic mapping checks, run:
node .agents/skills/surface-runner/scripts/map_intent.mjs "<natural language request>"
Mapping
| User intent | CLI command | MCP tool |
|---|
| initialize or set up Surface | surface init --json | surface_run |
| status or progress | surface status --json | surface_status |
| run a closed-loop review | surface run --<target-kind> <target> --json | surface_run |
| next action or next task | surface next --json | surface_next |
| capture a page/component/DOM/screenshot | surface capture --<target-kind> <target> --json | surface_capture |
| audit or review a page/component/DOM/screenshot | surface audit --<target-kind> <target> --json | surface_audit |
| explain a finding | surface explain <finding-id> --json | surface_explain |
| show backlog or tracked findings | surface backlog --json | surface_backlog |
| validate a run | surface validate --run <run-id> --json | surface_validate |
| enforce the release gate or CI check | surface gate --ci --json | surface_gate |
| trace a finding or decision | surface trace <id> --json | surface_trace |
Target Rules
- URLs beginning with
http://localhost, https://localhost, http://127.0.0.1, or https://127.0.0.1 use --localhost.
- Other
http:// or https:// URLs use --url.
- Requests that say
DOM or include HTML use --dom.
- Requests naming a route use
--route.
- Requests naming a component use
--component.
- Requests naming an image or screenshot file use
--screenshot.
Confirmation Shape
Confirm with the mapped intent, target, and exact command, for example:
Mapped intent to surface audit for http://localhost:3000. Confirm before running: surface audit --localhost http://localhost:3000 --json
Platform Notes
- Claude Code and Codex: use this skill directly; call MCP tools when exposed, otherwise run the CLI.
- Gemini or other agents: use the same mapping table as a prompt/command template and run the CLI when MCP is unavailable.
- CI and non-interactive environments: prefer
--json and preserve exit codes 0 success, 1 runtime failure, and 2 usage error.
