大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。



你会在这里看到：

• 如何从一个真实需求抽象出 Skill
• 如何设计目录结构
• 如何写 SKILL.md
• 如何拆分 references/、scripts/、assets/
• 如何做验证和迭代
• 一个贴近 MediaCrawler 场景的完整案例

很多人写 Skill 失败，不是因为 Markdown 不会写，而是因为一开始就做错了两件事：

• 还没搞清楚任务边界，就开始写
• 还没沉淀出稳定流程，就急着抽象

因此，实战第一步不是开文件，而是先判断：

• 这个任务是否值得做成 Skill
• 它的触发条件是什么
• 它的核心流程能否说清楚
• 哪些步骤应该交给脚本

下面给出一套可直接复用的工作流。

3.1 第一步：定义目标

先用一句话说明这个 Skill 要解决什么问题。

一个不好的目标定义：

处理网页相关任务

这个目标太大了，没有边界。

一个更好的目标定义：

把采集结果中的脏 HTML、空 Markdown、缺失元信息和不规范链接修复成结构化输出

这个定义有几个优点：

• 有明确输入问题
• 有明确输出方向
• 能看出任务边界

3.2 第二步：确认触发词和典型请求

不要直接写 description，先列真实请求。

例如，一个“采集结果后处理”类 Skill，典型请求可能包括：

• 帮我把这批抓取结果清洗一下
• 这个页面抽出来的 Markdown 是空的，修一下
• 把 HTML 提取结果规范成统一 JSON
• 把链接、标题、摘要补齐
• 修复这份 crawler 输出

把这些真实表达收集出来之后，再回写进 description，触发率会高很多。

3.3 第三步：划定边界

一个 Skill 必须同时知道“自己做什么”和“自己不做什么”。

例如，对于“采集结果后处理”来说，可以明确：

负责：

• 结果清洗
• 元信息补全
• 输出规范化
• 格式修复

不负责：

• 网站登录
• 页面交互录制
• 深度反爬对抗
• 全新的爬虫编写

边界不清，后面一定会膨胀。

3.4 第四步：设计目录结构

你可以先按下面这个骨架搭出来：

your-skill/ ├── SKILL.md ├── references/ │ ├── fields.md │ └── edge_cases.md ├── scripts/ │ └── normalize_output.py ├── assets/ │ └── output_template.md └── agents/ └── openai.yaml 

3.5 第五步：先写 description，再写正文

很多人习惯先堆正文，最后随手补一个 description。
这个顺序往往是反的。

正确做法是：

1. 先想清楚触发条件
2. 先写 name 和 description
3. 再写正文流程

因为 Skill 能不能被准确调用，第一关就是元数据。

3.6 第六步：把正文压缩成“核心执行说明”

SKILL.md 正文不要写成百科。
它只负责说清楚：

• 目标
• 推荐流程
• 关键规则
• 何时读取哪些资源

3.7 第七步：把详细知识下沉到 references/

例如这些内容更适合放进 references/：

• 字段定义表
• 各平台差异
• 大量异常样例
• 长篇接口说明
• 各种边界场景说明

3.8 第八步：把可重复操作下沉到 scripts/

例如：

• 链接规范化
• Markdown 清洗
• JSON 字段修复
• 批量结果合并
• 结构校验

如果你发现某段逻辑每次都要手写，通常就该脚本化了。

3.9 第九步：设计验证步骤

Skill 写完以后，至少要测试三件事：

1. 会不会触发
2. 触发后会不会按预期执行
3. 输出是否稳定

最少也应该准备 3 到 5 条真实请求做回放。

下面给出一个通用模板。你可以把它作为起点。

--- name: your-skill-name description: Describe exactly what this skill does, when it should be used, and which user requests should trigger it. Include concrete actions, artifacts, and failure symptoms. Use when asked to perform this category of task. --- # Your Skill Title Overview Describe the goal, scope, and non-goals of this skill in a few paragraphs. Workflow 1. Inspect the input and identify the task subtype. 2. Read the minimum required references. 3. Execute the recommended process. 4. Run validation checks. 5. Return the result in the required format. Rules - Prefer the simplest reliable path. - Do not duplicate information already present in the input. - Use scripts for deterministic transforms. - Stop and surface blockers clearly when required input is missing. Resources - Read `references/fields.md` when field mapping is needed. - Read `references/edge_cases.md` when output is malformed or incomplete. - Run `scripts/normalize_output.py` when normalization is required. 

这个模板的重点不在于格式漂亮，而在于结构完整。

5.1 写清输入

例如：

• 输入可能是单个 HTML
• 可能是抓取后的 JSON
• 可能是空 Markdown + 原始 HTML
• 可能是失败日志

如果不写清输入，代理就不知道该从哪里开始。

5.2 写清输出

例如：

• 返回清洗后的 Markdown
• 返回规范化 JSON
• 返回错误原因和修复建议
• 返回修复后的结果文件路径

5.3 写清检查点

例如：

• 标题是否为空
• 链接是否为绝对路径
• Markdown 是否非空
• 时间字段是否规范
• 摘要是否重复标题

没有检查点，执行就很容易飘。

5.4 写清失败分支

例如：

• 如果没有 HTML，只能基于现有字段修补
• 如果标题和正文都为空，必须返回失败原因
• 如果链接无法解析，要保留原值并标记问题

这一节给出一个接近真实项目的完整案例。

6.1 场景

在 MediaCrawler 这类项目中，经常会遇到这些情况：

• 页面抓到了，但 Markdown 为空
• HTML 有了，但文本提取质量差
• 标题、时间、摘要、作者字段缺失
• 链接是相对路径或格式不统一
• 输出 JSON 结构在不同站点间不一致

这些问题适合沉淀成一个 Skill，例如：

crawl-output-postprocess

6.2 目标

这个 Skill 的目标可以定义为：

对原始采集结果进行修复、清洗、补全和标准化，输出更稳定的 Markdown 或 JSON。

6.3 推荐目录结构

crawl-output-postprocess/ ├── SKILL.md ├── references/ │ ├── field_rules.md │ ├── markdown_fallback.md │ └── common_failures.md ├── scripts/ │ ├── normalize_links.py │ └── validate_output.py └── assets/ └── normalized_result_template.json 

6.4 一个示例 SKILL.md

---
name: crawl-output-postprocess
description: Clean and repair crawler output into usable Markdown or normalized JSON. Use when extracted markdown is empty, HTML is noisy, metadata is incomplete, links need normalization, or crawl results must be standardized before downstream use.
---

# Crawl Output Postprocess

 Overview

Use this skill to repair partially extracted crawl results. Focus on recovering non-empty markdown, normalizing metadata, cleaning links, and producing consistent output structures.

 Workflow

1. Inspect available inputs: markdown, html, title, summary, author, publish time, url.
2. If markdown is empty, recover content from HTML or visible text signals.
3. Normalize metadata fields and link formats.
4. Validate required fields and report any unrecoverable gaps.
5. Return cleaned markdown or normalized JSON.

 Rules

- Prefer preserving source meaning over aggressive rewriting.
- Do not fabricate metadata without clear evidence.
- Use scripts for link normalization and structure validation.
- If a field cannot be recovered, keep it empty and explain why.

 Resources

- Read `references/markdown_fallback.md` when markdown is empty.
- Read `references/field_rules.md` when metadata mapping is unclear.
- Read `references/common_failures.md` when output symptoms are unusual.
- Run `scripts/normalize_links.py` for URL normalization.
- Run `scripts/validate_output.py` before finalizing normalized JSON.

这个例子里，真正关键的是四件事：

• 触发场景写清楚了
• 工作流顺序清楚
• 不该瞎编的数据明确禁止编造
• 详细知识和脚本入口都明确了

6.5 references/ 里应该放什么

例如，references/field_rules.md 可以写：

• 各字段的优先级
• 标题和摘要冲突时怎么选
• 发布时间的格式要求
• 作者字段的识别规则
• 标签、来源、栏目等可选字段映射

references/markdown_fallback.md 可以写：

• Markdown 为空时的恢复策略
• 如何从标题、段落、列表恢复正文结构
• 如何跳过导航栏、页脚、推荐内容
• 哪些 HTML 区块优先保留

references/common_failures.md 可以写：

• 空正文
• 标题重复
• 摘要污染
• 链接格式异常
• 时间字段乱码

6.6 scripts/ 里应该放什么

scripts/normalize_links.py 适合负责：

• 相对路径转绝对路径
• 去掉明显无用参数
• 标准化协议和主机名

scripts/validate_output.py 适合负责：

• 检查关键字段是否存在
• 检查 JSON 结构是否合规
• 检查 Markdown 是否为空
• 输出明确的验证失败原因

6.7 这个 Skill 怎么被实际使用

假设用户发来下面这些请求：

• 这批 crawler 结果里的 markdown 都是空的，帮我修一下
• 把采集结果清洗成统一 JSON
• 这份 HTML 提取结果很脏，整理一下
• 修复一下这条抓取记录的标题、摘要和链接

这些请求都很容易命中上面的 description。

命中后，代理通常会按这个顺序工作：

1. 先检查输入里有什么
2. 判断是不是“空 Markdown”还是“元信息脏”
3. 读对应参考资料
4. 运行需要的脚本
5. 输出修复结果
6. 给出校验结论

7.1 准备一组代表性样本

至少准备下面几类：

• 正常样本
• 空字段样本
• 脏 HTML 样本
• 相对链接样本
• 格式错乱样本

7.2 准备一组真实请求

• 清洗这批采集结果
• 修复 markdown
• 规范化输出
• 补齐元信息
• 把这个页面结果整理一下

7.3 看三个结果

验证时重点看：

1. 会不会触发
2. 触发后会不会按预期走流程
3. 输出结果是否稳定、可复现

7.4 常见失败症状

症状一：根本没触发

通常说明：

• description 太泛
• 没写动作词
• 没写使用场景

症状二：触发了，但做得很散

通常说明：

• 工作流不够清楚
• 缺少检查点
• 该脚本化的步骤没有脚本化

症状三：内容很长，但没帮助

通常说明：

• SKILL.md 塞了太多背景
• 缺少真正可执行的规则
• 详细知识没有下沉到 references/

一个成熟 Skill 往往不是一次写成，而是几轮迭代出来的。

你可以用下面的方式更新它：

8.1 先记录失败样本

每当出现：

• 未触发
• 误触发
• 输出不稳定
• 某类边界场景处理差

都应该记下真实请求和失败症状。

8.2 判断问题属于哪一层

通常只会落在这几层之一：

• 元数据层：触发不准
• 主体层：流程不清
• 参考层：知识不够
• 脚本层：确定性步骤没托住

8.3 按层修，不要乱修

例如：

• 触发问题，改 description
• 知识问题，补 references/
• 稳定性问题，补 scripts/
• 输出格式问题，补校验步骤

不要一出问题就把所有内容都往 SKILL.md 里塞。

在真实项目里，Skill 常见的用法大概有四类。

9.1 作为固定流程的封装

例如：

• 某平台采集流程
• 自动化测试录制流程
• 数据清洗流程

9.2 作为项目知识入口

例如：

• 某类字段定义
• 某业务模块规则
• 某类异常的排查顺序

9.3 作为团队经验沉淀

当一个任务靠“老同事经验”才能做对时，就很适合做成 Skill。

9.4 作为模型与脚本之间的调度层

如果你准备长期维护 Skills，可以采用下面这套方式：

1. 每个 Skill 只做一类明确事情
2. 每次改动都基于真实失败样本
3. SKILL.md 只保留核心流程
4. 详细知识统一沉到 references/
5. 可计算步骤持续脚本化
6. 每个 Skill 都维护一组最小验证样本

在你把一个 Skill 交付出去之前，可以对照下面这份清单：

• name 是否短而清晰
• description 是否明确写了用途和触发条件
• SKILL.md 是否只保留核心执行逻辑
• 详细知识是否拆到了 references/
• 重复步骤是否拆到了 scripts/
• 是否写了输入、输出、检查点和失败分支
• 是否准备了多条真实请求做验证
• 是否准备了多类边界样本做验证

对于 MediaCrawler 这种项目，我更推荐你优先沉淀下面几类 Skill：

• 平台适配类
  比如某站的页面结构识别、字段抽取、异常处理。
  
  
  
• 输出后处理类
  比如 Markdown 修复、HTML 清洗、链接规范化、摘要补全。
  
  
  
• 自动化验证类
  比如采集流程回放、站点登录录制、结果断言。
  
  
  
• 异常排查类
  比如某类抓取失败的定位顺序、日志检查顺序、重试策略。
  
  
  

这些方向都非常适合做成可复用 Skill，而且跟你的项目场景贴合度高。

如果你准备真正开始写第一个 Skill，建议按下面顺序来，不要反过来：

1. 先挑一个重复出现的小任务
2. 先拿真实样本总结流程
3. 先写清触发条件
4. 再写 SKILL.md
5. 再补 references/ 和 scripts/
6. 最后用真实请求回放验证

这样做，成功率最高。

Skill 的落地，关键不在于会不会写 Markdown，而在于是否能把一个重复任务抽象成：

• 清楚的触发条件
• 稳定的执行流程
• 合理拆分的资源层
• 可验证、可迭代的执行单元