p2claw — Claude Code plugin: share local apps by link

# p2claw skill

The agent skill for **[p2claw](https://p2claw.com)**: give apps
running on a machine a peer-to-peer URL, put sign-in in front of
them, share private apps between machines, and receive email for an
agent. Works with any [Agent Skills](https://agentskills.io)–compatible
coding agent.

With this skill loaded, your agent can:

- **Publish a local app** at `https://<app>-<alias>.p2claw.com/`,
  with a QR code for your phone. It installs the `p2claw` binary if
  needed (bundled installer, no `sudo`), starts the agent as a
  launchd / systemd user service or in the foreground, registers the
  app, and checks the upstream answers.
- **Add sign-in** without registering OAuth apps with Google or
  GitHub: gate any app with one flag, or configure an app that
  already supports OIDC (Immich, Grafana, Nextcloud, …) to use the
  p2claw broker as its login provider. It knows which to pick.
- **Share private apps between machines**: apps with no public URL,
  reachable only by the peer ids you share them with, and reach apps
  other machines have shared with you.
- **Receive email** at `<alias>@p2claw.com` from allowlisted senders
  and read it safely: catching up and watching the inbox, treating
  forwarded mail as data rather than instructions, and leaving the
  allowlist to the owner.
- **Drive the agent from code** through its local Unix-socket API and
  the Python / Node client libraries.

The agent does the work; this skill is the instruction set that tells
it how. The instructions are in [`p2claw/SKILL.md`](./p2claw/SKILL.md),
with detail in [`p2claw/references/`](./p2claw/references/).

> [!NOTE]
> p2claw assumes a Bash/POSIX shell and supports macOS + Linux.
> Windows users should run their agent inside WSL — the bundled
> installer detects Windows and refuses with a helpful pointer.

---

## Installing the skill

Pick the matching section for your agent. All routes leave you with
the same on-disk shape — a `p2claw/` skill directory the agent can
discover.

### Claude Code

The repo ships a [`.claude-plugin/marketplace.json`](.claude-plugin/marketplace.json)
manifest, so the cleanest path is to register this repo as a
marketplace and install through it:

```text
/plugin marketplace add phact/p2claw-skill
/plugin install p2claw@p2claw
```

Alternatively, drop the skill in by hand:

```bash
git clone --depth 1 https://github.com/phact/p2claw-skill /tmp/p2claw-skill
cp -r /tmp/p2claw-skill/p2claw ~/.claude/skills/p2claw
```

After install, restart Claude Code and run `/skills` to confirm
`p2claw` appears in the list. (Project-scoped install is the same
flow into `.claude/skills/p2claw/` instead of `~/.claude/skills/`.)

### Claude Desktop

Open the **Customize** panel in the left sidebar → **Skills** → click
the **+** next to *Personal plugins* → paste:

```
phact/p2claw-skill
```

Restart the app once installation finishes. The skill becomes
available as soon as you start a new conversation.

### GitHub CLI (Copilot / `gh skill`)

If you have `gh` v2.90.0 or newer, the GitHub CLI ships a `skill`
subcommand that handles install for any agent it recognises:

```bash
gh skill install phact/p2claw-skill
```

Older `gh`: `gh extension install` the upstream `gh-skill` extension
first, or fall through to the manual git-clone path below.

### OpenAI Codex CLI

Codex scans `.agents/skills/` upward from the working directory, plus
the user-scope skill dir under `~/.config/codex/skills/`. Drop the
skill into either:

```bash
git clone --depth 1 https://github.com/phact/p2claw-skill /tmp/p2claw-skill
mkdir -p ~/.config/codex/skills
cp -r /tmp/p2claw-skill/p2claw ~/.config/codex/skills/p2claw
```

For project-scoped use, replace `~/.config/codex/skills` with
`<repo>/.agents/skills` inside the repo where you want it active.

### GitHub Copilot in VS Code

Skills follow the same SKILL.md format VS Code's Agent Skills feature
expects. Either install via `gh skill install phact/p2claw-skill`
(see above), or use the VS Code skill UI: **Command Palette → Agent
Skills: Add Skill** → paste the repo URL.

### Gemini CLI

```bash
git clone --depth 1 https://github.com/phact/p2claw-skill /tmp/p2claw-skill
cp -r /tmp/p2claw-skill/p2claw ~/.gemini/skills/p2claw
```

(Gemini's path is `~/.gemini/skills/<name>/SKILL.md`. Restart Gemini
CLI to pick up the new skill.)

### OpenCode

OpenCode also reads SKILL.md from a per-user skills directory:

```bash
git clone --depth 1 https://github.com/phact/p2claw-skill /tmp/p2claw-skill
cp -r /tmp/p2claw-skill/p2claw ~/.opencode/skills/p2claw
```

### Any other SKILL.md-compatible agent

The skill folder is `p2claw/` at the root of this repo. Every
SKILL.md-aware agent (per the
[Agent Skills spec](https://agentskills.io)) discovers skills from a
configured directory containing `<name>/SKILL.md`. Drop `p2claw/`
into whatever path your agent uses and you're done.

---

## What gets installed when you use the skill

The skill **doesn't** install the p2claw binary at skill-install time.
The binary is installed lazily, the first time the agent uses the
skill, via the bundled
[`p2claw/scripts/install.sh`](./p2claw/scripts/install.sh) — a
byte-identical copy of the canonical installer at
**[p2claw.com/install](https://p2claw.com/install)**. Drift between
the two is caught by
[`.github/workflows/install-script-sync.yml`](.github/workflows/install-script-sync.yml),
which opens a PR daily if they diverge.

When the agent first runs the bundled installer, it:

- Detects your OS + arch (macOS aarch64/x86_64, Linux x86_64/aarch64).
- Downloads the matching binary from the [p2claw-agent](https://github.com/phact/p2claw-agent) releases.
- Verifies SHA-256 against the published `SHA256SUMS`.
- Drops the binary at `~/.local/bin/p2claw` (no `sudo`).
- Optionally registers it as a launchd / systemd `--user` service so
  it survives reboot — only if you say yes when the agent asks.

Everything user-managed: `~/.local/bin/p2claw`, the agent's
`~/Library/Application Support/p2claw/` (macOS) or
`~/.local/share/p2claw/` (Linux) state directory, and the optional
launchd plist or systemd unit. Nothing system-wide. The agent
auto-upgrades itself from the p2claw-agent releases; the skill
documents how to pin or disable that.

---

## Uninstalling

```bash
~/.local/bin/p2claw service uninstall   # if you registered as a service
rm ~/.local/bin/p2claw
rm -rf "~/Library/Application Support/p2claw"   # macOS
# or
rm -rf ~/.local/share/p2claw                    # Linux
```

Then remove the skill from your agent's skill directory (the inverse
of whichever install path you used above).

---

## Links

- **Site & docs:** <https://p2claw.com>
- **Install script (canonical):** <https://p2claw.com/install>
- **Skill source:** [`p2claw/SKILL.md`](./p2claw/SKILL.md)
- **Agent source and releases (MIT):** <https://github.com/phact/p2claw-agent>
- **Agent Skills spec:** <https://agentskills.io>