Skip to content

docs: clarify Webcmd agent onboarding #23

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
ankitranjan7 wants to merge 2 commits into
base: main
Choose a base branch
from
+53 −10
Draft

docs: clarify Webcmd agent onboarding #23

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9420c85
docs: clarify webcmd agent onboarding
ankitranjan7 Jul 6, 2026
634343e
docs: add claude code plugin install path
ankitranjan7 Jul 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 25 additions & 8 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,17 +31,34 @@ Webcmd requires **Node.js >= 20**.
```bash
node --version
npm install -g @agentrhq/webcmd
webcmd --version
```

### 2. Verify the browser runtime
### 2. Teach your agent Webcmd

The CLI install is the same for everyone. Pick one agent-support path:

| Agent harness | Install Webcmd agent support |
|---------------|------------------------------|
| Codex | `codex plugin marketplace add agentrhq/webcmd`, then open `/plugins` and install Webcmd. |
| Claude Code | `/plugin marketplace add agentrhq/webcmd`, then `/plugin install webcmd@webcmd` |
| Cursor | `npx skills add agentrhq/webcmd --skill webcmd -a cursor` |
| Gemini CLI | `npx skills add agentrhq/webcmd --skill webcmd -a gemini-cli` |
| OpenCode | `npx skills add agentrhq/webcmd --skill webcmd -a opencode` |
| Hermes Agent | `npx skills add agentrhq/webcmd --skill webcmd -a hermes-agent` |
| Any skills-compatible agent | `npx skills add agentrhq/webcmd --skill webcmd` |

Codex and Claude Code users do not need the `npx skills add` command when they install the Webcmd plugin for their agent. The plugin bundles the Webcmd discovery skill.

### 3. Verify the browser runtime

```bash
webcmd doctor
```

`doctor` checks the Webcmd browser bridge: daemon status, runtime wiring, profile selection, and a live connectivity probe. Pure public adapters and local passthrough commands do not need a green browser check, but `COOKIE`, `INTERCEPT`, `UI`, and `webcmd browser` workflows do.

### 3. Discover commands
### 4. Discover commands

```bash
webcmd list
Expand All @@ -52,7 +69,7 @@ webcmd reddit hot --help

`webcmd list -f json` is the source of truth for agents. It emits one row per command with the site, command name, arguments, output columns, browser requirement, and strategy.

### 4. Run your first adapters
### 5. Run your first adapters

```bash
webcmd hackernews top --limit 5
Expand Down Expand Up @@ -111,16 +128,16 @@ Agents usually want `-f json`; humans usually want the default table.

## For AI Agents

Webcmd is designed to be driven by coding agents such as Codex, Claude Code, Cursor, and similar tools.
Webcmd is designed to be driven by coding agents such as Codex, Claude Code, Cursor, and similar tools. Install the CLI once, then install the agent support that matches your harness from the Quick Start table.

Install Webcmd skills into the agent environment with your agent's skill manager:
The installable skill is a discovery entrypoint. Runtime workflow skills are served by the installed CLI so instructions stay in sync with your Webcmd version:

```bash
npx skills add agentrhq/webcmd
webcmd skills list
webcmd skills get webcmd-usage
webcmd skills get webcmd-browser
```

Or install/copy only the skills you need from [`skills/`](./skills/) into your agent's skills root. These skills teach agents when to use adapters, when to drive the browser, how to author new adapters, and how to repair failing commands.

| Skill | When to use |
|-------|-------------|
| [`webcmd-usage`](./skills/webcmd-usage/SKILL.md) | Orient an agent to Webcmd commands, formats, strategies, plugins, and external CLIs. |
Expand Down
14 changes: 12 additions & 2 deletions docs/plugins-and-skills.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,16 @@ You can run those yourself, but they are usually part of an agent task.

Skills are instructions for agents. They help the agent choose the right workflow instead of guessing.

Webcmd has two install surfaces:

| Agent surface | Recommended install |
| --- | --- |
| Codex | Install the Webcmd plugin from the Codex plugin marketplace. |
| Claude Code | Install the Webcmd plugin from the Claude Code plugin marketplace. |
| Other skill-aware agents | Install the Webcmd discovery skill with `npx skills add agentrhq/webcmd --skill webcmd`. |

Install the CLI separately with `npm install -g @agentrhq/webcmd`. The skill or plugin teaches the agent how to use the `webcmd` binary; it should not be treated as the CLI package itself.

Common skills:

| Skill | Purpose |
Expand All @@ -69,10 +79,10 @@ Use the Webcmd adapter-author skill to create this command. If the site changes

## Installing Skills for Agents

If your agent supports skills, install or copy the relevant Webcmd skills from the package. Then tell the agent to use them.
If your agent supports skills, install the Webcmd discovery skill. Then tell the agent to load the runtime workflow it needs.

```text
Before working on this site, load the Webcmd usage and adapter-author skills. Prefer an existing adapter if one exists.
Before working on this site, load the Webcmd usage workflow and prefer an existing adapter if one exists.
```

## Recommended Agent Behavior
Expand Down
16 changes: 16 additions & 0 deletions docs/quickstart.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,22 @@ webcmd --version
webcmd --help
```

## Install Agent Support

The CLI install is universal. The second step depends on the agent harness you use:

| Agent harness | Install Webcmd agent support |
| --- | --- |
| Codex | `codex plugin marketplace add agentrhq/webcmd`, then open `/plugins` and install Webcmd. |
| Claude Code | `/plugin marketplace add agentrhq/webcmd`, then `/plugin install webcmd@webcmd` |
| Cursor | `npx skills add agentrhq/webcmd --skill webcmd -a cursor` |
| Gemini CLI | `npx skills add agentrhq/webcmd --skill webcmd -a gemini-cli` |
| OpenCode | `npx skills add agentrhq/webcmd --skill webcmd -a opencode` |
| Hermes Agent | `npx skills add agentrhq/webcmd --skill webcmd -a hermes-agent` |
| Any skills-compatible agent | `npx skills add agentrhq/webcmd --skill webcmd` |

Codex and Claude Code plugin installs already include the Webcmd discovery skill, so users on those agents do not need a separate `npx skills add` step.

## Verify the Runtime

Agents use Webcmd for public commands, authenticated browser workflows, local CLIs, and adapter authoring. Verify the local runtime before asking an agent to create commands:
Expand Down
Loading