diegosouzapw/awesome-omni-skill / skills/ai-agents/agent-browser-upstream
agent-browser-upstream
VerifiedSafely sync navigator's agent-browser fork with upstream vercel-labs/agent-browser, analyze changes, and generate integration documentation
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 13.2 KB |
| metadata.json | config | 1.4 KB |
SKILL.md
View on GitHub---
name: agent-browser-upstream
description: Safely sync navigator's agent-browser fork with upstream vercel-labs/agent-browser, analyze changes, and generate integration documentation
triggers:
- upstream
- agent-browser update
- sync fork
- integration plan
- update agent-browser
- merge upstream
archetype: dev-workflow
user_invocable: false
---
# Agent-Browser Upstream Sync Skill
Manages the process of keeping navigator's agent-browser fork in sync with the upstream vercel-labs/agent-browser repository.
## Related Skills
| Skill | Purpose |
|-------|---------|
| **[upstream-evaluation](../upstream-evaluation/SKILL.md)** | Decision frameworks for what to adopt/skip/adapt |
| **[docs/architecture/DESIGN.md](../../../docs/architecture/DESIGN.md)** | Navigator's design philosophy and conventions |
**Workflow**: Use `upstream-evaluation` skill for the "what and why" decisions, then return here for the "how" execution.
## Prerequisites
**None required** - the skill auto-manages everything:
1. **Auto-clone**: If `.agent-browser/repo/` doesn't exist, the script clones the fork automatically
2. **Auto-configure**: Upstream remote is added if missing
3. **Override**: Set `AGENT_BROWSER_LOCAL` env var to use an existing local clone instead
The `.agent-browser/` directory is gitignored and contains:
- `repo/` — Git clone of the fork
- `analysis/<sha>/` — Generated artifacts (jq-able JSON, diffs)
## Workflow Overview
```
Phase 1: Check Status (fetch, compare)
↓
Phase 2: Analyze Changes (categorize commits)
↓
Phase 3: Evaluate Changes ← uses upstream-evaluation skill
↓
Phase 4: Write Integration Docs + Create Issue
↓
Phase 5: User Review & Confirmation
↓
Phase 6: Execute Merge (ONLY after user confirms)
```
> **CRITICAL**: Never merge without completing phases 3-5 first.
> Phase 3 MUST use the `upstream-evaluation` skill to apply Navigator's design frameworks.
---
## Phase 1: Sync Fork
### Steps
1. **Run the analysis script** (handles everything automatically)
```bash
bun run .claude/skills/agent-browser-upstream/scripts/analyze-upstream.ts --format summary
```
The script will:
- Clone `.agent-browser/` if missing
- Add upstream remote if needed
- Fetch latest from both remotes
- Show divergence summary
2. **Or check manually**
```bash
cd .agent-browser/repo
# Current fork version
git describe --tags origin/main 2>/dev/null || git rev-parse --short origin/main
# Latest upstream version
git describe --tags upstream/main 2>/dev/null || git rev-parse --short upstream/main
# Divergence
git log --oneline origin/main..upstream/main
```
### Decision Point
If no commits in divergence → **STOP** with "Fork is up to date with upstream"
If commits exist → **CONTINUE** to Phase 2 (never skip to merge)
---
## Phase 2: Analyze Changes
### Steps
1. **Run analysis script**
```bash
bun run .claude/skills/agent-browser-upstream/scripts/analyze-upstream.ts \
--repo "$REPO_PATH" \
--base origin/main \
--target upstream/main
```
2. **Review commit categories**
The script outputs JSON with commits categorized as:
- `breaking` - API changes, removed exports
- `additive` - New features, new exports
- `fix` - Bug fixes
- `docs` - Documentation only
- `chore` - Build, deps, tooling
3. **Identify key files changed**
Focus on these files for navigator impact:
- `src/protocol.ts` - MCP protocol definitions
- `src/browser.ts` - Browser control API
- `src/index.ts` - Public exports
- `src/cli/` - CLI commands (may inform navigator CLI)
### Output
Present a summary table:
| Category | Count | Key Changes |
|----------|-------|-------------|
| Breaking | N | List significant ones |
| Additive | N | List new features |
| Fix | N | List relevant fixes |
---
## Phase 3: Evaluate Changes
**REQUIRED** — Even for "clean" updates with 0 breaking changes.
### Run the Evaluation Command
Use `/agent-browser:integrate-changes`, which:
- Loads the **upstream-evaluation** skill
- Provides decision frameworks from DESIGN.md
- Guides through structured evaluation process
- Outputs adopt/skip/defer tables for integration docs
### Why This Phase Exists
The 2025-01-20 v0.6.0 sync skipped evaluation because "0 breaking changes" was treated as a green light. This caused:
- Marketplace plugin merged without review (Vercel-branded, not navigator-appropriate)
- 8 new features not assessed for navigator integration
- No documentation created before merge
### Evaluation Output
The `upstream-evaluation` skill produces:
- **Adopt** table: Features to add with Navigator naming and schema changes
- **Skip** table: Features to exclude with rationale
- **Defer** table: Features to revisit later
- **Extend existing** table: Changes to existing actions
2. **Review evaluation output**
- Ensure all new commands identified
- Ensure plugins flagged
- Ensure schema changes documented
3. **Do NOT proceed to merge** until analyst complete
---
## Phase 4: Impact Assessment (Navigator-Specific)
### Steps
1. **Map upstream changes to navigator usage**
Check which navigator files import from agent-browser:
```bash
grep -r "@outfitter/agent-browser" packages/*/src --include="*.ts" -l
```
2. **Cross-reference with changed APIs**
For each breaking change, check if navigator uses it:
```bash
# Example: if upstream changed BrowserOptions
grep -r "BrowserOptions" packages/*/src --include="*.ts"
```
3. **Flag breaking changes**
Create a list:
- [ ] Change X affects `packages/server/src/browser.ts:42`
- [ ] Change Y affects `packages/core/src/types.ts:18`
4. **Identify required navigator changes**
For each breaking change, document:
- What changed upstream
- How navigator currently uses it
- What navigator code needs to change
### Decision Point
If breaking changes exist → **STOP** and confirm with user before proceeding
---
## Phase 5: Write Integration Docs
### Steps
1. **Determine version**
```bash
VERSION=$(git describe --tags upstream/main 2>/dev/null || echo "v$(date +%Y.%m.%d)")
```
2. **Create version directory**
```bash
mkdir -p docs/_upstream/$VERSION
```
3. **Generate changes.md**
Raw changelog with all commits and diffs.
4. **Generate integration.md**
Use template from `references/integration-template.md`:
- Version metadata
- Breaking changes with navigator impact
- Additive features with adoption plan
- Required code changes
- Test plan
5. **Generate status.md**
Tracking checklist:
```markdown
## Implementation Status
- [ ] Merge upstream into fork
- [ ] Update navigator bun.lock
- [ ] Apply breaking change fixes
- [ ] Run navigator tests
- [ ] Update navigator CHANGELOG
```
6. **Update index**
Add entry to `docs/_upstream/README.md`
7. **Create GitHub issue** (optional, recommended for breaking changes)
The integration doc *is* the issue — its frontmatter has title/labels:
```bash
bun run .claude/skills/agent-browser-upstream/scripts/create-issue.ts \
docs/_upstream/$VERSION/integration.md
```
Or use the command: `/agent-browser:issue docs/_upstream/$VERSION/integration.md`
---
## Phase 6: Execute Merge
> **REQUIRES USER CONFIRMATION** - Do not proceed without explicit approval from Phase 5 docs review
### Steps
1. **Merge upstream into fork**
```bash
cd /path/to/navigator/.agent-browser/repo # Always use absolute path
git checkout main
git merge upstream/main --no-edit
```
2. **Resolve conflicts if any**
- Prefer upstream changes unless navigator-specific customization
- Document any conflict resolutions in integration.md
3. **Push to fork**
```bash
git push origin main
```
4. **Create fork release tag**
```bash
# Determine tag version: <upstream-version>-nav.<patch>
# e.g., v0.6.0-nav.1, v0.6.0-nav.2
VERSION="v0.6.0-nav.1" # Adjust based on upstream version
git tag -a "$VERSION" -m "Navigator fork release: synced with upstream
Upstream: vercel-labs/agent-browser <upstream-tag>
Navigator tracking: <issue-url>"
git push origin "$VERSION"
```
5. **Update navigator's package.json**
```bash
cd /path/to/navigator # Back to navigator root
# Update packages/server/package.json to reference the tag:
# "@outfitter/agent-browser": "github:outfitter-dev/agent-browser#v0.6.0-nav.1"
```
6. **Force refresh bun lockfile** (required for GitHub deps)
```bash
cd /path/to/navigator
rm bun.lock
bun install
```
> **Why?** Bun caches GitHub commit SHAs. Without removing the lockfile,
> `bun install` may not fetch the new tag even after pushing.
7. **Verify lockfile updated**
```bash
grep "agent-browser" bun.lock
# Should show the new tag: #v0.6.0-nav.1
```
8. **Run navigator tests**
```bash
bun run typecheck
bun test
```
9. **Update integration docs**
- Mark fork synced in `docs/_upstream/<version>/integration.md`
- Add tag version to the doc
### Decision Point
If tests fail → **STOP** and document failures, do not commit
---
## Fork Tagging Convention
The fork uses `<upstream-version>-nav.<patch>` tags:
| Tag | Meaning |
|-----|---------|
| `v0.6.0-nav.1` | First navigator release based on upstream v0.6.0 |
| `v0.6.0-nav.2` | Second navigator release (e.g., hotfix to fork) |
| `v0.7.0-nav.1` | First navigator release based on upstream v0.7.0 |
Benefits:
- Clear upstream version lineage
- Navigator can branch and test new versions before merging to main
- Pinnable in package.json: `github:outfitter-dev/agent-browser#v0.6.0-nav.1`
---
## Integration Patterns
### Pattern: API Signature Change
When upstream changes a function signature:
1. Find all navigator usages
2. Update to new signature
3. Add backward-compat wrapper if needed (temporary)
4. Document in integration.md
### Pattern: New Feature Adoption
When upstream adds a useful feature:
1. Evaluate if navigator should expose it
2. Add to navigator's schema if needed
3. Wire through action-executor
4. Add tests
5. Document in navigator CHANGELOG
### Pattern: Breaking Type Change
When upstream changes a type definition:
1. Update navigator's re-exports
2. Check all type usages compile
3. Update any Zod schemas that reference it
---
## Quick Reference
### Commands
```bash
# Run analysis (auto-clones if needed)
bun run .claude/skills/agent-browser-upstream/scripts/analyze-upstream.ts --format summary
# Generate diff artifacts (for incremental context loading)
bun run .claude/skills/agent-browser-upstream/scripts/generate-diff.ts
# Check current versions
cd .agent-browser/repo && git describe --tags origin/main upstream/main
# View pending changes
cd .agent-browser/repo && git log --oneline origin/main..upstream/main
# Diff specific file
cd .agent-browser/repo && git diff origin/main..upstream/main -- src/protocol.ts
# Read analysis artifacts incrementally
cat .agent-browser/analysis/<sha>/summary.json # Start here
jq '.counts' .agent-browser/analysis/<sha>/summary.json
cat .agent-browser/analysis/<sha>/by-category/breaking.json
```
### Key Files
| Location | Purpose |
|----------|---------|
| `.agent-browser/repo/` | Local clone of the fork (gitignored) |
| `.agent-browser/analysis/<sha>/` | Generated artifacts for specific upstream SHA |
| `docs/_upstream/README.md` | Index of all integration docs |
| `docs/_upstream/<version>/integration.md` | Version-specific integration plan |
| `references/integration-template.md` | Template for integration docs (also the issue) |
| `scripts/generate-diff.ts` | Generates jq-able artifacts for agents |
| `scripts/analyze-upstream.ts` | Analyzes commits between refs |
| `scripts/create-issue.ts` | Creates GitHub issue from integration doc |
### Environment Variables
| Variable | Purpose | Default |
|----------|---------|---------|
| `AGENT_BROWSER_LOCAL` | Override repo path | `.agent-browser/repo/` in navigator root |
---
## Troubleshooting
### Bun Lockfile Not Updating
**Symptom:** After pushing new tag to fork, `bun install` still shows old commit SHA.
**Cause:** Bun caches GitHub dependencies by commit SHA. Even with a new tag, it may reuse the cached resolution.
**Fix:**
```bash
cd /path/to/navigator
rm bun.lock
bun install
grep "agent-browser" bun.lock # Verify new tag/commit
```
### Git Context Issues
**Symptom:** `gh` commands target wrong repo (e.g., upstream instead of navigator).
**Cause:** Working directory is `.agent-browser/repo/` (the fork clone) instead of navigator root.
**Fix:** Always use absolute paths:
```bash
# WRONG - relative path, may be in wrong directory
cd .agent-browser/repo && git push
# RIGHT - absolute path
cd /Users/you/project/navigator/.agent-browser/repo && git push
# For navigator commands, go back to root
cd /Users/you/project/navigator && gh issue create
```
### Tag Already Exists
**Symptom:** `git tag` fails with "tag already exists".
**Fix:** Increment the patch number:
```bash
# If v0.6.0-nav.1 exists, use v0.6.0-nav.2
git tag -a "v0.6.0-nav.2" -m "..."
```
### Fork Behind After Merge
**Symptom:** `git log origin/main..upstream/main` still shows commits after merge.
**Cause:** Origin wasn't pushed.
**Fix:**
```bash
cd .agent-browser/repo
git push origin main
git log --oneline origin/main..upstream/main # Should be empty
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 198k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |