agent-skill-kit 3.9.135

package/.agent/skills/chrome-devtools/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: chrome-devtools
+description: >-
+  Puppeteer CLI scripts for browser screenshots, debugging, and Core Web Vitals measurement.
+  Use when capturing screenshots, measuring performance, or debugging browser issues.
+  NOT for E2E test suites (use e2e-automation) or AI browser automation (use agent-browser).
+category: browser-automation
+triggers: ["screenshot", "browser", "puppeteer", "devtools", "performance"]
+coordinates_with: ["agent-browser", "perf-optimizer", "e2e-automation"]
+success_metrics: ["0 ghost instances", "100% session recovery"]
+metadata:
+  author: pikakit
+  version: "3.9.134"
+---
+
+# Chrome DevTools — Puppeteer CLI
+
+> Direct Puppeteer CLI scripts. Session persistence. JSON output. Auto-compressed screenshots.
+
+---
+
+## Prerequisites
+
+**Required:**
+- Node.js 18+
+- Puppeteer: `npm install puppeteer sharp yargs`
+
+**Linux/WSL:** Chrome dependencies via `./install-deps.sh`
+
+---
+
+## When to Use
+
+| Use This For | Use `agent-browser` For |
+|--------------|------------------------|
+| Quick screenshots | Long autonomous AI sessions |
+| Custom Puppeteer scripts | Context-constrained agent workflows |
+| WebSocket debugging | Cloud browsers (CI/CD) |
+| Core Web Vitals measurement | Multi-tab @ref interactions |
+| Auth injection, form filling | AI-optimized element referencing |
+
+---
+
+## System Boundaries
+
+| Owned by This Skill | NOT Owned |
+|---------------------|-----------|
+| 10 Puppeteer CLI scripts | E2E test suites (→ e2e-automation) |
+| Session persistence (.browser-session.json) | AI @ref handle system (→ agent-browser) |
+| Screenshot capture + auto-compress | Performance recommendations (→ perf-optimizer) |
+| Core Web Vitals measurement | Cross-browser testing |
+| Console/network monitoring | Browser installation |
+
+**Side effects:** Launches browser processes, writes files (screenshots, session), executes JavaScript in page context, navigates pages with network requests.
+
+---
+
+## Available Scripts
+
+| Script | Purpose | Side Effects | Idempotent |
+|--------|---------|-------------|-----------|
+| `navigate.ts` | Navigate to URL | Browser launch, page navigation | No |
+| `screenshot.ts` | Capture screenshot | File write (auto-compress > 5MB) | No |
+| `click.ts` | Click element | Page state mutation | No |
+| `fill.ts` | Fill form field | Form state mutation | No |
+| `evaluate.ts` | Execute JavaScript | Depends on script content | Depends |
+| `aria-snapshot.ts` | Get ARIA tree (YAML) | None (read-only) | Yes |
+| `select-ref.ts` | Interact by ref | Page state mutation | No |
+| `console.ts` | Monitor console | None (passive) | Yes |
+| `network.ts` | Track HTTP requests | None (passive) | Yes |
+| `performance.ts` | Core Web Vitals | Navigation + measurement | No |
+
+---
+
+## Session Persistence
+
+```bash
+# 1. Launch session (browser starts)
+node navigate.ts --url https://example.com/login
+
+# 2. Interact (browser reuses session)
+node fill.ts --selector "#email" --value "user@example.com"
+node click.ts --selector "button[type=submit]"
+
+# 3. Capture
+node screenshot.ts --output ./result.png
+
+# 4. Close (browser terminates)
+node navigate.ts --close true
+```
+
+**State:** `.browser-session.json` in working directory. One session per directory. Delete file to reset.
+
+---
+
+## Common Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--headless false` | true | Show browser window |
+| `--close true` | false | Terminate browser process |
+| `--timeout 30000` | 30000 | Timeout in ms |
+| `--wait-until networkidle2` | load | Wait strategy |
+| `--full-page true` | false | Full page screenshot |
+| `--max-size 5` | 5 | Max screenshot MB before auto-compress |
+
+---
+
+## Error Taxonomy
+
+| Code | Recoverable | Trigger |
+|------|-------------|---------|
+| `ERR_ELEMENT_NOT_FOUND` | Yes | CSS selector matched no elements |
+| `ERR_NAVIGATION_TIMEOUT` | Yes | Page did not load within timeout |
+| `ERR_BROWSER_DISCONNECTED` | Yes | Browser process unreachable |
+| `ERR_BROWSER_CRASHED` | Yes | Browser terminated unexpectedly |
+| `ERR_PUPPETEER_MISSING` | No | Puppeteer npm package not installed |
+| `ERR_SCRIPT_FAILED` | Yes | JavaScript execution threw error |
+| `ERR_WRITE_FAILED` | Yes | Screenshot/file write failed |
+| `ERR_INVALID_SELECTOR` | No | CSS selector syntactically invalid |
+| `ERR_SESSION_CORRUPTED` | Yes | Session file is invalid JSON |
+
+**Zero internal retries.** Scripts execute once and return JSON. Callers own retry logic.
+
+---
+
+## Troubleshooting
+
+| Problem | Cause | Resolution |
+|---------|-------|------------|
+| `Cannot find puppeteer` | Not installed | `npm install puppeteer sharp yargs` |
+| `libnss3.so` missing | Linux deps | Run `./install-deps.sh` |
+| Element not found | Wrong selector | Use `aria-snapshot.ts` to find correct selector |
+| Screenshot > 5MB | High DPI / full page | Auto-compressed; use `--max-size 3` for smaller |
+| Session stale | Browser died | Delete `.browser-session.json`, re-launch |
+| Script hangs | Page never loads | Increase `--timeout` or check URL |
+
+
+## 📑 Content Map
+
+| File | Description | When to Read |
+|------|-------------|--------------|
+| [scripts-guide.md](rules/scripts-guide.md) | Complete script reference with all options | Detailed script usage |
+| [aria-snapshot.md](rules/aria-snapshot.md) | ARIA tree format and usage | Element discovery |
+| [scripts/](scripts/) | Puppeteer CLI scripts | Script execution |
+| [engineering-spec.md](rules/engineering-spec.md) | Full engineering spec: contracts, security, scalability | Architecture review |
+
+---
+
+## 🔗 Related
+
+| Item | Type | Purpose |
+|------|------|---------|
+| `agent-browser` | Skill | AI-optimized browser automation with @ref handles |
+| `e2e-automation` | Skill | Playwright E2E testing |
+| `perf-optimizer` | Skill | Performance analysis and recommendations |
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/chrome-devtools/rules/_sections.md

@@ -0,0 +1,25 @@
+# Sections
+
+This file defines all sections, their ordering, impact levels, and descriptions.
+The section ID (in parentheses) is the filename prefix used to group rules.
+
+---
+
+## 1. Aria (aria)
+
+**Impact:** LOW  
+**Description:** Aria patterns and best practices.
+
+## 2. Engineering Specification (engineering)
+
+**Impact:** MEDIUM  
+**Description:** Full engineering specification covering contracts, security, and scalability.
+
+## 3. Scripts (scripts)
+
+**Impact:** LOW  
+**Description:** Scripts patterns and best practices.
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/chrome-devtools/rules/_template.md

@@ -0,0 +1,32 @@
+---
+title: Rule Title Here
+impact: MEDIUM
+impactDescription: Optional description of impact (e.g., "20-50% improvement")
+tags: tag1, tag2
+---
+
+## Rule Title Here
+
+**Impact: MEDIUM (optional impact description)**
+
+Brief explanation of the rule and why it matters. This should be clear and concise, explaining the performance implications.
+
+**Incorrect (description of what's wrong):**
+
+```typescript
+// Bad code example here
+const bad = example()
+```
+
+**Correct (description of what's right):**
+
+```typescript
+// Good code example here
+const good = example()
+```
+
+Reference: [Link to documentation or resource](https://example.com)
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/chrome-devtools/rules/aria-snapshot.md

@@ -0,0 +1,95 @@
+---
+name: aria-snapshot
+description: YAML accessibility tree format with ref handles for element interaction
+title: "ARIA Snapshot Format"
+impact: MEDIUM
+impactDescription: "Moderate improvement to quality or maintainability"
+tags: aria, snapshot
+---
+
+# ARIA Snapshot Format
+
+> YAML accessibility tree with refs for interaction.
+
+---
+
+## Format
+
+```yaml
+- banner:
+  - link "Hacker News" [ref=e1]
+    /url: https://news.ycombinator.com
+  - navigation:
+    - link "new" [ref=e2]
+    - link "past" [ref=e3]
+- main:
+  - list:
+    - listitem:
+      - link "Show HN: My project" [ref=e8]
+      - text: "128 points by user 3 hours ago"
+- contentinfo:
+  - link "Guidelines" [ref=e20]
+```
+
+---
+
+## Notation
+
+| Notation | Meaning |
+|----------|---------|
+| `[ref=eN]` | Stable ID for interaction |
+| `[checked]` | Checkbox/radio selected |
+| `[disabled]` | Element inactive |
+| `[expanded]` | Accordion/dropdown open |
+| `/url:` | Link destination |
+| `/placeholder:` | Input placeholder |
+| `[level=N]` | Heading level |
+
+---
+
+## Roles
+
+| Role | Element |
+|------|---------|
+| `banner` | Header |
+| `navigation` | Nav menu |
+| `main` | Main content |
+| `contentinfo` | Footer |
+| `link` | Anchor |
+| `button` | Button |
+| `textbox` | Input |
+| `checkbox` | Checkbox |
+| `listitem` | List item |
+| `heading` | H1-H6 |
+
+---
+
+## Interact by Ref
+
+```bash
+# Click
+node select-ref.ts --ref e1 --action click
+
+# Fill
+node select-ref.ts --ref e5 --action fill --value "text"
+
+# Get text
+node select-ref.ts --ref e8 --action text
+
+# Screenshot
+node select-ref.ts --ref e1 --action screenshot --output ./element.png
+```
+
+---
+
+## 🔗 Related
+
+| File | When to Read |
+|------|-------------|
+| [scripts-guide.md](scripts-guide.md) | All script options and examples |
+| [engineering-spec.md](engineering-spec.md) | Full contracts and architecture |
+| [SKILL.md](../SKILL.md) | Quick reference and error taxonomy |
+
+---
+
+⚡ PikaKit v3.9.134