This skill should be used when the user asks to design or run OpenDevBrowser provider workflows, scraping pipelines, QA/debug automation, parity checks across modes, or resilient browser operations with codified scripts and artifacts.
This skill should be used when the user asks to design or run OpenDevBrowser provider workflows, scraping pipelines, QA/debug automation, parity checks across modes, or resilient browser operations with codified scripts and artifacts.
version
2.6.0
OpenDevBrowser Best Practices
This is the primary battery pack for OpenDevBrowser operations.
diagnostics for QA/debug (console, network, trace context),
safe write flows with explicit policy notice.
For frontend, design-system, screenshot-to-code, or /canvas composition tasks, load opendevbrowser-design-agent immediately after this pack so the work is design-contract-first instead of operations-only.
Routine artifact-bearing workflow runs should omit --output-dir; inspect the returned artifact_path first, then .opendevbrowser/<namespace>/<runId> for research, shopping, inspiredesign, or product-video artifacts before publishing claims. If a wrapper requires an explicit workflow root, use --output-dir .opendevbrowser; the runtime appends <namespace>/<runId>. Browser evidence omitted outputs use .opendevbrowser/screenshot/<uuid>/capture.png for screenshots and .opendevbrowser/screencast/<uuid> for browser replay, while explicit caller paths remain caller-controlled.
Public-first YouTube transcript retrieval.
node scripts/youtube-transcript-live-probe.mjs --url "https://www.youtube.com/watch?v=aircAruvnKk" --youtube-mode auto --out artifacts/capability-fix/youtube-transcript-auto.json
Rules:
keep transcript runs public-first
browser-assisted transcript fallback is opt-in only
if browser fallback is enabled, use an isolated automation profile instead of a daily logged-in Google profile
Evidence-gated research primitive with explicit public source families.
npx opendevbrowser research run --topic "Chrome extension debugging workflows" --days 30 --sources web,community --browser-mode managed --mode json --output-format json
Rules:
load opendevbrowser-research before research tasks so planning, evidence review, confidence, and limitations stay skill-guided
treat research run as provider-constrained and low-level; inspect summary.md, report.md, records.json, context.json, meta.json, and bundle-manifest.json before publishing claims
use --source-selection only to explain selector semantics; use explicit --sources web,community for public topical examples
add shopping only with --source-selection shopping or explicit --sources ...shopping... when the task is deliberately commercial
--source-selection auto resolves to public-first web,community; use all, social, or explicit social sources only when social evidence is intentional
Deterministic shopping reruns with explicit providers.
use explicit providers plus --browser-mode managed for the most reproducible reruns
inspect buyingReadiness.status; transport success and emitted offers are not enough for buying guidance when readiness is partial or fail
treat --region as advisory unless meta.selection.region_authoritative=true
inspect meta.primaryConstraintSummary first on no-offer runs
if meta.primaryConstraint.guidance is present, follow meta.primaryConstraint.guidance.reason and meta.primaryConstraint.guidance.recommendedNextCommands[]
if guidance is absent, inspect meta.offerFilterDiagnostics before calling a no-offer run a provider outage
Design-contract synthesis with repeated public references.
keep inspiredesign references public-first; explicit-url inspiredesign run --url ... uses deep capture for DOM/layout evidence, while Pinterest harvest/recovery commands keep captureMode=off for byte-backed pin-media extraction; --visual-evidence required controls screenshot evidence when the selected strategy explicitly calls for screenshots and does not enable deep capture for canonical pin-media harvest
use repeated --url flags instead of packed URL strings
provide --query or at least one --url for inspiredesign harvest; use --query when provider discovery is part of the task
use inspiredesign harvest when visual reference discovery, screenshot PNG artifacts, ranked references, metadata-only visual JSON, deterministic media-analysis.json, meta-prompt.md, or motion-design follow-through is required
treat social/pinterest as a browser-native site recipe, not a default full social provider; default Pinterest harvest applies extension auth only when extensionAuthReady is current and the caller has not set incompatible auth transport or cookie settings; explicit browserMode, profile, useCookies, cookiePolicyOverride, or challengeAutomationMode values other than browser_with_helper opt out, while explicit challengeAutomationMode=browser_with_helper is compatible and may merge with the implicit extension, cookies, and required cookie policy defaults; for managed recovery, use a dedicated headed profile with --profile <name>, cookies, and --cookie-policy required; use registry-backed explicit CDP profiles through cdp-profile start plus connect --profile for browser/session primitives until provider workflows expose an explicit-CDP transport selector
for multi-pin Pinterest design harvests, run query discovery with --query ... --provider social/pinterest and trust the broad-query harvest only when query-discovered canonical https://www.pinterest.com/pin/<id>/ URLs become ranked references with manifest-backed first-party pin-media bytes in the same bundle; omitted --output-dir runs return artifact_path, so inspect that path before assuming .opendevbrowser/inspiredesign/<runId>; if the query bundle remains diagnostic-only, read and , keep only canonical pin URLs, then use one canonical recovery harvest per selected pin with omitted
Agent Sync Targets
Skill-pack installation and discovery are synchronized for:
Install and update refresh managed copies of these canonical packs, adopt matching markerless canonical copies only when repairing or promoting a managed OpenDevBrowser target, and preserve drifted markerless directories outside managed repair for user review. Uninstall removes marker- or sentinel-managed canonical packs and leaves unrelated directories untouched.
If a global npm install or update seems stale, compare command -v opendevbrowser, which -a opendevbrowser, and npm prefix -g; the active binary may live under a different prefix from npm's default global prefix.
Required Operating Rules
Prefer refs from opendevbrowser_snapshot over raw selectors.
Use one action per decision loop: snapshot -> action -> snapshot.
Keep a single correlation context (requestId, sessionId) across a run.
Before daemon-backed workflows, run opendevbrowser status --daemon --output-format json and require data.fingerprintCurrent === true.
For extension readiness, require data.fingerprintCurrent === true, data.relay.extensionConnected === true, and data.relay.extensionHandshakeComplete === true.
For user-owned Google OAuth continuity, use --google-auth-intent user-owned with extension /ops: opendevbrowser launch --google-auth-intent user-owned --extension-only --wait-for-extension --output-format json.
Treat --google-auth-intent user-owned as fail-closed for --no-extension, --headless, --extension-legacy, and direct CDP.
Managed and direct cdpConnect use best-effort readable system Chrome-family cookie bootstrap, but copied cookies are not Google auth proof; add --disable-system-cookie-bootstrap when investigating perceived logout or auth invalidation.
Google-sensitive cookies are skipped by default during managed and direct cdpConnect bootstrap; use --allow-google-cookie-bootstrap only for diagnostic runs that explicitly accept that risk.
Inspect sanitized diagnostics.authProvenance for mode and cookie-bootstrap provenance. Do not record private cookies, tokens, account identifiers, full profile paths, or account screenshots.
After Google sign-in or account chooser actions, recover the OAuth popup with targets-list --include-urls, then target-use --target-id <target-id>.
Treat data.relay.opsConnected, data.relay.canvasConnected, and data.relay.cdpConnected as diagnostic or lane-specific presence fields; data.relay.cdpConnected is active-legacy-session-only.
Treat missing or false data.fingerprintCurrent as not current; use the matching binary, restart from the current install, or isolate shared runs with OPENCODE_CONFIG_DIR, OPENCODE_CACHE_DIR, and unique daemon or relay ports.
Parallel Operations (Reliable As-Is)
Safe parallelism today is session-per-worker (one session per page/tab command stream).
Keep each session single-writer for target/page actions; run commands serially inside that session.
Do not run independent concurrent streams that alternate target-use within one session.
Use default extension /ops for relay-backed concurrency; use /cdp only for legacy compatibility paths.
For managed parallel runs with persisted profiles, use unique profile paths per session (or disable persistence) to avoid profile lock collisions.
Treat extension headless attempts (--extension-only --headless) as expected unsupported_mode; route headless workloads through managed/cdpConnect instead.
Do not route user-owned Google OAuth continuity through managed/cdpConnect. Use extension /ops or stop and ask for a non-Google test account/profile.
Before extension-mode runs, preflight npx opendevbrowser status --daemon --output-format json and require data.fingerprintCurrent === true, data.relay.extensionConnected === true, and data.relay.extensionHandshakeComplete === true; do not require data.relay.opsConnected, data.relay.canvasConnected, or data.relay.cdpConnected unless that lane is actively in use.
Operational references:
artifacts/provider-workflows.md (see Workflow E)
scripts/odb-workflow.sh parallel-multipage-safe
docs/CLI.md (concurrency semantics)
docs/SURFACE_REFERENCE.md (transport and policy constraints)
docs/TROUBLESHOOTING.md (parallel crosstalk and profile-lock remediation)
QA replay debug evidence lane exception: use browser replay when timing matters:
opendevbrowser_screencast_start sessionId="<session-id>" outputDir="./artifacts/qa-replay"
# run the suspect flow
opendevbrowser_screencast_stop sessionId="<session-id>" screencastId="<screencast-id>"
Read-Only Social Validation Workflow
Goal: validate authenticated read/search capability without posting.
Choose the least-privileged session mode that matches the auth need. For non-Google social validation, prefer a dedicated managed headed profile or registry-backed explicit CDP profile; require data.fingerprintCurrent === true from JSON daemon status before running.
Require extension readiness (data.relay.extensionConnected === true and data.relay.extensionHandshakeComplete === true) only when the workflow explicitly uses extension /ops, needs live active-tab reuse, or depends on user-owned Google OAuth continuity.
Navigate/search target social surface.
Capture debug-trace-snapshot and network-poll evidence.
Record blocker/auth status only (no write action), and do not treat copied cookies, raw --profile, or raw CDP attach as login proof.
Treat tests/parity-matrix.test.ts as contract coverage only. Live release proof comes from the direct-run harnesses below.
This pack is the canonical owner of direct-run release evidence policy; other docs and skill packs should point here instead of restating the full policy.
docs/SURFACE_REFERENCE.md (78 CLI commands, 70 tools, 59 /ops commands, 41 /canvas commands, 67 CLI-tool pairs, /cdp envelope contracts; mirrored by npx opendevbrowser --help and npx opendevbrowser help). These hardcoded counts are validator-covered and must be refreshed from generated public-surface truth whenever counts change.
artifacts/skill-runtime-surface-matrix.md and assets/templates/skill-runtime-pack-matrix.json (canonical pack/runtime audit inventory)
Direct-run release note:
scripts/live-regression-direct.mjs is the preferred release harness for /canvas, annotate, and CLI smoke. It uses temporary managed profiles for managed probes, waits for /ops drain before the legacy /cdp step, and keeps manual annotation timeouts as explicit skipped boundaries in --release-gate mode.
scripts/provider-direct-runs.mjs --include-high-friction --include-auth-gated is the preferred provider release harness. Treat provider-live-matrix and live-regression-matrix as debug-only helpers, not refreshed release evidence.
Explicit artifacts/release/vX.Y.Z/... paths are local-only release proof outputs. For normal omitted workflow outputs, inspect the returned artifact_path first; the persisted bundle is under .opendevbrowser/<namespace>/<runId>.
Skill Runtime Audit and Realignment
This pack is the canonical owner of repo-local skill runtime audit policy and skill-pack runtime realignment.
Use these assets when the task is to inventory or validate the full OpenDevBrowser skill/runtime surface:
artifacts/skill-runtime-surface-matrix.md
assets/templates/skill-runtime-pack-matrix.json
scripts/skill-runtime-audit.mjs
Audit runtime rule:
scripts/skill-runtime-audit.mjs keeps smoke mode isolated and reproducible with temp harnesses, but full mode must reuse the current configured daemon and environment for provider-direct and live-regression so extension state, cookies, and auth-backed scenarios are exercised for real when available.
Realignment rule:
when a pack drifts behind current runtime behavior, update the skill to match the repo reality and strengthen the workflow guidance instead of making the pack merely stop failing validation.
Canvas Governance Handshake
Use the design-canvas surface when the workflow needs persisted design documents, explicit governance state, preview tabs, or overlay selection.
Recommended command order:
opendevbrowser_canvas or opendevbrowser canvas --command canvas.session.open --output-format json to get canvasSessionId, leaseId, preflightState, planStatus, governance block states, generation-plan requirements, and guidance.recommendedNextCommands.
Read the handshake before mutating. The handshake is the source of truth for:
planStatus
preflightState
governanceRequirements.requiredBeforeMutation
governanceRequirements.requiredBeforeSave
generationPlanRequirements.requiredBeforeMutation
generationPlanRequirements.allowedValues
generationPlanIssues
allowedLibraries
mutationPolicy.allowedBeforePlan
guidance.recommendedNextCommands
guidance.reason
guidance.nextStepGuidance, guidance.paramsExamples, guidance.fieldExamples, guidance.validationChecks, and guidance.doNotProceedIf when a repair envelope is present
treat allowedLibraries.components, allowedLibraries.icons, and allowedLibraries.styling as separate policy lanes:
components are reusable UI adapters such as shadcn,
icons are approved icon families,
styling is for utility/theme adapters such as tailwindcss
Require preflightState="handshake_read" or inspect the returned invalid-plan state before moving on. If the response already carries guidance.recommendedNextCommands, follow that list instead of guessing.
Submit canvas.plan.set --output-format json with all required non-empty objects:
targetOutcome
visualDirection
layoutStrategy
contentStrategy
componentStrategy
Code-sync surface:
canvas.session.attach joins an existing canvas session as an observer or reclaims the write lease with attachMode=lease_reclaim.
canvas.code.bind, canvas.code.unbind, canvas.code.pull, canvas.code.push, canvas.code.status, and canvas.code.resolve manage framework-adapter-backed document bindings when a canvas file is round-tripped to repo code.
Built-in code-sync lanes are builtin:react-tsx-v2, builtin:html-static-v1, builtin:custom-elements-v1, builtin:vue-sfc-v1, and builtin:svelte-sfc-v1; legacy tsx-react-v1 manifests migrate to builtin:react-tsx-v2 on load.
Bound source manifests live under .opendevbrowser/canvas/code-sync/<documentId>/<bindingId>.json, and workspace routes reject duplicate repo paths or duplicate binding ids before child mutation.
Preview/export projection defaults to canvas_html; bound_app_runtime is opt-in only when the binding requests it and runtime bridge preflight succeeds.
Current /canvas parity notes:
All 41 public canvas.* commands are agent-callable through opendevbrowser_canvas and opendevbrowser canvas --command ....
Use canvas.workspace.open, canvas.workspace.status, canvas.workspace.child.add, canvas.workspace.child.execute, canvas.workspace.child.close, and canvas.workspace.close for multi-child orchestration over existing child sessions. Workspaces store refs-only manifests under .opendevbrowser/canvas-workspace/<workspaceId>/workspace-manifest.json; child documents remain owned by their child sessions.
Route child mutations through canvas.workspace.child.execute only after checking the target child. Workspace guardrails reject duplicate child ids, sessions, leases, document ids, repo paths, code-sync binding ids, stale child routes, and nested workspace route attempts before dispatch.
Preview budget states are focused_live, pinned_live, background_live, thumbnail, paused, and degraded. Treat thumbnail, paused, and degraded as budget or recovery states, not proof of live bound-app parity.
canvas.feedback.subscribe live streaming is public through the CLI only: use --output-format stream-json for the built-in polling bridge.
Tool-driven agents can achieve the same public streaming behavior by calling canvas.feedback.subscribe, then repeating canvas.feedback.next, and finally canvas.feedback.unsubscribe.
canvas.tab.sync and canvas.overlay.sync are internal extension runtime helpers, not public commands.
canvas_html is still the default preview/export contract. bound_app_runtime is opt-in and only valid when runtime preflight, app-side instrumentation, and code-sync binding policy succeed.
Component and icon libraries currently render semantically, not package-faithfully. Treat shadcn, tailwindcss, tabler, microsoft-fluent-ui-system-icons, 3dicons, and @lobehub/fluent-emoji-3d as metadata and constrained render lanes, not as general library import/export parity.
Tailwind usage rule:
When allowedLibraries.styling includes tailwindcss, use it for layout, spacing, responsive, and state styling over canonical tokens/theme variables.
Do not treat Tailwind as a component inventory source or invent generation-plan allowlists for it; keep styling policy in allowedLibraries / libraryPolicy.
Preview/export should materialize a deterministic utility-class layer and stay self-contained; do not depend on a remote Tailwind CDN for canvas preview correctness.
Failure handling:
plan_required: immediately call canvas.plan.set.
generation_plan_invalid: resubmit canvas.plan.set with every required non-empty generation-plan block present, using generationPlanIssues plus details.missingFields and details.issues as the repair checklist.
revision_conflict: reload with canvas.document.load and replay the patch batch against the latest revision.
unsupported_target or restricted_url: move the preview to a normal http(s) tab or fall back to managed mode.
If a freshly rebuilt unpacked extension still shows old /canvas or popup behavior, reload the extension in Chrome before trusting the live result; stale MV3 runtime state can preserve old service-worker logic after npm run extension:build.
If workspace panes, drafts, selection, or previews look mixed after rebuild or reload, reload the unpacked extension, reconnect the relay, reopen the workspace, and inspect canvas.workspace.status before treating child isolation as broken.
Operational references:
artifacts/canvas-governance-playbook.md
assets/templates/canvas-handshake-example.json
assets/templates/canvas-generation-plan.v1.json
assets/templates/canvas-feedback-eval.json
assets/templates/canvas-blocker-checklist.json
Diagnostics and Traceability
Current diagnostics tools:
opendevbrowser_session_inspector (session-first summary with relay health, target state, trace proof, and next-action guidance)
discovery-diagnostics.json records accepted and rejected URL counts, blocker diagnostics, and recovery actions; login/challenge and search-shell diagnostics are recovery paths, not product-ready evidence, and login_or_challenge_state blocks Pinterest product authority
canonical Pinterest pin harvests and recovery paths use captureMode=off and open the exact canonical pin in the active managed or extension workflow session before byte-backed pin-media extraction, which is required for reliable GIF and video pin capture in live sessions
trust multi-pin Pinterest harvest outputs only when top-level ready=true, productSuccess=true, artifactAuthority=product_ready, evidenceAuthority=pin_media_ready, ranked-references.json is non-empty, and pin-media-index.json proves pin-media-first manifest-backed authority for the selected pin; snapshot_ready and motion_ready are not substitutes for canonical pin-media readiness, login_or_challenge_state blocks authority, unavailable supplemental viewport screenshot evidence is recorded as skipped and satisfied by pin media when authority is complete, media-analysis.json remains advisory, and motion-evidence.json remains browser replay authority
treat media-analysis.json as a deterministic design-fact surface from trusted saved pin media, not as readiness authority; pin-media-index.json remains the only pin-media readiness and provenance authority
use media-analysis.json for palette, tone, layout, OCR-free typography structure, text-region layout, sampled saved-media motion facts, motionSignature, limitations, and non-goals; do not claim readable text extraction, exact copy, font families, OCR, model vision, Tesseract, OpenCV, Sharp, browser canvas analysis, browser replay evidence, interaction choreography, new dependencies, or raw mediaAnalysis in canvas-plan.request.json
for richer media-analysis.json, prefer hosts with FFmpeg and FFprobe available; they are recommended optional host tools, are not bundled static binaries, and are not downloaded by default
before Pinterest video or GIF harvest work, run npx opendevbrowser status-capabilities --output-format json and inspect host.mediaAnalysis; media-analysis binaries resolve from OPENDEVBROWSER_FFMPEG_PATH and OPENDEVBROWSER_FFPROBE_PATH, then inspiredesign.mediaAnalysis.ffmpegPath and inspiredesign.mediaAnalysis.ffprobePath, then ffmpeg and ffprobe on PATH, then common absolute install directories for implicit PATH-source ENOENT misses only; invalid env or config paths stay diagnostic and do not fall back
for daemon-backed macOS runs, a current LaunchAgent includes EnvironmentVariables.PATH with common Homebrew, MacPorts, Nix, and system binary directories; if host.mediaAnalysis is unexpectedly missing tools, rerun opendevbrowser daemon install from a stable install so old LaunchAgents without the required PATH entries can be repaired
missing or invalid FFmpeg or FFprobe binaries degrade media-analysis.json only; they do not fail pin-media readiness, do not replace pin-media-index.json, and media-analysis.json never satisfies product readiness; empty motion-evidence.json means no authoritative browser replay screencast was captured, not that trusted saved GIF/video media was unanalyzed
inspect top-level ready, productSuccess, artifactAuthority, evidenceAuthority, manifest-backed evidence, plus nextStepGuidance.readiness, reasonCode, primaryAction, paramsExamples, validationChecks, and doNotProceedIf before continuing from any harvest
visual harvest must not bypass policy_blocked, unresolved auth_required, challenge_detected, or rate_limited; inspect diagnostics instead of forcing screenshots through blocked references
if readiness is needs_recovery, blocked, or diagnostic_only, follow the recovery-first command examples and do not continue to Canvas
after a product-ready run or harvest with top-level ready=true, productSuccess=true, artifactAuthority=product_ready, non-diagnostic evidenceAuthority, ranked references, manifest-backed evidence, and no doNotProceedIf blockers, read advanced-brief.md first, inspect evidence.json, ranked-references.json, bundle-manifest.json, discovery-diagnostics.json for query harvests, media-analysis.json, visual-evidence.json, screenshot-index.json, motion-evidence.json, pin-media-evidence.json, pin-media-index.json, and meta-prompt.md when present, load opendevbrowser_skill_load opendevbrowser-best-practices "quick start", opendevbrowser_skill_load opendevbrowser-design-agent "canvas-contract", and opendevbrowser_skill_load opendevbrowser-motion-design "quick start", open a Canvas session, fill the ids in canvas-plan.request.json, run opendevbrowser canvas --command canvas.plan.set --params-file ./canvas-plan.request.json --output-format json, confirm planStatus=accepted, then patch only the governance blocks listed in design-agent-handoff.json. Treat Pinterest pin-media as design-ready only when pin-media-index.json proves persisted first-party bytes; remote media URLs and media-analysis.json alone are not proof
pair this lane with opendevbrowser-design-agent when the brief moves from contract synthesis into implementation or /canvas
Do not conflate daemon_fingerprint_mismatch with native messaging host drift.
Run the same workflow shape across all three modes before claiming parity.
Default to read/research workflows. Social posting probes remain disabled unless explicitly requested via direct-run opt-in (--include-social-posts).
Re-check extension readiness on resume when a run crosses idle windows.
motionPosture
responsivePosture
accessibilityPosture
validationTargets
Minimum nested fields that commonly cause generation_plan_invalid if omitted:
visualDirection.themeStrategy
layoutStrategy.navigationModel
componentStrategy.interactionStates
motionPosture.reducedMotion
responsivePosture.requiredViewports
accessibilityPosture.keyboardNavigation
validationTargets.requiredThemes
validationTargets.browserValidation
validationTargets.maxInteractionLatencyMs
Immediately inspect the canvas.plan.set response.
If planStatus="accepted" or preflightState="plan_accepted", follow the returned guidance.recommendedNextCommands.
If the command fails with generation_plan_invalid, inspect details.missingFields, details.issues, guidance.paramsExamples, guidance.fieldExamples, guidance.validationChecks, guidance.doNotProceedIf, and the handshake generationPlanIssues, then repair the params file before resubmitting.
Use canvas.plan.get or canvas.capabilities.get only as diagnostics when the repair examples are not enough.
Only after the plan is accepted, call canvas.document.patch.
After every successful canvas.document.patch, canvas.preview.render, canvas.preview.refresh, canvas.feedback.poll, canvas.document.save, or canvas.document.export, read guidance.recommendedNextCommands and guidance.reason before deciding the next command.
Use canvas.preview.render, canvas.tab.open, canvas.overlay.mount, and canvas.overlay.select when a browser-backed live view is required.
Use canvas.feedback.poll for snapshot audits between mutation rounds. When the plan is still missing or invalid, expect a synthetic preflight-blocker item instead of normal stage feedback. Use canvas.feedback.subscribe -> canvas.feedback.next -> canvas.feedback.unsubscribe when a live pull-stream is needed.
Use canvas.document.save or canvas.document.export to persist artifacts.
Annotation remains a separate surface today, but popup and canvas both ship per-item and combined Copy / Send actions. Send delivers directly into the active agent chat when scope is safe and degrades to stored-only annotate --stored retrieval when scope is missing, ambiguous, or relay enqueue fails. New captures and stored payloads use Annotation V2 compact handoff by default: schemaVersion: 2, compact.screenshotMode="none", redaction metadata, selector bundles, canvas identity when available, and screenshot-free shared inbox storage. annotate --stored resolves the shared repo-local inbox first, then the extension-local fallback; browser replay artifacts stay in the screencast lane and are never written into the shared inbox.
