Opencli Autofix
Recover when an OpenCLI site adapter breaks after a DOM or API change—collect a trace, patch only the adapter file, retry, and optionally file an upstream issue.
Overview
OpenCLI AutoFix is an agent skill most often used in Operate (also Build) that automatically repairs a broken OpenCLI adapter from trace output, with hard safety stops and a 3-round retry cap.
Install
npx skills add https://github.com/jackwener/opencli --skill opencli-autofixWhat is this skill?
- Hard-stops on AUTH_REQUIRED (77), BROWSER_CONNECT (69), CAPTCHA, and rate limits—no blind code edits
- Repairs only the adapter at adapterSourcePath from trace summary front matter
- Max 3 diagnose → fix → retry rounds before escalating to the user
- Uses opencli trace artifacts and gh for verified upstream GitHub issues
- Explicit scope: never touch src/, extension/, tests/, package.json, or tsconfig.json
- Maximum 3 repair rounds per failure
- Hard stop exit codes 77 (AUTH_REQUIRED) and 69 (BROWSER_CONNECT)
Adoption & trust: 11k installs on skills.sh; 23.8k GitHub stars; 1/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your opencli command failed because a site changed and you need the adapter fixed and retried without hacking the whole OpenCLI codebase.
Who is it for?
Builders who run OpenCLI daily and want agents to self-heal site adapters when selectors or response shapes drift.
Skip if: Auth/login failures, disconnected browsers, CAPTCHA blocks, or cases where you need to change OpenCLI core source instead of one adapter.
When should I use this skill?
Load when an opencli command fails—it guides trace collection, adapter patching, retry, and upstream issue filing after a verified fix.
What do I get? / Deliverables
The agent produces a trace-guided patch limited to the adapter file, retries up to three times, and can open a GitHub issue after a confirmed fix.
- Patched adapter file at adapterSourcePath only
- Retry outcome after up to 3 repair rounds
- Optional upstream GitHub issue via gh after verified fix
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Operate/iterate is the canonical shelf because the skill exists for production-like CLI breakage and self-repair loops, though it also applies during Build when you integrate OpenCLI commands. Iterate covers fast adapter patches and bounded retry cycles without rewriting the whole OpenCLI platform.
Where it fits
A new OpenCLI integration fails in CI because the target site renamed form fields.
A nightly automation script breaks and you need a trace-led adapter patch without touching core OpenCLI.
Pre-release smoke via opencli fails on schema mismatch and you retry after a bounded adapter fix.
How it compares
A bounded self-repair workflow for OpenCLI adapters, not a generic “fix any npm package” debugger.
Common Questions / FAQ
Who is opencli-autofix for?
Solo builders and agent users who depend on OpenCLI CLIs and want automatic adapter repairs when external sites change.
When should I use opencli-autofix?
After any failing opencli command during Operate/iterate maintenance, or during Build/integrations while wiring new site automations—never when exit codes indicate auth or browser connection failures.
Is opencli-autofix safe to install?
It edits adapter files and can run gh; review the Security Audits panel on this Prism page and confirm adapterSourcePath before allowing writes.
SKILL.md
READMESKILL.md - Opencli Autofix
# 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 ```bash opencli doctor # Verify extension + daemon connectivity ``` ## 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: ```bash opencli <site> <command> [args...] --trace retain-on-failure 2>trace-error.yaml ``` On failure, stderr contains the normal error envelope plus a small `trace` block: ```yaml ok: false error: code: SELECTOR message: "Could not f