Add README and agent-first skill guidance

Author: GloriaGuo

README.md

@@ -0,0 +1,101 @@
+# OpenCLI Skill
+
+A Codex skill for working with [OpenCLI](https://github.com/jackwener/opencli): installation checks, command discovery, browser-login reuse, desktop-app adapters, downloads, troubleshooting, and adapter-generation workflows.
+
+Repository: [GloriaGuo/opencli-skill](https://github.com/GloriaGuo/opencli-skill)
+
+## What This Skill Covers
+
+- Choosing when OpenCLI is a better fit than browser agents or Playwright
+- Discovering commands safely with `opencli list -f yaml`
+- Running browser-backed site commands with Chrome login reuse
+- Running desktop adapters such as Codex and Cursor
+- Using OpenCLI as a passthrough hub for local CLIs such as `gh` and `docker`
+- Downloading media and exported articles
+- Troubleshooting the Browser Bridge, daemon, auth, and installed-command mismatches
+- Generating new OpenCLI adapters
+
+## Files
+
+- [SKILL.md](./SKILL.md): main skill entrypoint
+- [agents/openai.yaml](./agents/openai.yaml): UI metadata for the skill
+- [references/agent-playbook.md](./references/agent-playbook.md): fastest agent-first operating path
+- [references/commands.md](./references/commands.md): common commands and output patterns
+- [references/china-workflows.md](./references/china-workflows.md): China-focused site and desktop examples
+- [references/practical-scenarios.md](./references/practical-scenarios.md): detailed use-case manual
+- [references/troubleshooting.md](./references/troubleshooting.md): common failure signatures and fixes
+
+## Install
+
+Clone or copy the repo into your Codex skills directory:
+
+```bash
+git clone git@github.com:GloriaGuo/opencli-skill.git "${CODEX_HOME:-$HOME/.codex}/skills/opencli"
+```
+
+Or copy the folder contents manually into:
+
+```bash
+${CODEX_HOME:-$HOME/.codex}/skills/opencli
+```
+
+## Recommended OpenCLI Setup
+
+```bash
+npm install -g @jackwener/opencli
+opencli doctor
+opencli list -f yaml
+```
+
+For browser-backed commands:
+
+- Keep Chrome open
+- Log into the target site in Chrome
+- Install and enable the OpenCLI Browser Bridge extension
+
+## Quick Examples
+
+Public data:
+
+```bash
+opencli hackernews top --limit 5 -f json
+```
+
+Browser-backed data:
+
+```bash
+opencli bilibili hot --limit 5 -f json
+opencli zhihu search "Android 性能优化" -f json
+```
+
+Desktop adapters:
+
+```bash
+opencli codex --help
+opencli codex read -f json
+opencli cursor read -f json
+opencli cursor ask "总结当前工作区最近一次对话"
+```
+
+Downloads:
+
+```bash
+opencli zhihu download "https://zhuanlan.zhihu.com/p/xxx" --output ./zhihu
+opencli bilibili download BV1xxx --output ./bilibili
+```
+
+## Design Principles
+
+- Prefer deterministic command output over ad-hoc browsing
+- Start with read-only commands
+- Trust the installed CLI surface over stale README assumptions
+- Use `json` for agents and `yaml` for humans
+- Treat browser login state as a first-class dependency
+
+## Validation
+
+This skill can be validated with:
+
+```bash
+python3 /Users/ruiguo/.codex/skills/.system/skill-creator/scripts/quick_validate.py .
+```

SKILL.md

@@ -7,10 +7,23 @@ description: Use when Codex needs to install, inspect, troubleshoot, or operate
 
 OpenCLI turns websites, Electron apps, and existing local CLIs into structured terminal commands. Prefer it when deterministic CLI output is more useful than ad-hoc browser automation.
 
+## Trigger Cues
+
+Load this skill when the task sounds like any of these:
+
+- "use opencli"
+- "pull data from Bilibili/Zhihu/Xiaohongshu/Weixin/Boss"
+- "reuse my Chrome login"
+- "control Cursor/Codex/Notion/ChatGPT from the terminal"
+- "download article/video/media through OpenCLI"
+- "inspect what OpenCLI supports on this machine"
+- "create or troubleshoot an OpenCLI adapter"
+
 ## Reference Files
 
 | Reference | Use for |
 | --- | --- |
+| [references/agent-playbook.md](references/agent-playbook.md) | Agent-first trigger patterns, action order, and safe defaults |
 | [references/commands.md](references/commands.md) | Common commands, category selection, and example invocations |
 | [references/china-workflows.md](references/china-workflows.md) | China-focused site templates and desktop-agent workflows |
 | [references/practical-scenarios.md](references/practical-scenarios.md) | Detailed field manual for choosing OpenCLI and executing end-to-end workflows |
@@ -28,6 +41,7 @@ OpenCLI turns websites, Electron apps, and existing local CLIs into structured t
    - New site development: use `explore`, `synthesize`, `generate`, and `cascade`.
 4. Prefer `-f json` for agent-readable output. Use `-f yaml` for human inspection, `-f table` for terminal browsing, and `-v` only when debugging.
 5. If a browser-backed command returns empty data or authorization errors, verify the Chrome login state before changing commands or code.
+6. Before any write-like action such as `post`, `reply`, `send`, `publish`, `greet`, or `follow`, do at least one read-only command first unless the user explicitly asks to skip that safety step.
 
 ## Decision Guide
 
@@ -57,4 +71,6 @@ Use `opencli explore <url> --site <name>` to inspect a site, `opencli synthesize
 - Prefer structured output over prose whenever another tool or agent will consume the result.
 - For media downloads, install `yt-dlp` when the adapter requires it.
 - When a command is likely browser-backed, assume login state matters until proven otherwise.
+- For desktop adapters, check `--help` before assuming command parity across apps or versions.
+- Treat `opencli list -f yaml` as the source of truth when the README and installed commands disagree.
 - Read [references/troubleshooting.md](references/troubleshooting.md) before concluding that an adapter is broken.

agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "OpenCLI"
-  short_description: "Run websites and desktop apps through OpenCLI"
-  default_prompt: "Use $opencli to inspect the local OpenCLI setup and run the right command for this site or app."
+  short_description: "Discover and run OpenCLI workflows safely"
+  default_prompt: "Use $opencli to inspect the installed OpenCLI surface, choose the right adapter, and run a safe read-first workflow for this task."

references/agent-playbook.md

@@ -0,0 +1,99 @@
+# OpenCLI Agent Playbook
+
+This file is optimized for agent behavior. Read it when the user wants results through OpenCLI and you need a safe default path quickly.
+
+## Trigger Phrases
+
+Strong signals:
+
+- "use opencli"
+- "check what opencli can do"
+- "run this through my browser login"
+- "query Bilibili / Zhihu / Xiaohongshu / Weixin / Boss"
+- "control Codex / Cursor / ChatGPT / Notion from terminal"
+- "download this article/video with opencli"
+- "generate an opencli adapter"
+
+Weak but useful signals:
+
+- The task needs deterministic CLI output instead of free-form browsing
+- The user already has the site logged in in Chrome
+- The task targets a known site repeatedly
+
+## Default Action Order
+
+Follow this order unless the user already gave an exact command:
+
+1. `opencli doctor` if the task is browser-backed and health is unknown
+2. `opencli list -f yaml` if the command surface is unknown
+3. Use read-only commands first
+4. Use `-f json` if another tool or model will consume the result
+5. Expand scope only after a small first pass succeeds
+
+## First Commands By Situation
+
+### Browser-backed site
+
+```bash
+opencli doctor
+opencli list -f yaml
+opencli <site> <read-command> --limit 5 -f json
+```
+
+### Desktop adapter
+
+```bash
+opencli <app> --help
+opencli <app> read -f json
+opencli <app> history -f json
+opencli <app> model -f json
+```
+
+### External CLI passthrough
+
+```bash
+opencli <tool> ...
+```
+
+### Adapter development
+
+```bash
+opencli explore <url> --site <name>
+opencli synthesize <name>
+opencli generate <url> --goal "<goal>"
+```
+
+## Safe Defaults
+
+- Start with `--limit 5` or `--limit 10`
+- Prefer `json` for machine consumption
+- Prefer `yaml` when the human will scan raw output
+- Do not begin with write actions such as `post`, `reply`, `publish`, `greet`, `send`, or `follow`
+- For browser-backed commands, suspect login state before suspecting the adapter
+
+## Write-Action Rule
+
+Before any write-capable command:
+
+1. Read current state first
+2. Confirm target identity or content source
+3. Keep the outbound command explicit in the transcript
+
+Examples:
+
+- Before `boss greet`, run `boss detail`
+- Before `jike post`, inspect timeline or notifications if relevant
+- Before desktop `send` or `ask`, confirm the app and active context with `read`, `history`, or `model`
+
+## Installed-Version Rule
+
+Do not assume the README equals the installed surface area.
+
+When in doubt:
+
+```bash
+opencli <adapter> --help
+opencli list -f yaml
+```
+
+Trust the installed CLI over stale docs.