Automatically fix broken OpenCLI adapters when commands fail. Load this skill when an opencli command fails — it guides you through collecting a trace artifact, patching the adapter, retrying, and filing an upstream GitHub issue after a verified fix. Works with any AI agent.

OpenCLI AutoFix — Automatic Adapter Self Repair When an opencli command fails because a website changed its DOM, API, or response schema, automatically diagnose, fix the adapter, and retry — don't just report the error. Safety Boundaries Before starting any repair, check these hard stops: AUTH REQUIRED (exit code 77) — STOP. Do not modify code. Tell the user to log into the site in Chrome. BROWSER CONNECT (exit code 69) — STOP. Do not modify code. Tell the user to run opencli doctor . CAPTCHA / rate limiting — STOP. Not an adapter issue. Scope constraint: Only modify the file at adapterSourcePath in the trace summary.md front matter — this is the authoritative adapter location (may be clis/<site / in repo or ~/.opencli/clis/<site / for npm installs) Never modify src/ , extension/ , tests/ , package.json , or tsconfig.json Retry budget: Max 3 repair rounds per failure. If 3 rounds of diagnose → fix → retry don't resolve it, stop and report what was tried. Prerequisites When to Use This Skill Use when opencli <site <command fails with repairable errors: SELECTOR — element not found (DOM changed) EMPTY RESULT — no data returned (API response changed) API ERROR / NETWORK — endpoint moved or broke PAGE CHANGED — page structure no longer matches COMMAND EXEC — runtime error in adapter logic TIMEOUT — page loads differently, adapter waits for wrong thing Before Entering Repair: "Empty" ≠ "Broken" EMPTY RESULT — and sometimes a structurally valid SELECTOR that returns nothing — is often not an adapter bug . Platforms actively degrade results under anti scrape heuristics, and a "not found" response from the site doesn't mean the content is actually missing. Rule this out before committing to a repair round: Retry with an alternative query or entry point. If opencli xiaohongshu search "X" returns 0 but opencli xiaohongshu search "X 攻略" returns 20, the adapter is fine — the platform was shaping results for the first query. Spot check in a normal Chrome tab. If the data is visible in the user's own browser but the adapter comes back empty, the issue is usually authentication state, rate limiting, or a soft block — not a code bug. The fix is opencli doctor / re login, not editing source. Look for soft 404s. Sites like xiaohongshu / weibo / douyin return HTTP 200 with an empty payload instead of a real 404 when an item is hidden or deleted. The snapshot will look structurally correct. A retry 2 3 seconds later often distinguishes "temporarily hidden" from "actually gone". "0 results" from a search is an answer. If the adapter successfully reached the search endpoint, got an HTTP 200, and the platform returned results: [] , that is a valid answer — report it to the user as "no matches for this query" rather than patching the adapter. Only proceed to Step 1 if the empty/selector missing result is reproducible across retries and alternative entry points . Otherwise you're patching a working adapter to chase noise, and the patched version will break the next working path. Step 1: Collect Trace Context Run the failing command with failure retained trace enabled: On failure, stderr contains the normal error envelope plus a small trace block: Read summaryPath first. It is the LLM oriented entry point and includes front matter: The artifact directory contains: If you redirected stderr to a file, read that file and copy trace.summaryPath . Do not ask the user to rerun with legacy diagnostic env vars. Trace is the repair evidence path. Step 2: Analyze the Failure Read the trace summary and the adapter source. Classify the root cause: Error Code Likely Cause Repair Strategy SELECTOR DOM restructured, class/id renamed Explore current DOM → find new selector EMPTY RESULT API response schema changed, or data moved Check network → find new response path API ERROR Endpoint URL changed, new params required Discover new API via network intercept AUTH REQUIRED Login flow changed, cookies expired STOP — tell user to log in, do not modify code TIMEOUT Page loads differently, spinner/lazy load Add/update wait conditions PAGE CHANGED Major redesign May need full adapter rewrite Key questions to answer: 1. What is the adapter trying to do? (Read the file at adapterSourcePath ) 2. What did the page look like when it failed? (Read summary.md , then state/ if needed) 3. What network requests happened? (Read Failed Network in summary.md , then network.jsonl if needed) 4. What's the gap between what the adapter expects and what the page provides? Step 3: Explore the Current Website Use opencli browser to inspect the live website. Never use the broken adapter — it will just fail again. DOM changed (SELECTOR errors) API changed (API ERROR, EMPTY RESULT) Step 4: Patch the Adapter Read the adapter source file at adapterSourcePath from the trace summary front matter and make targeted fixes. This path is authoritative — it may be in the repo ( clis/ ) or user local ( ~/.opencli/clis/ ). Use the Read tool on the exact path from summary.md front matter. Common Fixes Selector update: API endpoint change: Response schema change: Wait condition update: Rules for Patching 1. Make minimal changes — fix only what's broken, don't refactor 2. Keep the same output structure — columns and return format must stay compatible 3. Prefer API over DOM scraping — if you discover a JSON API during exploration, switch to it 4. Use @jackwener/opencli/ imports only — never add third party package imports 5. Test after patching — run the command again to verify 6. Never relax verify/<cmd .json fixtures to silence a failure. A failing patterns / notEmpty / mustNotContain / mustBeTruthy rule means the adapter's output is broken. Tighten the adapter so it produces correct values; do not loosen the fixture to accept the broken values. The one legitimate reason to edit a fixture during repair is when the site itself changed shape (e.g. URL format migration) — in that case update the fixture and note the change in ~/.opencli/sites/<site /notes.md . Otherwise editing the fixture is covering up a silent correctness regression. Step 5: Verify the Fix If it still fails, go back to Step 1 and collect a fresh trace. You have a budget of 3 repair rounds (trace → fix → retry). If the same error persists after a fix, try a different approach. After 3 rounds, stop and report what was tried. Step 6: File an Upstream Issue If the retry passes , the local adapter has drifted from upstream. File a GitHub issue so the fix flows back to jackwener/OpenCLI . Do NOT file for: AUTH REQUIRED , BROWSER CONNECT , ARGUMENT , CONFIG — environment/usage issues, not adapter bugs CAPTCHA or rate limiting — not fixable upstream Failures you couldn't actually fix (3 rounds exhausted) Only file after a verified local fix — the retry must pass first. Procedure: 1. Prepare the issue content from the trace summary you already have: Title: [autofix] <site /<command : <error code (e.g. [autofix] zhihu/hot: SELECTOR ) Body (use this template): 2. Ask the user before filing. Show them the draft title and body. Only proceed if they confirm. 3. If the user approves and gh auth status succeeds: If gh is not installed or not authenticated, tell the user and skip — do not error out. When to Stop Hard stops (do not modify code): AUTH REQUIRED / BROWSER CONNECT — environment issue, not adapter bug Site requires CAPTCHA — can't automate this Rate limited / IP blocked — not an adapter issue Soft stops (report after attempting): 3 repair rounds exhausted — stop, report what was tried and what failed Feature completely removed — the data no longer exists Major redesign — needs full adapter rewrite via opencli adapter author skill In all stop cases, clearly communicate the situation to the user rather than making futile patches. Example Repair Session

opencli-autofix