SKILL 原则

创建与维护 SKILL 文档的元规则。本身也是 SKILL 文档，是 bootstrap 例外。

什么是 SKILL 文档

SKILL 文档是给 AI 协作助手使用的工作规则文件。读者不必阅读，但维护者在新增、修改、删除 SKILL 文档时必须遵循本文规范。

经验何时 SKILL 化

经验进入 SKILL 的标准，是它会反复影响 AI 协作结果。一次性的观点、临时偏好、单篇文章结论和还没有验证过的做法，应该先沉淀到普通内容文档、issue 处理记录或项目进度里；只有当某类任务会反复发生，并且其中存在稳定的判断标准、操作顺序、验收方式或容易踩坑的边界时，才值得写成 SKILL。

适合 SKILL 化的经验通常有几个特征：

• 高频复用：写作、Issue 沉淀、Docusaurus 配置、音乐库维护、每日三省吾身、提交发布等任务会持续重复发生。
• 过程稳定：每次处理都要先读哪些文件、判断哪些边界、修改哪些位置、验证哪些命令，这些步骤可以被描述成流程。
• 有明确禁区：哪些文件不能改、哪些内容不能直接发布、哪些场景必须问用户、哪些生成产物不能手动编辑。
• 能降低返工：如果不写成规则，AI 容易反复犯同类错误，例如过度新建文档、过度总结、漏掉 front matter、忘记更新入口页、把临时经验写成长期结论。
• 能被客观检查：至少能提供检查清单、命令、文件路径、输出格式或人工确认点，而不是只写“写好一点”“注意质量”。

不适合直接 SKILL 化的内容也要克制：

• 还没有跑通过一次的想法，只能是候选流程。
• 只适用于单篇文章的表达，不应提升为全站写作规则。
• 只是一种价值判断，但没有操作边界，应该进入普通文章。
• 依赖外部工具当前 UI 的细节，容易过期，除非同时写清失效条件。
• 为了记录某次处理过程而写的复盘，不应污染长期规则。

SKILL 化的目标是让下一次同类任务更稳，而不是把所有知识都变成规则。规则过多会让 AI 上下文变重，也会让真正关键的约束被淹没。每新增一条规则，都要问：它会不会在未来多次改变助手行为；如果不会，就不要写进 SKILL。

沉淀粒度

SKILL 文档应该沉淀“做事方式”，而不是堆积案例原文。好的规则要回答五个问题：

1. 这个规则适用于哪类任务？
2. 开始前必须读取哪些上下文？
3. 处理时按什么步骤判断和执行？
4. 哪些情况必须问用户，哪些情况可以直接做？
5. 完成后如何验证、留言、关闭 issue 或更新相关入口？

经验沉淀不能过分简洁。只写“遇到类似情况要融合进文档”没有执行价值；应该写清楚如何判断归属、如何保留因果链、如何处理不确定内容、如何避免原文堆砌、如何验证文风和格式。AI 需要的是可执行规则，不是抽象口号。

但 SKILL 也不能变成百科。背景解释只保留到能支持判断为止；具体案例可以作为例子出现，但不能喧宾夺主。一个实用判断是：如果删除案例后规则仍然可执行，案例就是辅助；如果只能靠案例猜规则，说明规则没有写清。

从任务中回流规则

处理 GitHub Issue、修复网站问题、维护数据或写作时，如果连续遇到同类判断，应在任务完成后考虑是否回流到对应 SKILL。回流时不要新建一个“经验集合”类文档，优先找到已有规则文件：

• Issue 内容沉淀中的归属、确认边界、留言关闭流程 → github-issue-skill.md
• 写作口吻、标题、引用、表格、数据表达 → 我的写作原则.md
• front matter、slug、icon、历史快照 → 网站开发规范.md
• sidebars、入口页、Docusaurus 配置 → docusaurus配置.md
• 新增或维护 SKILL 文档本身 → 本文档

如果找不到对应规则文件，先判断这类任务是否会持续复现。会复现，再按本文规范新建 SKILL；不会复现，就把经验写入相关内容文档或 issue 评论，不要为了“全面 SKILL 化”制造孤立规则。

规则回流要保留来源感，但不要依赖来源文本。可以在 issue 评论里说明“已沉淀到哪个 SKILL 的哪类规则”，SKILL 正文里则写成通用流程。这样规则能长期使用，不会变成某个 issue 的附录。

位置

所有 SKILL 文档统一放在 docs/05-吴飞飞/01-关于/关于FEEI.CN/ 子目录下。

理由：本仓库是 FEEI.CN 站点本身，所有针对仓库的工作规则（写作、配置、提交、工作流、元规则）都是关于这个仓库/站点的元信息，集中在 关于FEEI.CN/ 下与目录语义一致。

front matter 必填字段

所有 SKILL 文档的 front matter 必须包含：

---
slug: /xxx-skill           # 英文路径
title: ...                 # 中文标题
icon: code-icon            # 统一使用 code-icon
description: ...           # 必填，≤160 字
sidebar_badge:
  text: SKILL
  color: success
---

• icon 一律 code-icon，保证视觉一致
• sidebar_badge 一律 { text: 'SKILL', color: success }，让 SKILL 文档在 sidebar 中可识别
• 文件名用中文，slug 用英文短路径
• description 必填，概括文档覆盖的规则或主题

icon 必须带 -icon 后缀。ItsHoverIcon 的 slug 来自文件名（如 code-icon.tsx → code-icon），缺后缀会导致 icon 无法渲染。

路由表

新增、移动、删除 SKILL 文档时，必须同步更新 AI.md 的 Context Loading 路由表。CLAUDE.md 和 AGENTS.md 是由 AI.md 生成的入口文件，不要直接编辑生成文件。

• 新增：在表中加一行 任务类型 | 文档路径
• 移动：更新该行路径
• 删除：删除该行

路径要与 git mv 后的实际位置一致。

写作语气

SKILL 文档的内容遵循本站通用文风：

• 指令式或陈述判断为主（"不创建 README"、"slug 必须稳定"）
• 不引用具体数字和统计数据作为论据
• 不在文档末尾添加总结段落
• 不一句一段，合并相关句子

详细写作规范见 我的写作原则。

引用其他 SKILL

正文中需要引用其他 SKILL 文档时：

• 直接使用中文文件名（依赖 slug 解析），如 详见 docusaurus配置
• 不需要 markdown 超链接形式
• 不要引用文件路径（docs/02-.../docusaurus配置.md）

bootstrap 例外

本文档作为元规则，在创建时已经位于合适的目录、front matter 完整、CLAUDE.md 已登记——这是预先建立的初值。后续如果修改本文档本身，仍需遵循上述所有规则。

如果将来需要"创建 SKILL 文档"的脚手架或模板，应另建一个 SKILL 文档覆盖，不要让本元规则与具体实现耦合。