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

title	date	keywords	commits	compression_status
Worker RPC, Web Skills Expansion, and Compatibility Audit	2026-01-21	hq worker-cli brave-search browser-tools skills-audit	0	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

• Implemented skills/hq/scripts/worker-rpc.py and a simulation harness to validate RPC event handling.
• Added portable brave-search skill with auto-loading of /run/secrets/api_keys/brave.
• Ported browser-tools skill (CDP-based Chrome automation) distinct from Playwright.
• Created handoff skill to generate portable Markdown summaries across agents.
• Produced docs/skill-compatibility.md (top 10 skills audit).
• Drafted specs/worker-message-bus.md design spec for messaging + tmux observability.
• 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

# 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