# 技能体系设计 本文回答当前技能库建设中的 5 个核心问题，并给出可落地的建议。 ## 1. 技能文件是否应该分目录，是否需要多级目录？ 结论：**应该分目录，但要区分“运行态目录”和“知识态目录”。** ### 1.1 运行态目录 如果目标是让 Copilot 直接识别并加载技能，建议遵循官方结构： ```text .github/skills/<skill-name>/SKILL.md ``` 这一层建议保持**扁平化**，不要做太深的多级目录。原因有三： - 官方技能发现机制围绕 `skills/<name>/SKILL.md` 设计。 - 扁平目录便于同步到用户级技能目录。 - 过深目录会让“技能名”和“分类名”耦合，后续迁移困难。 ### 1.2 知识态目录 知识本身是分层的，所以建议把更细的分类放在文档层，而不是直接放在运行态技能根目录层。 例如： ```text docs/ taxonomy/ coding/ architecture/ documentation/ review/ delivery/ ``` ### 1.3 推荐折中方案 - `.github/skills/`：只放可执行的、可被 Copilot 发现的技能包。 - `docs/`：放技能设计、分类说明、沉淀方法、样例、规范。 - `scripts/`：放同步、扫描、合并、批处理脚本。 一句话：**技能入口扁平，技能知识分层。** ## 2. 怎样兼容 Copilot，并支持每天自动同步？ 建议采用“双层架构”： ### 2.1 源仓库层 把 Git 仓库作为**唯一事实源**（source of truth）。 优点： - 可以版本管理。 - 可以 code review。 - 可以多人协作。 - 可以跨电脑同步。 ### 2.2 Copilot 运行层 有两种使用方式： #### 方式 A：项目内直接使用 把技能放在当前项目的 `.github/skills/` 下。打开该项目时，Copilot 就能直接发现这些技能。 适合： - 团队共享技能 - 与特定仓库强绑定的技能 #### 方式 B：用户级全局使用 同步到用户级技能目录，例如： - `~/.copilot/skills/` - `~/.agents/skills/` 适合： - 个人通用技能 - 跨多个仓库共用的写作、编码、分析技能 ### 2.3 最佳实践 推荐保留仓库中的 `.github/skills/` 作为主存储，再用脚本同步到用户级目录。 这样做的好处是： - 在仓库内打开时可直接使用。 - 同时支持全局复用。 - 不会把长期维护工作绑死在某个编辑器专用路径上。 ## 3. 技能 md 文档应该用什么格式？文件名目录名必须英文吗？ 结论：**运行态路径建议英文，正文内容可以中文。** ### 3.1 运行态技能格式 `SKILL.md` 建议使用 YAML frontmatter： ```yaml --- name: capture-conventions description: 'Capture coding conventions, directory habits, naming patterns, and stable repository rules from codebases.' --- ``` 然后正文使用 Markdown，建议包含： - 使用场景 - 输入要求 - 分析步骤 - 输出格式 - 合并策略 - 注意事项 ### 3.2 命名建议 #### 必须固定 - 技能入口文件：`SKILL.md` - 技能目录名：建议与 `name` 一致 #### 推荐英文的部分 - 技能目录名：`capture-conventions` - 脚本名：`sync-skills-to-user.ps1` - 资源文件名：`capture-checklist.md` 原因： - 兼容不同系统与工具链 - 便于脚本处理 - 与官方约定一致 #### 可以中文的部分 - `SKILL.md` 正文 - 设计文档 - 说明性文档 - 模板中的示例内容 ### 3.3 一个很实用的原则 **路径英文，标题中文。** 例如： - 文件路径：`docs/skill-system-design.md` - 文档标题：`# 技能体系设计` ## 4. 除了专有技能与功能性技能，还应该有哪些维度？ 建议至少分为 6 大维度： ### 4.1 捕获型技能 用于从已有材料中抽取稳定规律： - 代码风格捕获 - 目录结构捕获 - 命名习惯捕获 - API 设计偏好捕获 - 文档语气与组织方式捕获 ### 4.2 融合型技能 用于把新知识并入旧知识： - 合并重复条目 - 解决冲突表述 - 区分“稳定规则”和“局部例外” - 输出新的统一版本 ### 4.3 功能型技能 直接帮助完成任务： - 写文档 - 写代码 - 写测试 - 做重构 - 做代码评审 - 生成发布说明 ### 4.4 规范型技能 用于统一输出质量： - 编码规范 - 文档规范 - 注释规范 - 提交信息规范 - Issue / PR 模板规范 ### 4.5 流程型技能 用于跨步骤工作流： - 扫描仓库 → 捕获规律 → 合并知识 → 提交变更 - 分析缺陷 → 定位根因 → 写测试 → 修复 → 生成复盘 - 阅读项目 → 生成模块导图 → 输出上手文档 ### 4.6 元技能（Meta Skills） 用于维护技能体系自身： - 怎样写一个好技能 - 怎样拆分技能 - 怎样命名技能 - 怎样评估技能是否过大 - 怎样淘汰陈旧技能 这里面，**文档规范技能**当然值得单独成类，而且通常是高频高价值技能。 ## 5. Copilot 是否有记忆？能否与技能库合并？ 结论：**有，但定位不同，不能把 Copilot Memory 当成长期技能库。** ### 5.1 Copilot Memory 的特点 根据 GitHub 官方文档： - 它是**仓库级**记忆，不是用户级长期知识库。 - 由 Copilot 在实际工作中自动归纳产生。 - 带引用位置，会在使用前校验代码是否仍然成立。 - 默认会自动过期，当前公开资料显示约 **28 天**。 - 目前主要用于 GitHub 网站上的 cloud agent、code review、CLI 等场景。 ### 5.2 它适合做什么 适合做： - 仓库近期约定的自动记忆 - 局部代码习惯的短中期保持 - 减少重复提示 不适合做： - 你的长期个人知识资产库 - 跨仓库复用的方法论中心 - 需要精心编排和版本管理的规范体系 ### 5.3 推荐关系 建议把二者关系定义为： - **技能库**：长期、人工可维护、可审阅、可版本化的显式知识。 - **Copilot Memory**：短中期、仓库内、自动生成的隐式工作记忆。 ### 5.4 最佳整合方式 不要直接“把 Memory 当技能库”，而是做成这样的闭环： 1. 在日常 Copilot 使用中，让 Memory 自动积累。 2. 定期把高价值记忆转成候选知识。 3. 通过“融合型技能”合并到 Git 管理的技能库。 4. 再由脚本把技能库同步回 Copilot 可用目录。 这才是比较稳、也更适合长期演进的方案。 ## 推荐的初始技能清单 如果现在就开始搭，建议第一批先做这 12 个： 1. `capture-conventions` 2. `merge-skill-knowledge` 3. `write-tech-docs` 4. `capture-csharp-style` 5. `capture-directory-patterns` 6. `capture-module-usage` 7. `review-code-consistency` 8. `write-api-docs` 9. `write-release-notes` 10. `summarize-repository` 11. `generate-onboarding-guide` 12. `maintain-skill-library` ## 你现在最值得马上做的事 1. 确定技能目录主结构。 2. 先写 3 个核心技能样板。 3. 用 1~2 个真实仓库做捕获实验。 4. 验证“捕获 → 融合 → 同步”闭环。 5. 再逐步批量扩展。