How to use the OpenCLI AutoFix agent skill (opencli-autofix)

What an agent skill is and what this one does

An agent skill is a folder containing a SKILL.md file with instructions that an AI agent loads when a request matches the skill's description. The skill for opencli-autofix is described as automatically fixing broken OpenCLI adapters when commands fail.

When an opencli command fails with a repairable error, the skill directs the agent to collect a trace artifact, inspect the live site, patch the adapter, and retry. It also requires the agent to report the error instead of guessing when a hard stop applies.

• Repairable errors include SELECTOR, EMPTY_RESULT, API_ERROR, NETWORK, PAGE_CHANGED, COMMAND_EXEC and TIMEOUT.
• Hard stops include AUTH_REQUIRED (exit code 77), BROWSER_CONNECT (exit code 69), and CAPTCHA or rate limiting.
• The repair budget is a maximum of 3 repair rounds per failure, after which the agent stops and reports what it tried.

Install the opencli-autofix skill

Download the ZIP for the skill from the directory page and unzip it. For a personal install, place the skill folder in ~/.claude/skills/. For a single project, place it in the project's .claude/skills/ folder.

In the Claude apps you can instead upload the ZIP under Settings → Capabilities → Skills.

• Personal: ~/.claude/skills/
• Project: .claude/skills/ inside your project folder
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Install the requirements

The skill depends on several tools. Check connectivity with opencli doctor before relying on repairs. The skill's own prerequisite check is the opencli doctor command, which verifies the extension and daemon connection.

• OpenCLI CLI installed (the opencli command)
• OpenCLI browser extension and daemon, checked via opencli doctor
• GitHub CLI (gh), needed only for filing upstream issues
• Chrome with the target site logged in, where the site requires login

How to trigger the skill with a natural request

Load the skill by asking the agent to work on a failing OpenCLI command. The skill's description says to load it when an opencli command fails, so a request that mentions the failure is the natural trigger. Give the agent the command and the error so it can start at Step 1.

The agent will first run the failing command with trace retention enabled. You do not need to pass legacy diagnostic environment variables.

• "My opencli example search command fails with a SELECTOR error. Please fix the adapter."
• "opencli xiaohongshu search returned EMPTY_RESULT after the site update. Diagnose it."
• "Retry the failing opencli command after repairing the adapter."

What the agent does during a repair

The skill sets a clear sequence. First, the agent rules out a non-adapter cause: an empty result may come from a platform degrading results, so it retries with an alternative query, spot-checks in a normal Chrome tab, and retries after a short delay. It proceeds to repair only if the empty or selector-missing result is reproducible.

Next, the agent runs the command with --trace retain-on-failure, reads summaryPath from the error output, and reads the adapter source at adapterSourcePath. It then explores the live site with opencli browser, without using the broken adapter, and makes targeted edits.

• Collect trace: opencli <site> <command> --trace retain-on-failure
• Read summary.md first, then receipt.json, trace.jsonl, network.jsonl, console.jsonl, state/ and screenshots/ as needed
• Explore the live page with opencli browser (for DOM changes, state; for API changes, network with filters)
• Patch only the file at adapterSourcePath, then retry

Examples of repair requests

A typical SELECTOR failure happens when the site renames a class. The agent finds the new selector in the current DOM and updates the one line in the adapter. An EMPTY_RESULT failure often means the response shape changed, so the agent inspects the network responses to find the new data path.

Stop cases look different. If the error is AUTH_REQUIRED, the agent tells you to log into the site in Chrome and does not edit code. If it is BROWSER_CONNECT, the agent tells you to run opencli doctor.

• SELECTOR: class renamed, agent finds the new selector and updates the adapter
• EMPTY_RESULT: response schema moved, agent checks network and updates the response path
• TIMEOUT: page lazy-loads differently, agent updates wait conditions
• AUTH_REQUIRED: agent stops and asks you to log in

Safety notes: scripts, network and file edits

This skill runs scripts and uses the network. Its allowed tools include Bash for opencli and gh commands, plus Read, Edit and Write. It can edit local adapter files and may file GitHub issues after a verified fix.

The scope is narrow by design. The agent may only modify the file at adapterSourcePath listed in the trace summary. It must never modify src/, extension/, tests/, package.json or tsconfig.json. Review changes before you rely on them, especially if you do not want an agent editing local code automatically.

• Only the adapterSourcePath file may be edited
• Never touch src/, extension/, tests/, package.json, tsconfig.json
• CAPTCHA and rate limits are not adapter issues and must be handled manually
• Filing an upstream GitHub issue uses the gh command after a verified fix