Claude Skill

opencli-adapter-author

Use when writing an OpenCLI adapter for a new site or adding a new command to an existing site. Guides end-to-end from first recon through field decoding, adapter coding, and verify. Replaces opencli-oneshot / opencli-explorer. For ad-hoc browser driving (no adapter), see opencli

LLM Mart · 0 points · 2 views 0 listing impressions 0 install-command copies
Download mxyhi-ok-skills-opencli_opencli-adapter-author-fe5e7a2.zip · 72 KB

Install

skills CLI npx skills add https://github.com/mxyhi/ok-skills/tree/main/opencli/opencli-adapter-author
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install mxyhi-ok-skills@llmmart
Git git clone https://github.com/mxyhi/ok-skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole mxyhi/ok-skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Adapter authoring

Choose the simplest implementation that reliably performs the requested task. Use an existing site adapter when it already covers the capability:

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

list returns {ok:true,data:{commands,total,nextOffset?}}; use --offset to continue, --limit to adjust page size. Detailed arguments belong in command help.

Evidence available to you

opencli browser open https://example.com --session research
opencli browser state --diagnostics --session research
opencli browser network --session research
opencli browser network --static --session research
opencli browser network --detail RequestKey --session research

Network captures describe observed requests. Static analysis adds candidates from loaded scripts without executing them. Inspect source locations, unresolved expressions and capture provenance. Replay read requests when useful and compare business data with the page. Write commands have real effects, including when run through adapter test; use a suitable test account or a supported dry-run.

Prefer public APIs with a stable contract when available. Browser fetch, captured responses, page state and semantic UI interactions are also valid choices. Select based on the task and observed reliability. Do not guess endpoint parameters or hide failed operations behind empty success results.

JS interface

Adapters are ordinary files under ~/.opencli/clis/<site>/<command>.js or repository clis/<site>/. There is no draft directory, promotion step or required memory file.

opencli adapter init example/search

The existing cli({...}) interface is unchanged: func(args) for Node execution, func(page, args) with browser: true. Reuse neighboring adapters and shared helpers. Return business data; the CLI adds the JSON success envelope. Throw a typed error with an actionable hint for failures. Use access: 'read'|'write' accurately. columns controls human table exports; JSON preserves nested results.

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 exercise

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

check validates definitions without executing adapters. test executes the normal CLI and optionally compares an existing fixture. --write-fixture, --update-fixture and --no-fixture control optional expectations; no row-shape or site-memory gate is imposed. --trace retain-on-failure helps diagnose browser execution.

For repository changes, cover the core behavior and failure paths with focused production-path tests, typecheck and build. Verify IDs, fields, units, pagination and empty/error semantics relevant to the task. Do not automatically replay a write with an unknown outcome; inspect state first.

Optional references

Read only what is useful for the current task: references/adapter-template.md for adapter patterns, api-discovery.md for request investigation, output-design.md for result fields, field-decode-playbook.md for opaque fields, and deep-recon.md for difficult private protocols. Site notes and fixtures are optional knowledge aids; older reference checklists are not mandatory workflows.

Files (ok-skills)
  • references
    • site-memory
      • bilibili.md 3.6 KB
        Loading…
      • eastmoney.md 3.8 KB
        Loading…
      • gmail.md 2.8 KB
        Loading…
      • tonghuashun.md 2.4 KB
        Loading…
      • xueqiu.md 2.8 KB
        Loading…
    • adapter-template.md 21.2 KB
      Loading…
    • api-discovery.md 17 KB
      Loading…
    • coverage-matrix.md 5.5 KB
      Loading…
    • deep-recon.md 10.3 KB
      Loading…
    • field-conventions.md 5.2 KB
      Loading…
    • field-decode-playbook.md 7.1 KB
      Loading…
    • jsdom-fixture-pattern.md 7.9 KB
      Loading…
    • output-design.md 4.7 KB
      Loading…
    • site-memory.md 10.7 KB
      Loading…
    • site-recon.md 4.5 KB
      Loading…
    • strategy-selection.md 2.3 KB
      Loading…
    • success-rate-pitfalls.md 9.3 KB
      Loading…
    • typed-errors.md 12.6 KB
      Loading…
  • SKILL.md 4 KB
    ---
    name: opencli-adapter-author
    description: Build or improve an OpenCLI JS adapter using observed site behavior, existing adapters and browser API evidence. For ad-hoc browser interaction, see opencli-browser.
    allowed-tools: Bash(opencli:*), Bash(jsluice:*), Read, Edit, Write, Grep
    ---
    
    # Adapter authoring
    
    Choose the simplest implementation that reliably performs the requested task.
    Use an existing site adapter when it already covers the capability:
    
    ```sh
    opencli list search --site example
    opencli example search --help -f json
    ```
    
    `list` returns `{ok:true,data:{commands,total,nextOffset?}}`; use `--offset` to
    continue, `--limit` to adjust page size. Detailed arguments belong in command help.
    
    ## Evidence available to you
    
    ```sh
    opencli browser open https://example.com --session research
    opencli browser state --diagnostics --session research
    opencli browser network --session research
    opencli browser network --static --session research
    opencli browser network --detail RequestKey --session research
    ```
    
    Network captures describe observed requests. Static analysis adds candidates
    from loaded scripts without executing them. Inspect source locations, unresolved
    expressions and capture provenance. Replay read requests when useful and compare
    business data with the page. Write commands have real effects, including when run
    through `adapter test`; use a suitable test account or a supported dry-run.
    
    Prefer public APIs with a stable contract when available. Browser fetch, captured
    responses, page state and semantic UI interactions are also valid choices. Select
    based on the task and observed reliability. Do not guess endpoint parameters or
    hide failed operations behind empty success results.
    
    ## JS interface
    
    Adapters are ordinary files under `~/.opencli/clis/<site>/<command>.js` or repository
    `clis/<site>/`. There is no draft directory, promotion step or required memory file.
    
    ```sh
    opencli adapter init example/search
    ```
    
    The existing `cli({...})` interface is unchanged: `func(args)` for Node execution,
    `func(page, args)` with `browser: true`. Reuse neighboring adapters and shared helpers.
    Return business data; the CLI adds the JSON success envelope. Throw a typed error
    with an actionable hint for failures. Use `access: 'read'|'write'` accurately.
    `columns` controls human table exports; JSON preserves nested results.
    
    ```js
    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 exercise
    
    ```sh
    opencli adapter check example/search
    opencli example search 'query'
    opencli adapter test example/search --args '{"query":"query"}'
    ```
    
    `check` validates definitions without executing adapters. `test` executes the normal
    CLI and optionally compares an existing fixture. `--write-fixture`, `--update-fixture`
    and `--no-fixture` control optional expectations; no row-shape or site-memory gate
    is imposed. `--trace retain-on-failure` helps diagnose browser execution.
    
    For repository changes, cover the core behavior and failure paths with focused
    production-path tests, typecheck and build. Verify IDs, fields, units, pagination
    and empty/error semantics relevant to the task. Do not automatically replay a
    write with an unknown outcome; inspect state first.
    
    ## Optional references
    
    Read only what is useful for the current task: `references/adapter-template.md`
    for adapter patterns, `api-discovery.md` for request investigation,
    `output-design.md` for result fields, `field-decode-playbook.md` for opaque fields,
    and `deep-recon.md` for difficult private protocols. Site notes and fixtures are
    optional knowledge aids; older reference checklists are not mandatory workflows.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.