---
title: Skills
description: "Load agent-desktop's skills with the skills command. They are compiled into the binary, so they always match the installed version."
url: "https://agent-browser.dev/desktop/skills"
docs_index: /desktop/llms.txt
lastUpdated: 2026-10-30
navTitle: "Skills"
---

> For an index of all documentation, see [/desktop/llms.txt](/desktop/llms.txt).

agent-desktop ships guides written for AI agents: the observe, act, and verify loop, the retry rules, and what differs on each OS. They are compiled into the binary, so the instructions an agent reads always match the version it runs. The `skills` command prints them. It needs no permission and no desktop session.

## Bootstrap an agent

Run these three commands before the first action:

```bash
agent-desktop status                  # platform, permissions, supported surfaces
agent-desktop skills get desktop      # the loop, refs, verification, and retry rules
agent-desktop skills get platform     # what differs on the OS the binary runs on
```

To make this automatic, put the bootstrap in your agent's instructions file (`AGENTS.md` or equivalent):

```markdown
Use `agent-desktop` to see and operate desktop apps. Before the first use, run
`agent-desktop skills get desktop` and `agent-desktop skills get platform`, and follow them.
```

## The skills command

Every form prints the JSON envelope. A skill's Markdown is in `data.content`.

<table>
  <thead>
    <tr>
      <th>Command</th>

      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>agent-desktop skills</code></td>

      <td>List skills, the same as <code>skills list</code></td>
    </tr>

    <tr>
      <td><code>agent-desktop skills list</code></td>

      <td>List every bundled skill with its aliases and references</td>
    </tr>

    <tr>
      <td><code>agent-desktop skills get \<name></code></td>

      <td>Print one skill's main guide</td>
    </tr>

    <tr>
      <td><code>agent-desktop skills get \<name> \<reference></code></td>

      <td>Print one reference file of that skill</td>
    </tr>

    <tr>
      <td><code>agent-desktop skills get \<name> --full</code></td>

      <td>Print the main guide followed by every reference, each introduced by a <code>--- references/\<file>.md ---</code> line</td>
    </tr>

    <tr>
      <td><code>agent-desktop skills path</code></td>

      <td>Report that skills are embedded, and list the available names</td>
    </tr>
  </tbody>
</table>

`--full` is the only flag the command adds, and it has no effect when you pass a reference. To read a skill as plain Markdown, extract `data.content`:

```bash
agent-desktop skills get desktop | jq -r '.data.content'
```

`skills path` confirms there is no skills directory on disk:

```json
{
  "version": "2.5",
  "ok": true,
  "command": "skills",
  "data": {
    "available": ["agent-desktop", "agent-desktop-macos", "agent-desktop-windows", "agent-desktop-linux", "agent-desktop-ffi", "jev-desktop"],
    "location": "embedded",
    "note": "Skills are compiled into this binary and are always version-matched. Run `agent-desktop skills get <name>` to print a skill, or redirect into a file to extract a copy."
  }
}
```

## Available skills

`<name>` accepts the canonical name or an alias.

<table>
  <thead>
    <tr>
      <th>Name</th>

      <th>Alias</th>

      <th>Covers</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>agent-desktop</code></td>

      <td><code>desktop</code></td>

      <td>The core guide for every OS: the snapshot and ref loop, verification and retry rules, and when to open each reference. Load it first.</td>
    </tr>

    <tr>
      <td><code>agent-desktop-macos</code></td>

      <td><code>macos</code></td>

      <td>What differs on macOS: permissions, Notification Center, troubleshooting.</td>
    </tr>

    <tr>
      <td><code>agent-desktop-windows</code></td>

      <td><code>windows</code></td>

      <td>What differs on Windows: PowerShell quoting, elevation, shell surfaces, Chromium and Electron, troubleshooting.</td>
    </tr>

    <tr>
      <td><code>agent-desktop-linux</code></td>

      <td><code>linux</code></td>

      <td>What differs on Linux: the AT-SPI bus, X11 and Wayland, window lifecycle, capture and clipboard, shell and notifications, troubleshooting.</td>
    </tr>

    <tr>
      <td><code>agent-desktop-ffi</code></td>

      <td><code>ffi</code></td>

      <td>Embedding agent-desktop through the <a href="/desktop/ffi">C library</a>: build and link, errors, ownership, threading.</td>
    </tr>

    <tr>
      <td><code>jev-desktop</code></td>

      <td><code>jev</code></td>

      <td>An optional helper that drives an app from a plain-language goal. It needs a clone of the repository and an API key, and it is not part of the native CLI.</td>
    </tr>
  </tbody>
</table>

`platform` resolves to the skill for the OS the binary runs on. `skills list` marks platform skills with `platform` and `current`; this is the Linux entry on a Linux machine:

```json
{
  "aliases": ["linux", "agent-desktop-linux"],
  "current": true,
  "name": "agent-desktop-linux",
  "platform": "linux",
  "references": [
    "references/bus-and-permissions.md",
    "references/display-servers-and-input.md",
    "references/windows-and-lifecycle.md",
    "references/capture-and-clipboard.md",
    "references/shell-tray-and-notifications.md",
    "references/troubleshooting.md"
  ]
}
```

An unknown name returns `INVALID_ARGS` and lists every alias:

```json
{
  "code": "INVALID_ARGS",
  "message": "Unknown skill 'nope'. Known: desktop, agent-desktop, macos, agent-desktop-macos, windows, agent-desktop-windows, linux, agent-desktop-linux, ffi, agent-desktop-ffi, jev, jev-desktop"
}
```

## References

Load a reference only when you need it. Name it by path (`references/workflows.md`), file name (`workflows.md`), or stem (`workflows`):

```bash
agent-desktop skills get desktop workflows
agent-desktop skills get linux troubleshooting
```

<table>
  <thead>
    <tr>
      <th>Skill</th>

      <th>References</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>desktop</code></td>

      <td><code>commands-observation</code>, <code>commands-interaction</code>, <code>commands-system</code>, <code>workflows</code></td>
    </tr>

    <tr>
      <td><code>macos</code></td>

      <td><code>troubleshooting</code></td>
    </tr>

    <tr>
      <td><code>windows</code></td>

      <td><code>permissions-and-elevation</code>, <code>chromium-and-electron</code>, <code>troubleshooting</code>, <code>shell-and-overlay</code></td>
    </tr>

    <tr>
      <td><code>linux</code></td>

      <td><code>bus-and-permissions</code>, <code>display-servers-and-input</code>, <code>windows-and-lifecycle</code>, <code>capture-and-clipboard</code>, <code>shell-tray-and-notifications</code>, <code>troubleshooting</code></td>
    </tr>

    <tr>
      <td><code>ffi</code></td>

      <td><code>build-and-link</code>, <code>error-handling</code>, <code>ownership</code>, <code>threading</code></td>
    </tr>
  </tbody>
</table>

An unknown reference returns `INVALID_ARGS` and lists the available ones.

## Install a skill in an agent harness

A harness that supports skills can also install a static copy with `npx skills add`:

```bash
npx skills add https://github.com/vercel-labs/agent-desktop --skill agent-desktop
```

You can also add `--skill agent-desktop-ffi` or the platform skill for your OS (`agent-desktop-macos`, `agent-desktop-windows`, or `agent-desktop-linux`). An installed copy can go stale when you upgrade the CLI, so prefer `agent-desktop skills get`, which always matches the binary you run.

---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)