feat: SKILL.md template system with auto-generated command references

- SKILL.md.tmpl + browse/SKILL.md.tmpl with {{COMMAND_REFERENCE}} and {{SNAPSHOT_FLAGS}} placeholders - scripts/gen-skill-docs.ts generates SKILL.md from templates (supports --dry-run) - Build pipeline runs gen:skill-docs before binary compilation - Generated files have AUTO-GENERATED header, committed to git
2026-05-07 14:06:42 +02:00 · 2026-03-13 15:43:21 -07:00
parent f565a06912
commit 9aec68142d
6 changed files with 690 additions and 65 deletions
@@ -12,6 +12,8 @@ allowed-tools:
  - Read

 ---
+<!-- AUTO-GENERATED from SKILL.md.tmpl — do not edit directly -->
+<!-- Regenerate: bun run gen:skill-docs -->

 # browse: QA Testing & Dogfooding

@@ -99,30 +101,115 @@ $B diff https://staging.app.com https://prod.app.com

 ## Snapshot Flags

+The snapshot is your primary tool for understanding and interacting with pages.
+
 ```
-i        Interactive elements only (buttons, links, inputs)
-c        Compact (no empty structural nodes)
-d <N>    Limit depth
-s <sel>  Scope to CSS selector
+-i        Interactive elements only
+-c        Remove empty structural elements
+-d        Limit tree depth
+-s        Scope to CSS selector
 -D        Diff against previous snapshot
 -a        Annotated screenshot with ref labels
-o <path> Output path for screenshot
-C        Cursor-interactive elements (@c refs)
+-o        Output path for annotated screenshot
+-C        Scan cursor:pointer/onclick/tabindex elements
 ```

-Combine: `$B snapshot -i -a -C -o /tmp/annotated.png`
+Combine flags: `$B snapshot -i -a -C -o /tmp/annotated.png`

-Use @refs after snapshot: `$B click @e3`, `$B fill @e4 "value"`, `$B click @c1`
+After snapshot, use @refs everywhere:
+```bash
+$B click @e3       $B fill @e4 "value"     $B hover @e1
+$B html @e2        $B css @e5 "color"      $B attrs @e6
+$B click @c1       # cursor-interactive ref (from -C)
+```
+
+Refs are invalidated on navigation — run `snapshot` again after `goto`.

 ## Full Command List

-**Navigate:** goto, back, forward, reload, url
-**Read:** text, html, links, forms, accessibility
-**Snapshot:** snapshot (with flags above)
-**Interact:** click, fill, select, hover, type, press, scroll, wait, wait --networkidle, wait --load, viewport, upload, cookie-import, dialog-accept, dialog-dismiss
-**Inspect:** js, eval, css, attrs, is, console, console --errors, network, dialog, cookies, storage, perf
-**Visual:** screenshot, pdf, responsive
-**Compare:** diff
-**Multi-step:** chain (pipe JSON array)
-**Tabs:** tabs, tab, newtab, closetab
-**Server:** status, stop, restart
+### Navigation
+| Command | Description |
+|---------|-------------|
+| `back` | History back |
+| `forward` | History forward |
+| `goto <url>` | Navigate to URL |
+| `reload` | Reload page |
+| `url` | Print current URL |
+
+### Reading
+| Command | Description |
+|---------|-------------|
+| `accessibility` | Full ARIA tree |
+| `forms` | Form fields as JSON |
+| `html [selector]` | innerHTML |
+| `links` | All links as "text → href" |
+| `text` | Cleaned page text |
+
+### Interaction
+| Command | Description |
+|---------|-------------|
+| `click <sel>` | Click element |
+| `cookie` | Set cookie |
+| `cookie-import <json>` | Import cookies from JSON file |
+| `cookie-import-browser [browser] [--domain d]` | Import cookies from real browser |
+| `dialog-accept [text]` | Auto-accept next dialog |
+| `dialog-dismiss` | Auto-dismiss next dialog |
+| `fill <sel> <val>` | Fill input |
+| `header <name> <value>` | Set custom request header |
+| `hover <sel>` | Hover element |
+| `press <key>` | Press key |
+| `scroll [sel]` | Scroll element into view |
+| `select <sel> <val>` | Select dropdown option |
+| `type <text>` | Type into focused element |
+| `upload <sel> <file...>` | Upload file(s) |
+| `useragent <string>` | Set user agent |
+| `viewport <WxH>` | Set viewport size |
+| `wait <sel|--networkidle|--load>` | Wait for element/condition |
+
+### Inspection
+| Command | Description |
+|---------|-------------|
+| `attrs <sel>` | Element attributes as JSON |
+| `console [--clear|--errors]` | Console messages |
+| `cookies` | All cookies as JSON |
+| `css <sel> <prop>` | Computed CSS value |
+| `dialog [--clear]` | Dialog messages |
+| `eval <file>` | Run JS file |
+| `is <prop> <sel>` | State check |
+| `js <expr>` | Run JavaScript |
+| `network [--clear]` | Network requests |
+| `perf` | Page load timings |
+| `storage [set k v]` | localStorage + sessionStorage |
+
+### Visual
+| Command | Description |
+|---------|-------------|
+| `diff <url1> <url2>` | Text diff between pages |
+| `pdf [path]` | Save as PDF |
+| `responsive [prefix]` | Mobile/tablet/desktop screenshots |
+| `screenshot [path]` | Save screenshot |
+
+### Snapshot
+| Command | Description |
+|---------|-------------|
+| `snapshot [flags]` | Accessibility tree with @refs |
+
+### Meta
+| Command | Description |
+|---------|-------------|
+| `chain` | Multi-command from JSON stdin |
+
+### Tabs
+| Command | Description |
+|---------|-------------|
+| `closetab [id]` | Close tab |
+| `newtab [url]` | Open new tab |
+| `tab <id>` | Switch to tab |
+| `tabs` | List open tabs |
+
+### Server
+| Command | Description |
+|---------|-------------|
+| `restart` | Restart server |
+| `status` | Health check |
+| `stop` | Shutdown server |
@@ -0,0 +1,106 @@
+---
+name: browse
+version: 1.1.0
+description: |
+  Fast headless browser for QA testing and site dogfooding. Navigate any URL, interact with
+  elements, verify page state, diff before/after actions, take annotated screenshots, check
+  responsive layouts, test forms and uploads, handle dialogs, and assert element states.
+  ~100ms per command. Use when you need to test a feature, verify a deployment, dogfood a
+  user flow, or file a bug with evidence.
+allowed-tools:
+  - Bash
+  - Read
+
+---
+
+# browse: QA Testing & Dogfooding
+
+Persistent headless Chromium. First call auto-starts (~3s), then ~100ms per command.
+State persists between calls (cookies, tabs, login sessions).
+
+## Core QA Patterns
+
+### 1. Verify a page loads correctly
+```bash
+$B goto https://yourapp.com
+$B text                          # content loads?
+$B console                       # JS errors?
+$B network                       # failed requests?
+$B is visible ".main-content"    # key elements present?
+```
+
+### 2. Test a user flow
+```bash
+$B goto https://app.com/login
+$B snapshot -i                   # see all interactive elements
+$B fill @e3 "user@test.com"
+$B fill @e4 "password"
+$B click @e5                     # submit
+$B snapshot -D                   # diff: what changed after submit?
+$B is visible ".dashboard"       # success state present?
+```
+
+### 3. Verify an action worked
+```bash
+$B snapshot                      # baseline
+$B click @e3                     # do something
+$B snapshot -D                   # unified diff shows exactly what changed
+```
+
+### 4. Visual evidence for bug reports
+```bash
+$B snapshot -i -a -o /tmp/annotated.png   # labeled screenshot
+$B screenshot /tmp/bug.png                # plain screenshot
+$B console                                # error log
+```
+
+### 5. Find all clickable elements (including non-ARIA)
+```bash
+$B snapshot -C                   # finds divs with cursor:pointer, onclick, tabindex
+$B click @c1                     # interact with them
+```
+
+### 6. Assert element states
+```bash
+$B is visible ".modal"
+$B is enabled "#submit-btn"
+$B is disabled "#submit-btn"
+$B is checked "#agree-checkbox"
+$B is editable "#name-field"
+$B is focused "#search-input"
+$B js "document.body.textContent.includes('Success')"
+```
+
+### 7. Test responsive layouts
+```bash
+$B responsive /tmp/layout        # mobile + tablet + desktop screenshots
+$B viewport 375x812              # or set specific viewport
+$B screenshot /tmp/mobile.png
+```
+
+### 8. Test file uploads
+```bash
+$B upload "#file-input" /path/to/file.pdf
+$B is visible ".upload-success"
+```
+
+### 9. Test dialogs
+```bash
+$B dialog-accept "yes"           # set up handler
+$B click "#delete-button"        # trigger dialog
+$B dialog                        # see what appeared
+$B snapshot -D                   # verify deletion happened
+```
+
+### 10. Compare environments
+```bash
+$B diff https://staging.app.com https://prod.app.com
+```
+
+## Snapshot Flags
+
+{{SNAPSHOT_FLAGS}}
+
+## Full Command List
+
+{{COMMAND_REFERENCE}}