Agent skill

The Phonebox agent skill is one Markdown file, published at https://phonebox.dev/skills/phonebox/SKILL.md. It is written for agents. It teaches an agent to find out what its user wants, onboard them, and use Phonebox through MCP tools, the CLI or HTTP, with the HTTP request behind every command.

What it containsCopy Anchor Link

• What Phonebox is, and what it fits: apps without an API, services that work only in a mobile app, testing an Android build, and a phone per customer. None is a default, and it also says when not to use Phonebox, for example when an API or a website would do.
• Start with what your user wants: act on a phone now, build an integration the user asked for, or onboard and ask one question.
• Onboarding your user: check what exists (a key, MCP tools, phonebox account), then walk the user through only the missing steps: sign-up, a key and credit.
• How to drive a phone: MCP tools when connected, the CLI in a shell (installed when needed), the SDK only for integration code, and HTTP otherwise; PHONEBOX_API_KEY and PHONEBOX_PHONE.
• The loop: create a phone, look at the screen, tap and type, look again, and park, as one block of commands.
• Reading the screen: the text form, refs and snapshots, and when to take a screenshot instead.
• Targets: coordinates, refs, text, resource IDs and descriptions, the order in which text matches, and what an ambiguous target means.
• Testing an Android build, one use case among several: build the APK, install it with phonebox apps "$PHONEBOX_PHONE" install ./app.apk (with --replace for another signing key or an older version), then look and walk the screens, with a link to the guide.
• Parking and cost: the price, the timers, reservations, and the rule to always park when done.
• Rules: one agent per phone, never repeating an action whose outcome is unknown, never deleting phones, and keeping keys out of prompts.
• When something fails: each common error code, what it means, and what to do next.
• Several customers or tasks: names, metadata, one phone per end user, and keys limited to certain phones.
• HTTP equivalents: the REST request behind every CLI command.

Install it in Claude CodeCopy Anchor Link

To make the skill available in every Claude Code session, install it as a personal skill:

mkdir -p ~/.claude/skills/phonebox
curl -fsSL https://phonebox.dev/skills/phonebox/SKILL.md -o ~/.claude/skills/phonebox/SKILL.md

To give it to everyone who works on one project, save it in the project and commit it:

mkdir -p .claude/skills/phonebox
curl -fsSL https://phonebox.dev/skills/phonebox/SKILL.md -o .claude/skills/phonebox/SKILL.md

Claude Code can then use the skill whenever a task calls for an Android phone. Download it again when you update the CLI, so that the two match.

Other agentsCopy Anchor Link

Any agent that can read a URL can use the skill. The simplest way is the setup prompt below, which tells the agent to read the skill first. For an agent you use often, add a line to the instructions file it reads, such as AGENTS.md, telling it to read https://phonebox.dev/skills/phonebox/SKILL.md before it uses Phonebox.

Agents that prefer tools to terminal commands can use the MCP server instead.

The setup promptCopy Anchor Link

The console's Home page has this prompt with a Copy button, for an account that already exists:

Read https://phonebox.dev/setup.md and connect this machine to my existing Phonebox account. Use my available credit without requiring a purchase. Then read https://phonebox.dev/skills/phonebox/SKILL.md, find out what I want to use phones for, and help me with that. Park the phone when done.

Paste it into your coding agent. Set up with your coding agent walks through what happens next.