为了真正理解 Skill 的设计思路，博主找到了一个 从真实问题中生长出来 的 Skill —— wechat-article-viewer，专门解决 “AI 抓不到微信公众号文章正文” 这个痛点。

本文将 完整还原 这个 Skill 的诞生过程，让你看到它是如何一步步被设计出来的。

1.第一步：问题发现 —— 为什么 AI 读不了微信文章？

1.1 现象

当用户丢给 AI 一条微信公众号文章链接时，普通的网页抓取工具（如 web_fetch）只能返回 “继续滑动看下一个” 等提示文字，正文完全为空。

1.2 问题诊断（这是最关键的一步）

经过分析，发现微信文章有 三层防御机制：

防御层级	技术原理	为什么普通抓取失败
第一层：Cookie 鉴权	微信要求请求携带有效的 wap_sid2 Cookie（用户登录微信网页版时下发）	web_fetch 默认不带 Cookie，直接被服务端拒绝
第二层：动态渲染	正文由 JavaScript 动态加载，通过独立 API 获取后再插入 DOM	web_fetch 只获取 HTML 骨架，不执行 JS，拿不到内容
第三层：反爬策略	检测 User-Agent、Referer 等请求头，非浏览器请求会被拦截	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-viewer
description: >
  微信公众号文章完整阅读器。
  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.js
function checkBrowserConnection() {
  // 返回详细的连接状态，而不是简单的 true/false
  const 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.js
export 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 核心设计原则（对照检查）

原则	wechat-article-viewer 如何体现
单一职责	只做一件事：读取微信文章，不掺和其他功能
渐进式披露	SKILL.md 先给触发条件，匹配后再加载完整执行逻辑
错误友好	每步失败都有明确指引，不是简单报错
可复用	解决了一次，以后所有用户都能直接用
工程化	把 “浏览器连接检查” 这种复杂逻辑封装成可复用函数

5.2 这个 Skill 的设计流程图

6.第六步：你可以复用的设计模式

从这个 Skill 中，可以提炼出 三种通用设计模式，你以后写 Skill 可以直接套用：

模式 1：环境检查模式

适用于任何需要特定环境的 Skill（数据库、浏览器、API 服务等）：

## Workflow
1. 检查环境是否就绪
2. 如未就绪，返回清晰配置指引
3. 如已就绪，执行核心任务

模式 2：渐进式加载模式

SKILL.md 中只放 “触发条件” 和 “简要流程”，复杂逻辑放 scripts/：

## Workflow
执行 `scripts/xxx.js` 获取数据

模式 3：降级方案模式

主方案失败时提供备选方案：

## Workflow
1. 尝试方案 A（最快）
2. 如果失败，尝试方案 B（更稳定但更慢）
3. 如果仍失败，返回错误指引

7.第七步：举一反三 —— 你的每日新闻 Skill 如何借鉴？

如果重新设计 “每日热点新闻 Skill”，可以参考 wechat-article-viewer 的设计思路：

设计阶段	你的 Skill 可以怎么做
问题发现	新闻来源可能不稳定（API 限流、RSS 失效）
资源规划	需要多源备份：Hacker News API → GitHub Trending → RSS 备选
SKILL.md	明确写 “Use when” 和 “NOT for”，避免被误触发
执行代码	需要环境检查（网络是否通、API Key 是否存在）
错误处理	某个源失败时，自动切换到备用源
输出格式	固定格式，让 AI 每次都输出一致的日报样式

8.总结：Skill 设计的 “心法”

通过拆解 wechat-article-viewer，我们可以总结出设计一个好 Skill 的 五步心法：

• 发现问题：找到 AI 基础能力搞不定的具体场景
• 诊断根因：不是 “为什么不行”，而是 “技术上卡在哪”
• 设计流程：把解决方案拆成可执行的步骤
• 封装成 Skill：用 SKILL.md 描述规则 + 用 scripts 实现逻辑
• 沉淀复用：让经验变成可继承的工程资产

✨正如一位开发者所说：“Skill 带来的真正改变，不是 ‘这次成功了’，而是经验不再是一次性的，它沉淀成了可继承的能力。”