Guide · Agent skill

How to use the OpenCLI Adapter Author agent skill

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

The opencli-adapter-author skill helps an AI agent write or improve an OpenCLI adapter, which is a small JavaScript file that turns a website's data into a command-line command. It is for developers extending OpenCLI, maintainers fixing an adapter that broke after a site change, and engineers who want a reusable CLI command built from a site's public or browser-visible API. After this guide you will know how to install the skill, how to phrase a request that triggers it, what the agent does step by step, and which safety points to check before running it.

OpenCLI Adapter Authorjackwener/OpenCLI · Apache-2.0 Download the skill

Quick start

1Install the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings, Capabilities, Skills in the Claude apps.
2Install the prerequisites. Make sure Node.js and the OpenCLI CLI (@jackwener/opencli) are available, and that the opencli command runs. Install jsluice if you want static analysis.
3Ask for an adapter in plain language. Describe the site, the data you want and the command name. Mention OpenCLI so the agent loads the adapter-authoring workflow.
4Let the agent gather evidence. The agent checks existing adapters, opens the page in a named browser session and reviews network requests and page state against the visible data.
5Check and test the result. Run opencli adapter check, then run the command and opencli adapter test. Use a test account for any write command.

What the skill makes the agent do

Agent skills are folders of instructions and reference files that an AI agent loads when a task matches the skill's description. This one, named opencli-adapter-author, covers one job: producing an OpenCLI adapter that returns business data from a website.

The skill tells the agent to choose the simplest approach that reliably does the task. It first checks whether an existing adapter already covers the capability, then inspects the site's network requests and page state, and only then writes a new adapter. It also covers checking and testing the result.

Reuse an existing site adapter when one already does the job.
Gather evidence from browser sessions, captured network requests and static analysis of loaded scripts.
Write an adapter that returns business data; the CLI adds the JSON success envelope.
Check and test the adapter, including failure paths.

Install the skill from the ZIP or the Claude apps

Download the skill ZIP from this page. To install it for Claude Code, unzip it into ~/.claude/skills/ for all your projects, or into a project's .claude/skills/ folder to limit it to that project.

If you use the Claude apps instead, upload the ZIP under Settings, then Capabilities, then Skills. After installing, the skill's folder should contain SKILL.md and a references folder with files such as api-discovery.md, output-design.md and field-decode-playbook.md.

Claude Code, all projects: unzip into ~/.claude/skills/
Claude Code, one project: unzip into the project's .claude/skills/
Claude apps: Settings, Capabilities, Skills, then upload the ZIP

Check the requirements before you start

The skill needs Node.js and the OpenCLI CLI, published as @jackwener/opencli, so the opencli command is available. For static analysis it uses the jsluice tool, which the skill is allowed to run through Bash. Browser-based evidence capture needs a browser session controlled through OpenCLI.

If you are changing the OpenCLI repository itself, you also need that repo's typecheck and build tooling. The skill runs scripts and uses the network, so review the safety section before you approve it.

Node.js and the OpenCLI CLI (@jackwener/opencli)
The opencli command on your PATH
jsluice, for static analysis
A browser session controlled through OpenCLI
For repository changes: the OpenCLI repo's typecheck and build tools

opencli list search --site example
opencli example search --help -f json

Trigger the skill with a natural request

You do not need special syntax. Describe the site and the data you want, and mention adapters or the OpenCLI command. The skill's description covers building or improving an adapter from observed site behavior, so requests in that area should load it.

For ad-hoc clicking or one-off page interaction, the skill's description points to the separate opencli-browser skill instead. Use that one for tasks like filling in a single form.

Write an OpenCLI adapter that lists the trending posts on example.com.
My OpenCLI adapter for example search broke after the site redesign, please repair it.
Investigate the network requests on this page and build a search command from the API.
Add a read-only command to OpenCLI that returns the top items from this site's ranking page.

Follow the authoring workflow

The agent first looks for an existing adapter using opencli list with a site filter and reads its help output. If none covers the task, it opens the page in a named browser session and captures state, network requests and static candidates. It compares what it finds with the business data shown on the page before settling on an endpoint.

Adapters live under ~/.opencli/clis/<site>/<command>.js or in the repository's clis/<site>/ folder. Each file calls cli({...}) with a site, name, access level, strategy and an args list. The agent can scaffold a new file with opencli adapter init.

Check for an existing adapter first.
Open the page in a named session and capture evidence.
Prefer public APIs with a stable contract when they exist; browser fetch and page state are also valid.
Write the adapter, return business data and throw typed errors with hints on failure.
Set access to 'read' or 'write' accurately.

opencli browser open https://example.com --session research
opencli browser network --static --session research
opencli adapter init example/search

import { cli, Strategy } from '@jackwener/opencli/registry';

cli({
  site: 'example', name: 'search', description: 'Search example items',
  access: 'read', strategy: Strategy.PUBLIC, browser: false,
  args: [{ name: 'query', positional: true, required: true }],
  func: async (args) => {
    const response = await fetch(`https://example.com/api/search?q=${encodeURIComponent(args.query)}`);
    if (!response.ok) throw new Error(`Search failed: HTTP ${response.status}`);
    return response.json();
  },
});

Check and test the adapter

The check command validates the definition without running the adapter. The test command runs the normal CLI and can compare an existing fixture. The skill mentions --write-fixture, --update-fixture and --no-fixture for controlling optional expectations, and --trace retain-on-failure for diagnosing browser runs.

For repository changes, the skill asks for focused tests of the core behaviour and failure paths, plus typecheck and build. It also asks the agent to verify IDs, fields, units, pagination and empty or error results.

Run opencli adapter check to validate the definition.
Run the command directly to see real output.
Run opencli adapter test with --args as JSON.
Use --trace retain-on-failure when a browser run fails.

opencli adapter check example/search
opencli example search 'query'
opencli adapter test example/search --args '{"query":"query"}'

Safety notes: scripts, network and write commands

The skill runs scripts and uses the network. Static analysis reads loaded scripts without executing them, and the agent can replay read requests to compare results with the page. Review what it runs before approving, especially any Bash commands.

Write commands have real effects, and this includes running adapter test on a write command. The skill says to use a suitable test account or a supported dry-run. It also says not to automatically replay a write whose outcome is unknown; the agent should inspect state first. The skill does not address legal or policy limits on scraping, so check a site's terms yourself.

Test write commands only on a test account or with a supported dry-run.
Do not let the agent retry a write with an unknown outcome.
Read the site's terms of service before scraping.
Review Bash commands the agent proposes to run.

What people use it for

Adding a read-only search command for a site that has no OpenCLI adapter yet.
Repairing an existing adapter after the site changed its page structure or API.
Turning a site's ranking or listing page into a command that returns JSON rows.
Reviewing an adapter's output fields and empty or error handling before a repository change.

Frequently asked questions

Is the OpenCLI Adapter Author skill free to use?

The source material for this page does not state pricing or licence terms beyond the project licence shown on this page, which is Apache-2.0. Check the repository's licence file for the terms that apply to the code you use.

What do I need to install before using this skill?

You need Node.js and the OpenCLI CLI, published as @jackwener/opencli, with the opencli command available. jsluice is needed for static analysis, and a browser session controlled through OpenCLI is needed for browser-based evidence.

Where do I put the skill so Claude can find it?

For Claude Code, unzip the skill into ~/.claude/skills/ for all projects, or into a project's .claude/skills/ folder for one project. In the Claude apps, upload the ZIP under Settings, then Capabilities, then Skills.

Can the skill click around a website for me?

Not as its main job. The skill's description says ad-hoc browser interaction belongs to the separate opencli-browser skill. This skill is for writing or improving an adapter that returns business data.

Is it safe to let the agent run tests on a write command?

Be careful. The skill notes that write commands have real effects, including when run through adapter test. Use a suitable test account or a supported dry-run, and do not let the agent replay a write with an unknown outcome.

How does this compare with writing an OpenCLI adapter by hand?

The skill gives the agent a fixed workflow: check existing adapters, gather network and page evidence, write the adapter, then check and test it. Writing by hand gives you full control and needs you to do the same investigation yourself. The source does not compare the two in terms of speed or accuracy.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you maintain or extend OpenCLI and want an agent to investigate a site's API and write or repair a read-focused adapter with checks and tests. Pick something else if you only need one-off browser clicks, which the separate opencli-browser skill covers, or if you plan to test write actions against a real account.

Download the skill