企业官网建设流程全解析

yao-open-skills 是一个面向 AI Agent 的公开 Skill 合集，目前收录了 15 个可复用的 AI 资产，覆盖决策分析、商业研究、教程生产和安全治理。这个仓库没有复杂框架，真正支撑它运转的，是一张 JSON 登记表 registry/skills.json 和一组 Python 自动化脚本——收录、登记、目录生成、同步状态维护，全部围绕这两样东西展开。

这篇文章带你拆解它的幕后机制：为什么一张 JSON 表能管住 15 个 Skill？README 目录表为什么不用手写？新 Skill 从"决定公开"到"上线展示"要经过哪几步？

📋 仓库定位：精选合集，不是全量镜像

先纠正一个常见误解：yao-open-skills不是作者本地 Skill 工作区的完整备份，而是一个精选的公开合集。

它只收录满足四个条件的 Skill（见 docs/repository-design.md）：

• 适合开源分享：不依赖私人账号、专有数据或内部系统
• 有明确用途和边界：别人看名称和说明就知道它解决什么问题
• 可清理：能移除敏感信息、缓存、输出物和账号痕迹
• 值得长期维护：作者愿意继续修复、迭代和解释它

仓库目录结构刻意保持轻量，只有六个一级目录：

yao-open-skills/ ├── index.html # HTML 导航页（脚本生成） ├── README.md # 合集首页（目录区块由脚本生成） ├── docs/ # 仓库设计、发布规则、命名规范 ├── registry/ # skills.json 登记表（事实源） ├── scripts/ # 仓库级维护脚本 └── skills/ # 15 个公开 Skill 副本

关键约束是：Skill 状态以登记表为准，README 和 HTML 导航页只做展示，不允许手工维护。这条规则是整个自动化的起点。

🗂️ 事实源：registry/skills.json 一张表管住 15 个 Skill

打开 registry/skills.json，它的结构非常简单：顶层是仓库名、更新日期和一个skills数组，每个 Skill 一条记录。以其中的 Yao Doctor Skill 为例（字段已节选）：

{ "slug": "yao-doctor-skill", "title": "Yao Doctor Skill", "summary": "审计本地 Skill 库和 AI 工作台配置面，区分能力风险与不安全行为……", "collection_path": "skills/yao-doctor-skill", "lifecycle": "active", "sync_status": "published", "guide_path": "docs/skills/yao-doctor-skill.md", "license": "MIT", "tags": ["skills", "security", "audit"], "last_synced_at": "2026-06-19", "updated_at": "2026-06-19" }

一条记录解决了四个管理问题：这个 Skill 来自哪里（source_local_path）、在合集里的哪个目录（collection_path）、是否已同步到公开仓库（sync_status）、使用说明去哪里看（guide_path）。

双状态模型：lifecycle × sync_status

每个 Skill 记录两组状态字段，分别管理"内容生命周期"和"发布同步进度"：

这里有一条硬性规则：published不是推断值，而是显式登记值。只有公开仓库实际推送成功后，才允许标记为published并写入last_synced_at；如果本地源 Skill 发生了变化但还没重新推送，状态必须回退为needs-update。这条规则保证了读者在导航页看到的每个"已发布"标签都真实有效。

字段完整定义见 skills/yao-open-skills-sync/references/registry-schema.md。

✍️ 登记自动化：register_skill.py 一条命令写库

新增或更新一个 Skill 的登记信息，不需要手改 JSON。仓库内置了 upsert 脚本 scripts/register_skill.py，典型用法如下：

python3 scripts/register_skill.py \ --slug yao-positioning-skill \ --title "Yao Positioning Skill" \ --summary "完成竞品研究、需求洞察和定位方案比较" \ --source-local-path "/本地源路径/yao-positioning-skill" \ --collection-path "skills/yao-positioning-skill" \ --lifecycle active \ --sync-status staged \ --license "MIT" \ --tags "positioning,strategy,evidence"

脚本行为做了两层保护：

• 按slug去重：同名记录会被原地更新，而不是产生重复条目
• 自动收尾：刷新顶层updated_at为当天日期，并按slug字典序重新排序整个数组，保证登记表稳定可读

也就是说，登记这个环节是"命令进、JSON 出"，人不需要打开编辑器数逗号。

🔄 一键渲染：一条命令刷新 README 和 HTML 导航页

真正的"魔法"发生在渲染环节。README 里有一块被特殊标记围起来的目录区：

<!-- catalog:start --> （自动生成的 15 行 Skill 表格） <!-- catalog:end -->

渲染脚本 scripts/render_readme_catalog.py 会读取登记表，重新生成表格，然后只替换两个标记之间的内容，README 里其他手写文字一律不动。这就是为什么登记表改了、README 却能始终保持一致，而且作者可以在目录表之外自由编辑首页文案。

入口脚本 scripts/render_collection_pages.py 只做了两件事：先跑 README 渲染，再跑 HTML 导航页渲染（scripts/render_site_nav.py 会基于同一张表生成index.html的 Skill 卡片、分类筛选和搜索索引）。所以统一维护命令只有一条：

python3 scripts/render_collection_pages.py

标签和分类从哪来：catalog_common.py

表格里的中文标签（比如决策分析、网站安全）和 HTML 页面上的四大分类，都来自公共模块 scripts/catalog_common.py：

• 标签映射表：把英文 tag（decision-analysis→决策分析）翻译成中文展示，每个 Skill 最多显示 4 个，多出的折叠成"等"
• 分类目录：定义"决策与战略、商业与研究、学习与内容、工程与治理"四大分类，并通过一张 slug 映射表把每个 Skill 归入对应分类

这样分类调整只发生在代码里，README 和 HTML 页不会出现两套不一致的分组。导航页的更多细节见 docs/html-navigation.md。

🧩 15 个 Skill 的四大分类布局

按catalog_common.py的映射，15 个 Skill 的分布是这样的：

几个有代表性的成员：

• Yao Tutorial Skill：把主题或资料包生产成带配图的完整教程包，下面这张图就是它生成的 Python 教程成品预览

• Yao Doctor Skill：审计本地 Skill 库的安全风险并输出中英双语 HTML 安全报告，下图是它的公开示例报告图集

• Yao Interpreter Skill：静态解读任意 Skill 目录，输出证据链评分和双语 HTML 报告。用它解读元 Skill 项目得到的桌面端报告概览如下

• Yao Open Skills Sync：合集自带的"管家"，负责收录判断、清理、登记和状态维护（下一节详述）

🛡️ 治理层：发布规则 + 内置管家 Skill

自动化工具解决了"怎么记"，治理文档解决的是"什么能进"。

发布规则 docs/publishing-rules.md 把门槛写得非常具体：

• 可以公开：通用性强、方法完整、输入输出清楚、不依赖私人账号和内部系统、愿意长期维护
• 默认不公开：含账号/token/cookie、依赖公司内部文档、混有大量输出缓存日志、结构还在高频变化、版权来源不明

还有一个容易忽略的细节：每个已公开的 Skill必须配套一份人读的说明文档docs/skills/<slug>.md，docs/skills/README.md 是这些说明的总索引。

而把规则落地成日常动作的，是仓库内置的管理 Skill skills/yao-open-skills-sync/SKILL.md。它的职责清单正好覆盖了整条维护链：

1. 检查本地源 Skill，识别哪些文件该留、哪些该删
2. 按发布规则判断能否公开，不能安全清理就明确叫停
3. 复制干净副本到skills/<slug>/
4. 调用register_skill.py写登记表
5. 运行render_collection_pages.py刷新 README 和导航页
6. 推送后才会把sync_status置为published

命名上也有统一约束（见 docs/naming-conventions.md）：目录统一用 kebab-case 的 slug，slug 一旦公开尽量不改名，保证读者收藏的链接长期有效。

🚀 维护者工作流：收录一个 Skill 的完整路径

把前面所有机制串起来，收录一个新 Skill 的标准路径是六步：

这套设计的核心思想一句话就能说清：登记表是唯一事实源，所有页面都是它的投影。人只改数据和规则，展示层永远由脚本重新生成——这正是 15 个 Skill 的目录、标签、状态能在多次迭代后依然保持一致的原因。

📚 关键文件速查

最后给出一份"想深入研究去哪里看"的清单：

• 事实源登记表：registry/skills.json
• 登记脚本：scripts/register_skill.py
• 渲染入口脚本：scripts/render_collection_pages.py
• README 目录渲染：scripts/render_readme_catalog.py
• HTML 导航页渲染：scripts/render_site_nav.py
• 标签与分类映射：scripts/catalog_common.py
• 仓库设计理念：docs/repository-design.md
• 发布规则：docs/publishing-rules.md
• 命名规范：docs/naming-conventions.md
• 导航页维护说明：docs/html-navigation.md
• 管理 Skill 入口：skills/yao-open-skills-sync/SKILL.md
• 15 个 Skill 的说明文档索引：docs/skills/README.md

下次你看到一个"看起来总是同步"的开源合集，不妨去看看它背后是不是也藏着这样一张登记表——工具可以简单，但"单一事实源 + 自动生成"的思路，值得每个维护者借鉴。