@@ -1,29 +1,49 @@
 # 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.
+English | [中文](#中文说明)
+
+A Codex skill for working with [OpenCLI](https://github.com/jackwener/opencli): command discovery, browser-login reuse, desktop-app adapters, downloads, troubleshooting, and adapter-generation workflows.
 
 Repository: [GloriaGuo/opencli-skill](https://github.com/GloriaGuo/opencli-skill)
 
+## Why This Exists
+
+OpenCLI is powerful, but it spans several different modes:
+
+- public data commands
+- browser-backed site adapters
+- Electron desktop adapters
+- external CLI passthrough
+- adapter generation workflows
+
+This skill gives Codex a read-first, agent-safe operating path so it can:
+
+- discover the installed OpenCLI surface before guessing
+- choose the right adapter for a site or app
+- prefer structured output such as JSON
+- troubleshoot Browser Bridge, login-state, and installed-version mismatches
+
 ## 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
+- choosing OpenCLI vs browser agents vs 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 daemon, extension, auth, and command-surface issues
+- generating new OpenCLI adapters
 
-## Files
+## Repository Structure
 
 - [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
+- [agents/openai.yaml](./agents/openai.yaml): UI metadata
+- [references/agent-playbook.md](./references/agent-playbook.md): shortest agent-first path
+- [references/commands.md](./references/commands.md): common commands and output modes
 - [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
+- [references/practical-scenarios.md](./references/practical-scenarios.md): detailed scenario manual
+- [references/troubleshooting.md](./references/troubleshooting.md): common failures and fixes
+- [examples/README.md](./examples/README.md): example prompts and command recipes
 
 ## Install
 
@@ -49,11 +69,11 @@ 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
+- keep Chrome open
+- log into the target site in Chrome
+- install and enable the OpenCLI Browser Bridge extension
 
-## Quick Examples
+## Quick Start
 
 Public data:
 
@@ -74,7 +94,7 @@ Desktop adapters:
 opencli codex --help
 opencli codex read -f json
 opencli cursor read -f json
-opencli cursor ask "总结当前工作区最近一次对话"
+opencli cursor ask "Summarize the latest workspace conversation"
 ```
 
 Downloads:
@@ -86,16 +106,107 @@ 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
+- 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 .
 ```
+
+## 中文说明
+
+这是一个给 Codex 用的 `OpenCLI` skill，目标不是重复官方 README，而是让 agent 更稳定地完成真实任务：
+
+- 先发现本机已安装的命令面
+- 再选择站点 / 桌面应用 / CLI passthrough / adapter generation 路径
+- 默认走只读优先、结构化输出优先
+- 遇到浏览器命令时优先检查 Chrome 登录态和 Browser Bridge
+
+## 这个 skill 解决什么问题
+
+- 帮 Codex 判断什么时候该用 OpenCLI，而不是 browser agent 或 Playwright
+- 帮 Codex 在动手前先跑 `opencli list -f yaml`
+- 帮 Codex 对 B 站、知乎、小红书、微信公众号、Boss、Cursor、Codex 等场景选对命令
+- 帮 Codex 在安装版本和 README 不一致时，以本机实际命令面为准
+- 帮 Codex 在写操作前先做读操作，降低误操作风险
+
+## 仓库内容
+
+- [SKILL.md](./SKILL.md)：主 skill
+- [agents/openai.yaml](./agents/openai.yaml)：UI 元数据
+- [references/agent-playbook.md](./references/agent-playbook.md)：最短执行路径，偏 agent-first
+- [references/commands.md](./references/commands.md)：常用命令和输出格式
+- [references/china-workflows.md](./references/china-workflows.md)：中文平台和桌面应用示例
+- [references/practical-scenarios.md](./references/practical-scenarios.md)：详细实用场景手册
+- [references/troubleshooting.md](./references/troubleshooting.md)：常见故障排查
+- [examples/README.md](./examples/README.md)：可直接照抄的 prompt 和命令示例
+
+## 安装方式
+
+```bash
+git clone git@github.com:GloriaGuo/opencli-skill.git "${CODEX_HOME:-$HOME/.codex}/skills/opencli"
+```
+
+或者手动复制到：
+
+```bash
+${CODEX_HOME:-$HOME/.codex}/skills/opencli
+```
+
+## 推荐的 OpenCLI 环境准备
+
+```bash
+npm install -g @jackwener/opencli
+opencli doctor
+opencli list -f yaml
+```
+
+如果要跑浏览器类命令：
+
+- 保持 Chrome 打开
+- 先在 Chrome 中登录目标网站
+- 安装并启用 OpenCLI Browser Bridge 扩展
+
+## 快速示例
+
+公共数据：
+
+```bash
+opencli hackernews top --limit 5 -f json
+```
+
+浏览器站点：
+
+```bash
+opencli bilibili hot --limit 5 -f json
+opencli zhihu search "Android 性能优化" -f json
+```
+
+桌面应用：
+
+```bash
+opencli codex --help
+opencli codex read -f json
+opencli cursor read -f json
+opencli cursor ask "总结当前工作区最近一次对话"
+```
+
+下载：
+
+```bash
+opencli zhihu download "https://zhuanlan.zhihu.com/p/xxx" --output ./zhihu
+opencli bilibili download BV1xxx --output ./bilibili
+```
+
+## 设计原则
+
+- 优先用确定性的命令输出，而不是临场网页推理
+- 先读后写
+- 以本机安装版本的命令面为准，不盲信旧文档
+- agent 消费优先 `json`，人工查看优先 `yaml`
+- 浏览器登录态是第一优先级依赖
@@ -0,0 +1,6 @@
+# Examples
+
+This folder contains practical prompts and command recipes you can copy into Codex or run directly.
+
+- [agent-prompts.md](./agent-prompts.md): user-style prompts that should trigger the skill
+- [command-recipes.md](./command-recipes.md): reusable command recipes grouped by workflow
@@ -0,0 +1,40 @@
+# Agent Prompts
+
+These are realistic prompts that should naturally trigger the OpenCLI skill.
+
+## Discovery
+
+- Use OpenCLI to check what site adapters are available on this machine.
+- Inspect the installed OpenCLI surface and tell me whether Bilibili, Zhihu, and Codex adapters exist.
+- Use OpenCLI to troubleshoot why my browser-backed commands are returning empty data.
+
+## Browser-Backed Sites
+
+- Use OpenCLI to fetch the top 10 Bilibili hot videos as JSON.
+- Pull Zhihu search results for "Android 性能优化" through OpenCLI and summarize the top themes.
+- Use OpenCLI to search Xiaohongshu for "AI Agent" and return the first 10 results in YAML.
+- Export this Weixin article through OpenCLI and save it locally as Markdown.
+
+## Desktop Adapters
+
+- Use OpenCLI to inspect the current Codex desktop conversation and summarize it.
+- Use OpenCLI to read Cursor's current conversation and tell me what model it is using.
+- Use OpenCLI to export the current Codex thread to Markdown.
+
+## Downloads
+
+- Download this Bilibili video with OpenCLI into `./bilibili`.
+- Use OpenCLI to export a Zhihu article and download all images.
+- Download the media from this Xiaohongshu note through OpenCLI.
+
+## Adapter Development
+
+- Explore this site with OpenCLI and generate an adapter for its hot list.
+- Use OpenCLI cascade to probe the authentication strategy for this endpoint.
+
+## Chinese Prompts
+
+- 用 OpenCLI 拉一下 B 站热榜，返回 JSON。
+- 用 OpenCLI 搜索知乎里的“Android 性能优化”，先给我前 10 条。
+- 用 OpenCLI 读取当前 Codex 桌面会话并总结最近进度。
+- 用 OpenCLI 检查为什么小红书命令拿不到数据。
@@ -0,0 +1,71 @@
+# Command Recipes
+
+## 1. Environment Check
+
+```bash
+opencli doctor
+opencli list -f yaml
+```
+
+## 2. Public Data
+
+```bash
+opencli hackernews top --limit 5 -f json
+opencli google news --limit 10 -f json
+opencli wikipedia trending -f json
+```
+
+## 3. Chinese Platforms
+
+```bash
+opencli bilibili hot --limit 10 -f json
+opencli zhihu hot -f json
+opencli zhihu search "Android 性能优化" -f json
+opencli xiaohongshu search "AI Agent" --limit 10 -f yaml
+opencli weibo hot -f yaml
+opencli weixin download --url "https://mp.weixin.qq.com/s/xxx" --output ./weixin
+```
+
+## 4. Desktop Adapters
+
+```bash
+opencli codex --help
+opencli codex read -f json
+opencli codex history -f json
+opencli codex model -f json
+opencli codex export
+
+opencli cursor --help
+opencli cursor read -f json
+opencli cursor history -f json
+opencli cursor model -f json
+opencli cursor ask "Summarize the latest workspace conversation"
+opencli cursor export
+```
+
+## 5. Downloads
+
+```bash
+opencli zhihu download "https://zhuanlan.zhihu.com/p/xxx" --output ./zhihu
+opencli zhihu download "https://zhuanlan.zhihu.com/p/xxx" --download-images
+opencli xiaohongshu download abc123 --output ./xhs
+opencli bilibili download BV1xxx --output ./bilibili
+```
+
+## 6. External CLI Hub
+
+```bash
+opencli gh pr list --limit 5
+opencli docker ps
+opencli obsidian search query="AI"
+opencli gws docs list
+```
+
+## 7. Adapter Development
+
+```bash
+opencli explore https://example.com --site mysite
+opencli synthesize mysite
+opencli generate https://example.com --goal "hot"
+opencli cascade https://api.example.com/data
+```