OpenCLI Adapter Authoring Guide
End-to-end workflow to write and verify an OpenCLI adapter for a new site within 30 minutes.
Evidence: skill explicitly bounds scope, does not teach bypassing signatures/captchas/risk controls (coverage-matrix.md), requires reusing only legally obtained data; strategy selection has evidence discipline and typed errors prevent silent failures; emphasizes not storing credentials, sanitizing stored data, and verification before writing back. Deductions: no user confirmation mechanism (e.g., confirm before risky actions), relies on logged-in sessions involving sensitive data, but least-privilege scope and permission escalation not explicit; publisher unverified, attribution and update responsibility unclear.
Evidence: detailed runbook with fallback paths, structured; references real PRs (#1329, #1312) and adapter examples; error handling classification clear. Deductions: no visible test suite or CI evidence covering key paths; unexecuted static review cannot verify commands are reproducible; heavy dependence on external sites and browser state, high uncertainty.
Evidence: clear target audience (AI agents writing adapters), scenarios, and quick self-test (coverage-matrix.md three questions); provides non-supported list; semantic trigger conditions clear. Deductions: effectiveness depends on overseas services (GitHub, npm packages, Chrome Web Store), may be restricted in mainland China networks, no alternative provided.
Evidence: documentation well-structured, progressive disclosure (runbook, references), install/dependency notes exist, parameter and naming conventions clear, multiple examples, known limitations and boundaries (coverage-matrix.md), Apache-2.0 license, references to many PRs and files indicate active maintenance. Deductions: no version number or changelog, contributor maintenance responsibility not explicit, update path for upstream dependencies not stated.
Evidence: description clear, goal specific (30-minute closure); multiple adapter examples and fixture patterns show directly usable output format; references PR merge evidence. Deductions: no verifiable end-to-end example or third-party execution evidence, static review cannot confirm actual completion; direct usability of output not verified.
Evidence: references real PRs, adapter files, and fixture files as audit material; strategy selection and field decoding have evidence requirements. Deductions: no runnable tests or CI evidence; static review cannot independently reproduce core paths; lacking corroborating sources beyond author's own claims.
- Core functionality depends on overseas services (GitHub, npm, Chrome Web Store), which may be inaccessible in mainland China networks; prepare alternatives or mirrors.
- Skill requires reusing user's logged-in sessions; if handling sensitive data, ensure explicit user consent and follow least-privilege principle.
- No versioning or changelog; maintenance responsibility unclear, upstream changes may affect stability.
- Static review cannot verify actual execution; validate in real environment before adoption.
What does this skill do, and when should you use it?
This skill guides you through writing an OpenCLI adapter for a new site or adding a new command to an existing site. It provides a complete workflow: recon, API discovery, strategy selection, field decoding, coding, and verification. It emphasizes choosing a data source strategy based on external contract stability (public API, cookie, UI selector, etc.), with a detailed decision tree and fallback paths. The skill uses `opencli browser` commands throughout and requires leveraging site memory to speed up subsequent adapters. It is designed for the OpenCLI ecosystem, ideal for developers who want to build CLI interfaces for websites within OpenCLI.
Runs opencli doctor to check the environment, reads local site memory (endpoints.json, notes.md), performs site recon using opencli browser analyze, discovers API endpoints via network inspection, state extraction, bundle search, or interception, verifies endpoints by direct fetch, selects a strategy based on contract level and writes a strategy note, decodes fields (using field-conventions or decode-playbook), generates an adapter skeleton with opencli browser init, verifies with opencli browser verify and generates fixtures, and finally writes back endpoints, field maps, and notes to ~/.opencli/sites/.
- A developer needs to add a CLI command for a website not yet covered by OpenCLI (e.g., an internal tool).
- A developer needs to add a new command to an existing adapter (e.g., add 'follow list' to the Bilibili adapter).
- A developer needs to fix a broken adapter due to site changes, requiring re-recon and data source adjustment.
- A developer wants to migrate stable UI/DOM scraping to a more stable public API, but needs to assess contract stability.
- An AI agent wants to wrap website operations into reusable CLI commands for future automation.
What are this skill's strengths and limitations?
- Provides a complete, structured workflow from recon to verification, reducing guesswork.
- Emphasizes contract stability of data sources, helping reduce maintenance costs.
- Detailed fallback paths and troubleshooting guide.
- Site memory accelerates subsequent adapter development.
- Designed for the OpenCLI ecosystem, depends on its specific commands and tools.
- Requires installing and configuring OpenCLI runtime and browser extension first.
- May be overkill for simple data scraping.
- No test suite or complete example adapter code provided.
How do you install this skill?
This skill is part of the OpenCLI repository. Install the whole skill collection: npx skills add jackwener/opencli, or install only this skill: npx skills add jackwener/opencli --skill opencli-adapter-author. Requires OpenCLI runtime (e.g., OpenCLIApp or npm install -g @jackwener/opencli with Node.js 20+) and a browser bridge extension.
How do you use this skill?
Ensure opencli doctor passes. Read the skill's pre-check (coverage-matrix). Follow the runbook: recon the site, discover API, write strategy note, decode fields, use opencli browser init <site>/<name> to initialize adapter, and validate with opencli browser verify <site>/<name>. Follow the decision tree and fallback paths. Refer to the detailed docs in references/.
How does this skill compare with similar options?
Compared to the opencli-browser skill in the same repo, it focuses on writing reusable adapters rather than ad-hoc browser driving.