# Register as an agent skill

> phone-harness skill output, Claude Code and Codex skill install paths, trigger text, and re-sync after pulls so the agent auto-reaches for phone control.

- Repository: ShawnPana/phone-harness
- GitHub: https://github.com/ShawnPana/phone-harness
- Human docs: https://grok-wiki.com/public/docs/shawnpana-phone-harness-bf80173a2a2e
- Complete Markdown: https://grok-wiki.com/public/docs/shawnpana-phone-harness-bf80173a2a2e/llms-full.txt

## Source Files

- `install.md`
- `SKILL.md`
- `src/phone_harness/run.py`
- `README.md`
- `pyproject.toml`

---

---
title: "Register as an agent skill"
description: "phone-harness skill output, Claude Code and Codex skill install paths, trigger text, and re-sync after pulls so the agent auto-reaches for phone control."
---

`phone-harness skill` is a CLI subcommand that prints the repository root `SKILL.md` to stdout. Install that body under a skill directory named `phone-harness` so Claude Code or Codex can match the skill description and invoke `phone-harness` for real iPhone control.

## What gets registered

| Field | Value |
| --- | --- |
| Skill name | `phone-harness` |
| Body source | repo-root `SKILL.md` |
| Emit command | `phone-harness skill` |
| Trigger / description | `Control the user's iPhone through the Mac's iPhone Mirroring window: open apps, tap, type, swipe, read the screen.` |

The skill file frontmatter is:

```yaml
---
name: phone-harness
description: "Control the user's iPhone through the Mac's iPhone Mirroring window: open apps, tap, type, swipe, read the screen."
---
```

Agents match on that description text. The body is the day-to-day product surface: when not to use the phone, stdin Python usage with pre-imported helpers, screen workflow (OCR → act → verify), consent rules, connection gating, and gotchas.

## CLI surface

```text
phone-harness skill       print the phone-harness skill text
```

Behavior:

1. Resolve the package file `src/phone_harness/run.py`.
2. Walk three parents to the checkout root.
3. Read `{repo_root}/SKILL.md` as UTF-8.
4. Print the full file to stdout with no trailing extra newline (`end=""`; the file already ends with `\n`).

No flags, no args, no write path — registration is always a shell redirect into a skill directory.

```text
  ~/.phone-harness/          (canonical editable checkout)
  ├── SKILL.md               ← source of truth for skill body
  ├── install.md
  ├── agent-workspace/
  └── src/phone_harness/
      └── run.py             ← `phone-harness skill` reads ../../../SKILL.md
```

Because install is editable (`pip install -e .` at `~/.phone-harness`), the installed entry point still resolves `SKILL.md` from that checkout root.

## Prerequisites

Before registration:

1. Checkout at the canonical home: `~/.phone-harness` (or re-run `pip install -e .` if relocated).
2. `phone-harness` on `PATH` via editable install.
3. Day-to-day phone work still needs permissions and mirroring; skill registration alone does not grant Accessibility or Screen Recording.

<Note>
Registration only installs agent discovery text. Runtime control still requires a working `phone-harness` command, iPhone Mirroring, and the permission ladder verified by `phone-harness --doctor`.
</Note>

## Install paths

Register under the agent’s skill root, in a folder named `phone-harness`, as `SKILL.md`.

<Tabs>
  <Tab title="Claude Code">
    <Steps>
      <Step title="Create the skill directory">

```bash
mkdir -p ~/.claude/skills/phone-harness
```

      </Step>
      <Step title="Write the skill body">

```bash
phone-harness skill > ~/.claude/skills/phone-harness/SKILL.md
```

      </Step>
      <Step title="Verify">

```bash
head -5 ~/.claude/skills/phone-harness/SKILL.md
# ---
# name: phone-harness
# description: "Control the user's iPhone through the Mac's iPhone Mirroring window: open apps, tap, type, swipe, read the screen."
# ---
```

      </Step>
    </Steps>
  </Tab>
  <Tab title="Codex">
    <Steps>
      <Step title="Create the skill directory">

```bash
mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills/phone-harness"
```

      </Step>
      <Step title="Write the skill body">

```bash
phone-harness skill > "${CODEX_HOME:-$HOME/.codex}/skills/phone-harness/SKILL.md"
```

`CODEX_HOME` defaults to `$HOME/.codex` when unset.

      </Step>
      <Step title="Verify">

```bash
head -5 "${CODEX_HOME:-$HOME/.codex}/skills/phone-harness/SKILL.md"
```

      </Step>
    </Steps>
  </Tab>
  <Tab title="Both (Fast Path)">

```bash
mkdir -p ~/.claude/skills/phone-harness
phone-harness skill > ~/.claude/skills/phone-harness/SKILL.md
mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills/phone-harness"
phone-harness skill > "${CODEX_HOME:-$HOME/.codex}/skills/phone-harness/SKILL.md"
```

  </Tab>
</Tabs>

| Target | Directory | File |
| --- | --- | --- |
| Claude Code | `~/.claude/skills/phone-harness/` | `SKILL.md` |
| Codex | `${CODEX_HOME:-$HOME/.codex}/skills/phone-harness/` | `SKILL.md` |

<Info>
Skill packs here are plain files under local skill directories. They are not a model-provider package, hosted connector, or BYOK secret. Any agent that loads skills from a filesystem path can use the same `phone-harness skill` body by writing it into its own skill root.
</Info>

## Trigger text

Agents should auto-select the skill when the user asks for iPhone control that maps to the description:

```text
Control the user's iPhone through the Mac's iPhone Mirroring window: open apps,
tap, type, swipe, read the screen.
```

Typical match intents:

- Open or navigate iOS apps through mirroring
- Tap, type, swipe, or scroll on the phone
- Read the mirrored screen (OCR / capture)

The skill body also steers agents **away** from phone use when a Mac or web path exists, and toward consent stops for outward-facing or irreversible actions.

## What the skill body tells the agent

| Topic | Instruction surface in `SKILL.md` |
| --- | --- |
| Invoke | `phone-harness <<'PY' … PY` with helpers pre-imported |
| Coordinates | Global screen points; do not cache across calls |
| Eyes | Prefer `ocr()`; `screenshot()` for unlabeled icons |
| Act | `tap_text`, `tap`, `swipe`, `scroll_*`, `type_text`, `press`, navigation helpers |
| Verify | `wait_stable()` then re-capture after every action |
| Connection | User physical action only; never tap Connect/Continue or poll |
| Consent | Ask before send/post/purchase/delete/settings changes |
| Task-specific code | Edit `agent-workspace/agent_helpers.py` (e.g. `tap_icon`) |
| Setup failures | Read `install.md` |

## Re-sync after pulls

Registered copies are **snapshots**, not live links to the checkout.

After `git pull` (or any edit to repo `SKILL.md`):

```bash
phone-harness skill > ~/.claude/skills/phone-harness/SKILL.md
phone-harness skill > "${CODEX_HOME:-$HOME/.codex}/skills/phone-harness/SKILL.md"
```

Re-run only the targets you use. Until you re-sync, agents keep the old trigger text and workflow notes.

## Setup prompt integration

The README setup prompt asks the agent to:

1. Clone to `~/.phone-harness` and follow `install.md`
2. Put `phone-harness` on `PATH`
3. Register skill name `phone-harness` with body from `phone-harness skill`
4. Read `SKILL.md` and `src/phone_harness/helpers.py` for normal use
5. Verify with `./phone-harness --doctor` (or `phone-harness --doctor` after install)

Registration is part of install, not a separate product mode.

## Failure modes

| Symptom | Cause | Fix |
| --- | --- | --- |
| `phone-harness: command not found` | Not on `PATH` / not installed | `cd ~/.phone-harness && pip install -e . --no-deps` |
| Skill file missing frontmatter | Wrong redirect / truncated write | Re-run `phone-harness skill > …/SKILL.md` |
| Agent never picks phone control | Skill not installed for that agent | Register under that agent’s skills path |
| Stale workflow after pull | Registered snapshot out of date | Re-run skill redirects |
| Skill prints, phone still fails | Permissions / session, not skill install | `phone-harness --doctor` and connection flow |

`phone-harness skill` does not validate mirroring or permissions; it only emits text.

## Related pages

<CardGroup>
  <Card title="Installation" href="/installation">
    Clone to ~/.phone-harness, pyobjc, editable install, PATH, and skill registration in the Fast Path.
  </Card>
  <Card title="CLI reference" href="/cli-reference">
    phone-harness entry points: stdin exec, --doctor, skill, help, and usage errors.
  </Card>
  <Card title="Extend agent helpers" href="/extend-agent-helpers">
    agent-workspace/agent_helpers.py, PH_AGENT_WORKSPACE, and task-specific primitives like tap_icon.
  </Card>
  <Card title="Quickstart" href="/quickstart">
    First successful phone-harness script after install and skill registration.
  </Card>
  <Card title="Doctor diagnostics" href="/doctor-diagnostics">
    Ordered permission and session checks that skill registration does not replace.
  </Card>
  <Card title="Consent and limits" href="/consent-and-limits">
    When the skill body says not to use the phone, and hard product limits.
  </Card>
</CardGroup>