夜雨聆风为了真正理解 Skill 的设计思路，博主找到了一个 从真实问题中生长出来 的 Skill —— wechat-article-viewer，专门解决 “AI 抓不到微信公众号文章正文” 这个痛点。
本文将 完整还原 这个 Skill 的诞生过程，让你看到它是如何一步步被设计出来的。
1.第一步：问题发现 —— 为什么 AI 读不了微信文章？ 1.1 现象 1.2 问题诊断（这是最关键的一步） 1.3 设计思路的核心转变 2.第二步：资源规划 —— 这个 Skill 需要什么？ 2.1 Skill 结构设计 2.2 关键能力清单 3.第三步：编写 SKILL.md —— Skill 的 “说明书” 3.1 前置元数据（frontmatter） 3.2 触发条件（When to Run） 3.3 执行流程（Workflow） —— 这是核心中的核心 3.4 输出格式（Output Format） 4.第四步：编写执行代码（scripts/） 4.1 浏览器连接检查函数（关键设计） 4.2 主执行函数 5.第五步：设计思路总结 —— 这个 Skill 好在哪里？ 5.1 核心设计原则（对照检查） 5.2 这个 Skill 的设计流程图 6.第六步：你可以复用的设计模式 模式 1：环境检查模式 模式 2：渐进式加载模式 模式 3：降级方案模式 7.第七步：举一反三 —— 每日新闻 Skill 如何借鉴？ 8.总结：Skill 设计的 “心法”
1.第一步：问题发现 —— 为什么 AI 读不了微信文章？
1.1 现象
当用户丢给 AI 一条微信公众号文章链接时，普通的网页抓取工具（如 web_fetch）只能返回 “继续滑动看下一个” 等提示文字，正文完全为空。
1.2 问题诊断（这是最关键的一步）
经过分析，发现微信文章有 三层防御机制：
| 第一层：Cookie 鉴权 | wap_sid2 Cookie（用户登录微信网页版时下发） | web_fetch |
| 第二层：动态渲染 | web_fetch | |
| 第三层：反爬策略 | web_fetch |
1.3 设计思路的核心转变
“❓既然问题是 “用接口抓不到”，那解决方案就是：用真正的浏览器去渲染页面。
”
这就是 Skill 设计的起点 —— 不是堆叠提示词，而是找到正确的技术路径。
2.第二步：资源规划 —— 这个 Skill 需要什么？
在动手写代码之前，先想清楚 Skill 的 “骨架”。
2.1 Skill 结构设计
wechat-article-viewer/ # 技能目录├── SKILL.md # 核心说明书（告诉 AI 怎么用）├── scripts/ # 可执行脚本│ └── fetch_article.js # 实际抓取逻辑├── references/ # 参考文档│ └── browser_setup.md # 浏览器配置说明└── assets/ # 资源文件（本例不需要）
2.2 关键能力清单
1️⃣ 浏览器连接检查：确保有可用的 Chrome / Chromium 实例 2️⃣ 页面渲染等待：等待 JS 加载完成 3️⃣ 内容提取：从渲染后的 DOM 中提取标题、作者、正文 4️⃣ 错误处理：Cookie 过期、网络问题等场景的友好提示
3.第三步：编写 SKILL.md —— Skill 的 “说明书”
SKILL.md 是整个 Skill 的核心，它不写代码，但告诉 AI 什么时候该用这个 Skill、怎么用。
3.1 前置元数据（frontmatter）
---name: wechat-article-viewerdescription: >微信公众号文章完整阅读器。Use when: 用户提供 mp.weixin.qq.com 链接，需要阅读/总结文章内容。NOT for: 非微信链接的普通网页、需要登录的付费文章。---
为什么需要 NOT for？
“✨ 这是为了防止 AI 在错误场景下调用这个 Skill。比如用户给了一个知乎链接，AI 就不该用微信阅读器去处理。
”
3.2 触发条件（When to Run）
## When to Run- 用户消息中包含 `mp.weixin.qq.com` 链接- 用户说“帮我读一下这篇公众号”“总结这篇文章”- 用户分享微信公众号文章并要求分析内容
3.3 执行流程（Workflow） —— 这是核心中的核心
## Workflow### Step 1: 检查浏览器环境检查本地是否有带调试端口的 Chrome 实例运行（默认端口 9222）：- 如果没有运行，提示用户启动方式：```/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \--remote-debugging-port=9222 \--user-data-dir=/tmp/chrome-debug-profile```### Step 2: 连接浏览器并打开链接使用 Puppeteer 或 Chrome DevTools Protocol 连接到浏览器：- 打开目标 URL- 等待页面加载完成（等待 `.rich_media_content` 元素出现）### Step 3: 提取内容从渲染后的页面中提取：- 标题：`.rich_media_title`- 作者：`.profile_nickname`- 发布时间：`.publish_time`- 正文：`.rich_media_content`### Step 4: 返回结构化结果将提取的内容按以下格式返回给用户
3.4 输出格式（Output Format）
## Output Format📰 **{标题}**✍️ 作者：{作者}📅 发布时间：{发布时间}---{正文内容（自动分段）}---🔗 原文链接：{url}
4.第四步：编写执行代码（scripts/）
4.1 浏览器连接检查函数（关键设计）
这里有一个容易被忽略的细节：连接检查不是简单的 true/false，而是分层诊断。
// scripts/check_browser.jsfunction checkBrowserConnection() {// 返回详细的连接状态，而不是简单的 true/falseconst status = {connected: false,has_debug_port: false,has_wechat_login: false,user_guidance: ""};// 1. 调试端口是否可连接？if (!isPortOpen("localhost", 9222)) {status.user_guidance = "请先启动带调试端口的 Chrome，命令见文档";return status;}status.has_debug_port = true;// 2. 浏览器是否能正常通信？try {const browser = connectToBrowser(9222);status.has_debug_port = true;} catch (e) {status.user_guidance = "浏览器端口已占用但无法连接，请关闭其他调试进程";return status;}// 3. 浏览器里有没有微信登录态？if (!checkWechatCookie(browser)) {status.user_guidance = "请在浏览器中先登录微信网页版 (https://wx.qq.com)";return status;}status.has_wechat_login = true;status.connected = true;return status;}
为什么这样设计？
“✨ 用户遇到问题时，不是技术专家，需要明确的指引。分层诊断可以告诉用户 “
”你现在卡在哪一步”，以及 “下一步该做什么”。
4.2 主执行函数
// scripts/index.jsexport default async function run(action, params) {try {// 1. 参数校验const { url } = params;if (!url || !url.includes('mp.weixin.qq.com')) {return {success: false,message: "请提供有效的微信公众号文章链接"};}// 2. 检查浏览器环境const browserStatus = checkBrowserConnection();if (!browserStatus.connected) {return {success: false,message: browserStatus.user_guidance,retryable: true // 告诉用户配置后可以重试};}// 3. 抓取并渲染const article = await fetchAndRenderArticle(url);// 4. 返回结果return {success: true,data: article};} catch (error) {return {success: false,message: `执行失败：${error.message}`};}}
5.第五步：设计思路总结 —— 这个 Skill 好在哪里？
5.1 核心设计原则（对照检查）
| 单一职责 | |
| 渐进式披露 | |
| 错误友好 | |
| 可复用 | |
| 工程化 | 浏览器连接检查” 这种复杂逻辑封装成可复用函数 |
5.2 这个 Skill 的设计流程图
6.第六步：你可以复用的设计模式
从这个 Skill 中，可以提炼出 三种通用设计模式，你以后写 Skill 可以直接套用：
模式 1：环境检查模式
适用于任何需要特定环境的 Skill（数据库、浏览器、API 服务等）：
## Workflow1. 检查环境是否就绪2. 如未就绪，返回清晰配置指引3. 如已就绪，执行核心任务
模式 2：渐进式加载模式
SKILL.md 中只放 “触发条件” 和 “简要流程”，复杂逻辑放 scripts/：
## Workflow执行 `scripts/xxx.js` 获取数据
模式 3：降级方案模式
主方案失败时提供备选方案：
## Workflow1. 尝试方案 A（最快）2. 如果失败，尝试方案 B（更稳定但更慢）3. 如果仍失败，返回错误指引
7.第七步：举一反三 —— 你的每日新闻 Skill 如何借鉴？
如果需要设计一个 “每日热点新闻 Skill”，可以参考 wechat-article-viewer 的设计思路：
| 问题发现 | |
| 资源规划 | |
| SKILL.md | Use when” 和 “NOT for”，避免被误触发 |
| 执行代码 | |
| 错误处理 | |
| 输出格式 |
8.总结：Skill 设计的 “心法”
通过拆解 wechat-article-viewer，我们可以总结出设计一个好 Skill 的 五步心法：
发现问题：找到 AI 基础能力搞不定的具体场景 诊断根因：不是 “为什么不行”，而是 “技术上卡在哪” 设计流程：把解决方案拆成可执行的步骤 封装成 Skill：用 SKILL.md 描述规则 + 用 scripts 实现逻辑 沉淀复用：让经验变成可继承的工程资产
“✨正如一位开发者所说：“Skill 带来的真正改变，不是 ‘这次成功了’，而是经验不再是一次性的，它沉淀成了可继承的能力。”
”
