解决方案 by llj1998

反向学习别人的优秀 Skill（拆解、提炼方法论）

skill-web-profiler

把任意一个 Skill 文件夹，变成一份自包含的中文学习与拆解网页。

输出结果预览：
https://lingjie.li/2/pages/skill-web-profiler-profile/

开源链接：
https://github.com/llj1998/skill-web-profiler

它是什么

skill-web-profiler 是一个 Skill（Claude Code / Codex 的扩展能力包），作用是 拆解另一个 Skill。

给它指定一个 Skill 文件夹，它会输出一份本地 HTML 网页，包含：

  • 这个 Skill 是做什么的、什么时候用、什么时候不用
  • 核心原则、硬规则、红线、Fallback 路线
  • 工作流地图 + 详细可执行步骤
  • 文件组成 / References / Scripts / Assets 全量导读
  • 学习路径（30 分钟 / 2 小时 / 1 天）、决策树、Prompt 模板、Checklists、术语表、练习题
  • 完整原文档案（所有文本文件全文，可搜索、分组过滤、SKILL.md 默认置顶）

一句话：让别人读你的 Skill 像读一本中文教科书，而不是读一堆 Markdown 源码。

为什么写这个 Skill

读 Skill 源码是低效的：SKILL.md 是写给模型看的指令，不是写给人学习用的教材。

直接让 AI 总结又会丢失关键约束（红线、fallback、验证步骤），变成营销话术。

skill-web-profiler 的核心理念是 正文学习层 + 完整档案层 双层并存：

层负责什么长什么样
正文学习层让人 学会中文讲解、决策树、checklist、练习题
完整档案层保证 不漏原文所有文本文件全文，可搜索

正文不能替代档案，档案也不能替代正文 —— 二者缺一不可。

适用场景

✅ 适合

  • 给团队/社区做一份 Skill 说明手册
  • 反向学习别人的优秀 Skill（拆解、提炼方法论）
  • 给自己写的 Skill 做”对外说明书”
  • 把 Skill 内容做成可搜索的知识库

❌ 不适合

  • 给一份普通 Markdown 文档生成网页（请用 mkdocs / docsify）
  • 自动总结网页内容（请用其它摘要工具）
  • 给非 Skill 结构的代码项目做文档

安装

方式一：放进个人 Skills 目录

Claude Code:

# Windows
copy /E /I skill-web-profiler "%USERPROFILE%\.claude\skills\skill-web-profiler"

# macOS / Linux
cp -r skill-web-profiler ~/.claude/skills/skill-web-profiler

Codex:

cp -r skill-web-profiler ~/.codex/skills/skill-web-profiler

重启 Claude Code / Codex，输入 /skill-web-profiler 即可触发。

方式二：项目内 Skill

直接 clone 到项目根目录的 .claude/skills/ 或 .codex/skills/ 下。

快速使用

在 Claude Code / Codex 内（推荐）

直接告诉它：

用 skill-web-profiler 拆解 ~/.claude/skills/huashu-design

或更简单：

/skill-web-profiler huashu-design

模型会自动定位 Skill、读取必要文件、调用生成器、本地预览。

直接调脚本（不依赖模型）

python skill-web-profiler/scripts/generate_skill_website.py ^
  --skill "C:\Users\you\.claude\skills\target-skill" ^
  --out "D:\output\target-skill-profile" ^
  --title "Target Skill 完全学习手册"
# macOS / Linux
python skill-web-profiler/scripts/generate_skill_website.py \
  --skill "$HOME/.claude/skills/target-skill" \
  --out "./output/target-skill-profile" \
  --title "Target Skill 完全学习手册"

输出目录会包含：

target-skill-profile/
├── index.html        # 主页面
├── styles.css        # 样式
├── app.js            # 交互逻辑（搜索、目录、过滤）
├── archive.js        # 完整原文档案数据
└── skill-media/      # 图片资源预览（如有）

用任意静态服务器打开即可：

cd target-skill-profile
python -m http.server 8000
# 浏览器打开 http://localhost:8000

输出网页结构（21 栏）

#栏目作用
1这个 Skill 是什么定位、适用、不适用
2一句话心法一句话抓住精华
3核心原则硬规则提炼
4工作流地图阶段、路线、输入输出
5详细步骤可执行展开
6关键协议强制流程
7Fallback 路线资料/工具缺失时怎么办
8能力模式不同任务的角色切换
9专项规则场景化规则
10反模式细则错误行为对照
11异常处理路径/网络/脚本失败
12技术红线交付硬要求
13文件组成根文件导读
14References 路由什么时候读什么
15Scripts 工具链脚本用途和参数
16Assets / Demos资源、模板、示例
17红线与限制汇总禁止事项
18如何使用用户视角调用方式
19精华提炼可迁移方法论
20学习工具箱学习路径 / 决策树 / 模板 / 练习题
21完整原文档案全文可搜索（SKILL.md 默认置顶）

项目结构

skill-web-profiler/
├── SKILL.md                          # Skill 入口（写给模型看的指令）
├── README.md                         # 你正在读的这份
├── LICENSE                           # MIT
├── CHANGELOG.md                      # 版本记录
├── agents/
│   └── openai.yaml                   # Codex / OpenAI 兼容元数据
├── references/
│   ├── extraction-guide.md           # 抽取规则：如何从原 Skill 抽规则
│   └── website-blueprint.md          # 网页蓝图：21 栏信息架构
├── scripts/
│   └── generate_skill_website.py     # 主生成器（确定性，单文件）
└── assets/                           # 预留资源目录

设计哲学

读源码即可，但摘要这里给三条最关键的：

1. 抽取不是复制

不允许在正文出现 **粗体源码**、# 标题结构：...、Markdown 碎片。
原文必须先 理解 → 归类 → 改写成中文教学文案，再放入正文。
原文全文放 archive，给读者搜索和核对。

2. 正文学习化 + 档案完整化 双层并存

  • 正文不能替代档案：人需要核对原文
  • 档案不能替代正文：人不会读 Markdown 源码学习

3. 修生成器，不要手写一次性页面

生成器是确定性的。如果某个 Skill 拆出来不好看，改 generate_skill_website.py，让所有 Skill 都受益，不要手改某一个 HTML。

与同类工具的区别

工具输入输出重点
skill-web-profilerSkill 文件夹中文学习手册网页教学 + 完整档案
mkdocs / docsifyMarkdown 仓库文档站渲染
各类 AI 总结工具任意文本摘要压缩
GitHub README单文件项目首页入口

skill-web-profiler 的特殊点是只针对 Skill 这种结构（SKILL.md + references/ + scripts/ + assets/），所以能针对性地做”什么时候读什么 reference”、”脚本怎么用”、”资源在哪”这类导读。

路线图

  • [ ] 支持英文 / 双语输出
  • [ ] 提供在线 demo 站点（拆几个常用开源 Skill 作为示例）
  • [ ] 支持暗色模式持久化
  • [ ] 增加 PDF 导出
  • [ ] 兼容 Cursor / Continue / Cline 等工具的 skill-like 配置

欢迎 PR / Issue。

贡献

  1. Fork 本仓库
  2. 改 scripts/generate_skill_website.py（核心逻辑）或 references/*.md（规则文档）
  3. 用一个真实 Skill 测试生成结果
  4. 提 PR，说明改了什么、用哪个 Skill 测的

改动指南：

  • 修排版/样式 → 改生成器里嵌入的 CSS
  • 修信息架构 → 同时改 references/website-blueprint.md 和生成器
  • 修抽取规则 → 改 references/extraction-guide.md 和 SKILL.md
  • 不要直接 commit 某个 Skill 的生成产物

致谢

  • 灵感来自手工写 Skill 学习页的实践 —— 想把这件事自动化
  • 信息架构参考了产品设计手册和技术文档双路线
  • 感谢 Claude Code 和 Codex 团队提供的 Skill 框架

发表回复