skills/docs/worklogs/2026-01-21-add-review-skills.md

---
title: "Worker RPC, Web Skills Expansion, and Compatibility Audit"
date: 2026-01-21
keywords: [hq, worker-cli, brave-search, browser-tools, skills-audit]
commits: 0
compression_status: uncompressed
---

# Session Summary

**Date:** 2026-01-21 (Day 1 of project)
**Focus Area:** Worker RPC orchestration, portable web skills, and cross-agent skill compatibility

# Accomplishments

- [x] Implemented `skills/hq/scripts/worker-rpc.py` and a simulation harness to validate RPC event handling.
- [x] Added portable `brave-search` skill with auto-loading of `/run/secrets/api_keys/brave`.
- [x] Ported `browser-tools` skill (CDP-based Chrome automation) distinct from Playwright.
- [x] Created `handoff` skill to generate portable Markdown summaries across agents.
- [x] Produced `docs/skill-compatibility.md` (top 10 skills audit).
- [x] Drafted `specs/worker-message-bus.md` design spec for messaging + tmux observability.
- [x] Updated flake skill registry and API key exports (BRAVE/KAGI).

# Key Decisions

## Decision 1: Focus on skills (not pi extensions)

- **Context:** pi extensions are powerful but Pi-only; we need skills that work across Claude, Codex, Gemini, and OpenCode.
- **Options considered:**
  1. Port pi extensions directly (TS)
  2. Use portable skills + CLI tools
- **Rationale:** Cross-agent portability wins; skills are the shared layer.
- **Impact:** Future work (loop mode, oracle, etc.) will be implemented as skills or CLI utilities, not TS.

## Decision 2: Brave search as web fallback

- **Context:** Claude web tools may be unavailable or out of credits.
- **Options considered:**
  1. Keep Claude-only web skills
  2. Add Brave API-based search
  3. Add Kagi only
- **Rationale:** Brave offers raw search results with minimal dependencies.
- **Impact:** `brave-search` added; `web-research` now documents fallback strategy.

# Problems & Solutions

| Problem | Solution | Learning |
|---------|----------|----------|
| `brave-search` failed when `BRAVE_API_KEY` missing | Added fallback to `/run/secrets/api_keys/brave` in script | Prefer sops-backed defaults for skills |
| `brave-search` not deployable via flake | Added skill to `skills.nix` and updated `flake.nix` API key exports | Flake registry must be kept in sync with skills/ |
| Browser automation needs visible Chrome (not Playwright) | Ported `browser-tools` from pi-skills | CDP + profile copy covers authenticated workflows |

# Technical Details

## Code Changes

- Total files modified: 21
- Key files changed:
  - `skills/hq/SKILL.md` - RPC event mapping + WIP limit
  - `skills/brave-search/scripts/search.js` - API key fallback
  - `skills/browser-tools/scripts/browser-*.js` - CDP automation suite
  - `skills.nix` / `flake.nix` - skill registry + API key exports
  - `docs/skill-compatibility.md` - audit matrix
- New files created:
  - `skills/brave-search/` (SKILL, README, scripts, package.json)
  - `skills/browser-tools/` (SKILL, README, scripts, package.json)
  - `skills/handoff/` (SKILL, README, scripts)
  - `specs/worker-message-bus.md`
- Files deleted:
  - None

## Commands Used

```bash
# Install brave-search deps and test
cd skills/brave-search
npm install
node scripts/search.js "nix flakes" -n 1

# Skill deployment test
nix build ~/proj/skills#brave-search

# Worklog metrics + filename
skills/worklog/scripts/extract-metrics.sh
skills/worklog/scripts/suggest-filename.sh
```

## Architecture Notes

- The worker CLI already contains a schema-ready SQLite message bus; only CLI commands are missing.
- `browser-tools` complements `playwright-visit` by enabling authenticated and interactive sessions.
- Skill install is mediated by `.skills` manifests and `use-skills.sh` with Nix builds.

# Process and Workflow

## What Worked Well

- Reusing pi-skills implementations for Brave and browser CDP tools reduced risk.
- Rooting in skills rather than TS extensions kept portability high.
- Early audit (`docs/skill-compatibility.md`) made gaps visible.

## What Was Challenging

- Synchronizing flake registry with new skills.
- Navigating multiple agent ecosystems (pi vs Claude vs OpenCode).
- Deciding how to represent runtime orchestration across tools.

# Learning and Insights

## Technical Insights

- Pi skills are separate from pi-mono; extensions are Pi-only.
- Brave search provides low-latency, API-driven results without browser overhead.
- The worker bus schema is already adequate for structured inter-agent comms.

## Process Insights

- Keeping skills portable (bash + node + python) is the best compatibility strategy.
- Central registry (`skills.nix`) is the single point of failure for deployability.

## Architectural Insights

- Messaging and observability should be CLI-driven, not skill-driven.
- Review workflows (code-review, ops-review, spec-review) are portable but require a heavy toolchain.

# Context for Future Work

## Open Questions

- Should `browser-tools` be added to `.skills` by default or remain opt-in?
- How to structure log retention and pruning for worker message bus?
- Do we need a standardized JSON schema for worker messages in v1?

## Next Steps

- Implement `worker msg` CLI commands per `specs/worker-message-bus.md`.
- Add `worker watch` tmux integration.
- Expand skill compatibility audit beyond the top 10.
- Update dotfiles system packages (Chromium + Node) via `dotfiles-scvr`.

## Related Work

- `docs/worklogs/2026-01-21-worker-rpc-web-skills-audit.md`
- `docs/worklogs/2026-01-13-hq-deployment-codex-skills-integration.md`
- `docs/worklogs/2026-01-11-worker-cli-cleanup-refactors.org`
- `specs/worker-message-bus.md`
- Beads: `skills-29bp`, `skills-imei`, `skills-s5xl`, `skills-wxbs`, `skills-telx`, `dotfiles-scvr`

# Raw Notes

- Brave search default should not rely on Claude credits.
- Pi extensions stay in dotfiles; skills remain in this repo.
- `browser-tools` uses CDP with Chrome `:9222`, suitable for authenticated testing.

# Session Metrics

- Commits made: 0
- Files touched: 21
- Lines added/removed: +682/-20
- Tests added: 0
- Tests passing: 0/0