# `ego-browser skill` browser integration

The ego-browser Skill has two layers:

- **Entry Skill** — `skills/ego-browser/` in this repository. It is what skill
  markets, plugins, and `~/.agents/skills/ego-browser` contain. It only tells the
  agent to run `ego-browser skill`, plus the install guide and the
  cookie/cache/storage guide that must be readable before ego lite exists.
- **Usage guide** — `package/ego-browser/skill-body/SKILL.md`. It is versioned
  with the SDK and printed by `ego-browser skill`, so the agent always reads the
  guide that matches the installed browser. The build renders one guide per
  operating system from this single source: passages between
  `<!-- platform: windows -->` and `<!-- /platform -->` markers (or
  `platform: macos`) only reach that platform's guide.

This document lists what the ego lite app and its native `ego-browser` launcher
must implement. Everything else lives in this repository.

## Release payload

`npm run build` writes the payload to `package/ego-browser/dist/out/`
(CI archives the same directory as `ego-browser-release-payload.tar.gz`):

```text
dist/out/
├── index.js                     SDK bundle
├── ego-browser/
│   ├── SKILL.md                 all-platform usage guide (fallback)
│   ├── SKILL.macos.md           usage guide printed by `ego-browser skill` on macOS
│   └── SKILL.windows.md         usage guide printed by `ego-browser skill` on Windows
└── agent-skills/
    └── ego-browser/             entry Skill to install into ~/.agents/skills/ego-browser
        ├── SKILL.md
        ├── references/
        ├── scripts/
        ├── agents/
        ├── assets/
        └── learnings/           site learnings; the SDK reads this bundled copy
```

Ship `dist/out/` as one unit inside the app, keeping `ego-browser/` next to
`index.js`.

## 1. Add the `ego-browser skill` subcommand

1. Resolve the SDK with exactly the same rules as `ego-browser nodejs`:
   `--sdk-path`, then the debug override
   (`~/Library/Application Support/Citro Labs/debug/index.js`), then the bundled
   SDK. Do not implement a separate lookup, or the guide and SDK can come from
   different builds.
2. Pick the guide for the operating system the launcher runs on, from the
   directory that contains the resolved `index.js`: `ego-browser/SKILL.macos.md`
   on macOS, `ego-browser/SKILL.windows.md` on Windows. When that file does not
   exist (an older SDK passed through `--sdk-path`, or a platform without its
   own guide, such as Linux), read `ego-browser/SKILL.md` instead. Choose by
   operating system, not by the parent shell: the Windows guide already covers
   Git Bash, PowerShell, and cmd.
3. Write it to stdout unchanged and exit 0. The build already adds the first
   line (`[ego-browser:skill] ego-browser usage guide v<version> (<platform>)`,
   without the parenthesis in the all-platform `SKILL.md`) and the last line
   (`[ego-browser:skill] end of guide v<version>`); do not add or parse
   anything else.
4. When the SDK is not the bundled one, print one extra line before the guide so
   developers notice the override:

   ```text
   [ego-browser:skill] source=debug-sdk dir=/path/to/dist/out/ego-browser (override, not the bundled guide)
   ```

   `source` is `sdk-path` or `debug-sdk`.

Errors:

| Case                                                    | Behavior                                                                                     |
| ------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| Any extra argument, e.g. `ego-browser skill foo`        | Print usage to stderr, exit non-zero                                                         |
| Neither the platform guide nor `ego-browser/SKILL.md` exists next to the resolved SDK | Print the paths that were checked to stderr, exit non-zero; do not fall back to another source |

Also list `skill` in `ego-browser help`, e.g. "Print the usage guide for this
ego lite version".

Older launchers print `Unknown command: skill` and exit 2. The entry Skill
relies on that to send the agent to `references/install.md`, which asks the user
to run `ego-browser upgrade`.

## 2. Install the entry Skill on launch

On every launch, check `~/.agents/skills/ego-browser`:

| Current state                                                              | Action                                                                                             |
| -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| Missing                                                                    | Copy `agent-skills/ego-browser/` there as real files                                               |
| A symlink the browser created earlier (to `~/.local/share/ego/ego-skills`) | Replace it with a copy of `agent-skills/ego-browser/`, then delete `~/.local/share/ego/ego-skills` |
| Anything else (installed by the user or a package manager)                 | Leave it untouched                                                                                 |

Stop extracting the full Skill to `~/.local/share/ego/ego-skills`. After the
entry Skill is in place, the browser never writes `~/.agents/skills` again;
upgrades only replace the bundled payload.

## Acceptance checks

- [ ] `ego-browser skill` output is byte-identical to the bundled
      `ego-browser/SKILL.macos.md` on macOS and `ego-browser/SKILL.windows.md`
      on Windows, starts with the version line naming that platform, and ends
      with `[ego-browser:skill] end of guide v<version>`.
- [ ] On macOS the printed guide has no `### PowerShell` section; on Windows it
      has both the `### Bash, Zsh, Git Bash` and `### PowerShell` sections.
- [ ] With an SDK directory that only contains `ego-browser/SKILL.md`, the
      command prints that file.
- [ ] With `--sdk-path <checkout>/package/ego-browser/dist/out/index.js` or the
      debug override, the output is the checkout's guide and starts with a
      `source=` line; removing the override restores the bundled guide.
- [ ] `ego-browser skill foo` and a missing guide both exit non-zero with a
      readable error.
- [ ] `ego-browser help` lists `skill`.
- [ ] Fresh install: `~/.agents/skills/ego-browser` contains the entry Skill.
- [ ] Upgrade from a version that used the `ego-skills` symlink: the symlink is
      replaced by the entry Skill. A user-installed Skill stays unchanged.