Skip to content
BetterWrightDocs
Browse docs

Skill packs

BetterWright is an add-on: a host agent (Claude Code, Codex, a Pi package, or any MCP client) drives it. One static operator prompt can teach that agent the mechanics of the browser, but it cannot carry the specifics of every site and password manager without bloating every request. Skill packs solve that — small Markdown files the host agent reads on demand, only when a page or task makes them relevant.

Per-site and per-provider guidance stays true to BetterWright's role: the packs are plain files the controlling agent reads with the file tool it already has. BetterWright never becomes an agent itself.

What a pack looks like

A skill is a directory with a SKILL.md:

---
name: github
description: GitHub navigation, review, and account-context guidance.
siteSpecific: true
autoInject:
  keywords: ["github"]
  url: ["github.com", "gist.github.com"]
---
# GitHub

## Canonical URLs
...
  • name (required) — lowercase-hyphen-case, matching the directory.
  • description (required) — the primary "read this when…" trigger the agent sees before opening the pack.
  • autoInject.url — host or host/path/** glob patterns. When an open page matches, the pack is surfaced in that run's result (see below).
  • autoInject.keywords — phrases in the task text that suggest the pack.
  • siteSpecific — marks per-site guidance.

Keep SKILL.md short; link sibling ./reference.md files for depth so the agent pulls detail in only when it needs it.

How the host agent finds them

Every run result carries a skills array listing packs whose autoInject.url patterns match any open page:

{
  "ok": true,
  "pages": [{ "url": "https://github.com/o/r/pull/1", "active": true }],
  "skills": [
    { "name": "github", "description": "GitHub navigation…", "path": "/…/skills/github/SKILL.md" }
  ]
}

The operator prompt tells the agent to read the named path (with its own file tool, or betterwright skills show <name>) before improvising site-specific behavior, and to read the credential-manager pack before any login, signup, or checkout.

Packaged and user packs

Packaged packs ship in the npm package's skills/:

  • credential-manager — the source-order ladder for logins, signups, password changes, and payments, and the rules that keep secrets out of the transcript.
  • 1password, bitwarden — provider packs encoding the inline-menu detection heuristics, extension popup URLs, and unlock-then-reload flows.
  • github — a lean site pack (canonical URLs, working style, shortcuts).

Add your own under $BETTERWRIGHT_HOME/skills/<name>/SKILL.md; a user pack overrides a packaged one with the same name. List everything with betterwright skills list.

CLI

betterwright skills list          # name + description, one per line
betterwright skills show github   # print a pack's body

The programmatic API (listSkills, readSkill, matchSkillsForUrl, matchSkillsForText, skillHintsForPages, parseSkillDocument) is exported from the package root for hosts that want to surface packs their own way.