From 9a6e157af686fcf86cb2a47e3a61ed3e962df1a5 Mon Sep 17 00:00:00 2001
From: jackwener <jakevingoo@gmail.com>
Date: Sun, 15 Mar 2026 19:28:05 +0800
Subject: [PATCH] docs: add strong AI Agent prompts to read CLI-CREATOR.md
 before creating adapters

---
 README.md       |  6 +++++-
 README.zh-CN.md |  6 +++++-
 SKILL.md        | 10 ++++++++++
 3 files changed, 20 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 7992541..d641b16 100644
--- a/README.md
+++ b/README.md
@@ -112,6 +112,9 @@ opencli bilibili hot -v         # Verbose: show pipeline steps
 
 ## 🧠 AI Agent Workflow
 
+> [!IMPORTANT]
+> AI Agent 创建新适配器时，**必须先阅读 [CLI-CREATOR.md](./CLI-CREATOR.md)**，其中包含完整的浏览器探索工作流、认证策略决策树和调试指南。
+
 ```bash
 # 1. Deep Explore — discover APIs, infer capabilities, detect framework
 opencli explore https://example.com --site mysite
@@ -134,7 +137,8 @@ Explore outputs to `.opencli/explore/<site>/`:
 
 ## 🔧 Create New Commands
 
-See **[CLI-CREATOR.md](./CLI-CREATOR.md)** for the full adapter guide (YAML pipeline + TypeScript).
+> [!CAUTION]
+> **🚨 必须先阅读 [CLI-CREATOR.md](./CLI-CREATOR.md)！** 它是适配器开发的完全指南，包含 API 发现工作流、5 级认证策略、平台 SDK 参考、YAML/TS 选择决策树、`tap` 调试流程和常见陷阱。**跳过此文档直接写代码会导致大量可避免的错误。**
 
 ## Releasing New Versions
 
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 7a37a60..a318197 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -113,6 +113,9 @@ opencli bilibili hot -v         # 详细模式：展示 pipeline 每步数据
 
 ## 🧠 AI Agent 工作流
 
+> [!IMPORTANT]
+> AI Agent 创建新适配器时，**必须先阅读 [CLI-CREATOR.md](./CLI-CREATOR.md)**，其中包含完整的浏览器探索工作流、认证策略决策树和调试指南。
+
 ```bash
 # 1. Deep Explore — 网络拦截 → 响应分析 → 能力推理 → 框架检测
 opencli explore https://example.com --site mysite
@@ -135,7 +138,8 @@ opencli cascade https://api.example.com/data
 
 ## 🔧 创建新命令
 
-查看 **[CLI-CREATOR.md](./CLI-CREATOR.md)** 了解完整的适配器开发指南（YAML pipeline + TypeScript）。
+> [!CAUTION]
+> **🚨 必须先阅读 [CLI-CREATOR.md](./CLI-CREATOR.md)！** 它是适配器开发的完全指南，包含 API 发现工作流、5 级认证策略、平台 SDK 参考、YAML/TS 选择决策树、`tap` 调试流程和常见陷阱。**跳过此文档直接写代码会导致大量可避免的错误。**
 
 ## 版本发布
 
diff --git a/SKILL.md b/SKILL.md
index 299f6ff..4023aee 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -10,6 +10,11 @@ tags: [cli, browser, web, mcp, playwright, bilibili, zhihu, twitter, github, v2e
 
 > Make any website your CLI. Reuse Chrome login, zero risk, AI-powered discovery.
 
+> [!CAUTION]
+> **🚨 AI Agent 必读：创建或修改任何适配器之前，你必须先阅读 [CLI-CREATOR.md](./CLI-CREATOR.md)！**
+> 该文档包含完整的 API 发现工作流（必须使用 Playwright MCP Bridge 浏览器探索）、5 级认证策略决策树、平台 SDK 速查表、`tap` 步骤调试流程、分页 API 模板、级联请求模式、以及常见陷阱。
+> **本文件（SKILL.md）仅提供命令参考和简化模板，不足以正确开发适配器。**
+
 ## Install & Run
 
 ```bash
@@ -174,6 +179,11 @@ opencli bilibili hot -v         # Show each pipeline step and data flow
 
 ## Creating Adapters
 
+> [!IMPORTANT]
+> **STOP — 在写任何代码之前，先阅读 [CLI-CREATOR.md](./CLI-CREATOR.md)。**
+> 它包含：① AI Agent 浏览器探索工作流（必须用 Playwright MCP 抓包验证 API）② 认证策略决策树 ③ 平台 SDK（如 Bilibili 的 `apiGet`/`fetchJson`）④ YAML vs TS 选择指南 ⑤ `tap` 步骤调试方法 ⑥ 级联请求模板 ⑦ 常见陷阱表。
+> **下方仅为简化模板参考，直接使用极易踩坑。**
+
 ### YAML Pipeline (declarative, recommended)
 
 Create `src/clis/<site>/<name>.yaml`: