1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | skill-based-architecture |
| 项目自述名称 | Skill-Based Architecture（README 标题即用此名，未使用意译名） |
| 作者/维护者 | WoJiSama（个人开发者） |
| 来源链接 | https://github.com/WoJiSama/skill-based-architecture |
| 许可证 | MIT（GitHub API 确认） |
| GitHub Stars / Forks | 494 / 41（GitHub API 实测） |
| 最新版本 | v1.14.0（GitHub Release，发布于 2026-05-09）；此后仓库仍持续提交更新，最近一次提交为 2026-08-14 |
| 安装方式 | Claude Code：/plugin marketplace add + /plugin install 两条命令；Cursor / Codex / Gemini / Windsurf / OpenCode 等：git clone 到项目旁路径后用自然语言唤起 |
2. 功能介绍与亮点
一个专门“重组 Agent 规则文件”的元技能：把散落在 AGENTS.md、CLAUDE.md、.cursor/rules/ 等多处的项目规则，或一份已经写得过大、难以维护的单体 SKILL.md，重新组织成结构化、可路由的技能目录。
- 证据驱动的结构选择：不要求用户手动挑选“简单/中等/完整”档位，而是先盘点目标仓库现有规则的规模与复杂度，据此自动推导应生成单文件、轻量文件夹还是完整目录结构，仓库变小时结构也会相应收缩
- 按内容性质拆分：把不变的设计原则、随代码变化的事实地图、团队风格约定、模块级“坑点记录”分别归位到不同文件，避免一份文档混杂多种更新频率不同的内容
- 写入前预览确认：每一次创建、保留、冲突处理动作都会先展示计划、经用户确认后才落盘，并对保留下来的旧指令做语义合并，而非简单覆盖
- 跨工具路由入口：只在探测到对应工具时才生成 Cursor、Codex 等的注册入口，不会给未使用的工具硬塞适配文件
- 迁移前后校验：完成后会同时核对生成的目录结构和“新旧内容语义是否对应”，而不是只检查文件是否创建成功
3. 适用场景
固定分类：元技能与 Agent 增强
适用于同时使用多个 AI 编码工具（如 Claude Code、Cursor、Codex）、项目规则分散在多份配置文件里反复复制粘贴的开发者，以及维护的 SKILL.md 或项目规则文件已经膨胀到难以浏览、需要拆分为结构化目录的技能作者。对只有一两份小规则文件的小项目，作者本人在文档中也明确建议不必迁移，直接维持现状更简单。
4. 跨 Agent 兼容性
| Agent | 结论 | 依据 |
|---|---|---|
| Claude Code | ✅ 原生支持 | 仓库内含 .claude-plugin/marketplace.json 与 plugin.json，可通过官方插件市场两条命令直接安装；随附 SessionStart hook 用于会话清空/压缩后自动重新注入规则 |
| Codex | ✅ 已验证可用 | README 明确列出 Codex 的 clone 安装路径；一位 GitHub 用户（LDmoxeii）在真实 Codex CLI 环境下安装使用时报告并复现了一处模板文件 YAML 解析错误，作者在数小时内确认修复，证实该技能确实被安装进 Codex 环境并投入使用 |
| OpenClaw | ❓ 未验证 | README 未点名提及 OpenClaw；技能主体为标准 SKILL.md 格式，理论上符合 Agent Skills 规范的工具应可读取，但未见项目方或第三方的明确验证记录 |
| Hermes Agent | ❓ 未验证 | 同上，README 未点名提及，无法确认实际可用性 |
5. 推荐理由
多数“元技能”类产品解决的是“如何写出一个新技能”，而这个技能解决的是一个更容易被忽视的后续问题：项目规则和技能文件用久了会变得又长又散，散落在好几份配置文件里反复维护、互相打架。它把“重组规则”这件事本身产品化成一个可重复调用的流程——先盘点证据再决定结构、写入前必须预览确认、事后校验语义是否对应——而不是让用户每次都手动整理。License 清晰、无外部网络调用、近期仍在持续更新，且已有真实第三方用户在 Codex 环境下的实际使用记录。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 5 | GitHub 494 stars、41 forks；GitHub issue 区有 1 条已修复的真实缺陷报告与 1 条功能请求，均来自具名独立用户，目前未检索到其他平台的独立讨论或第三方报道 |
| 可用性 | 9 | Claude Code 下两条命令即可安装；其余工具 git clone 后自然语言唤起即可，无需额外配置或付费依赖；文档体系完整（README 含中英文版、REFERENCE.md、EXAMPLES.md、WORKFLOW.md 等），并提供沙盒示例供试用而不影响真实项目；近 4 天内仍有提交更新，维护活跃 |
| 安全性 | 8 | 见下方检查清单 |
安全检查清单： ① Shell 命令：随附脚本执行范围明确——扫描/重组本地规则文件、生成目录结构，均是完成“重组规则”这一声明功能所必需的本地文件操作 ② 联网外发：代码库检索未发现任何网络请求相关代码，SessionStart hook 也只读取本地 SKILL.md 文件并输出到标准输出，无外发行为 ③ 凭据处理：不涉及任何 API Key 或账号凭据 ④ 可疑指令：通读 SKILL.md 与相关脚本全文未发现夹带无关推广或隐蔽指令 ⑤ 作者信誉：个人开发者，对用户报告的缺陷响应及时（数小时内定位并修复） ⑥ License：MIT，条款明确 ⑦ 最近维护：最近一次提交为 2026-08-14，维护活跃
综合评分 = 三项均值 = 7.33
7. 跟同类 Skills 相比的优势
| 技能 | 定位 | 与本技能的差异 |
|---|---|---|
| skill-creator（Anthropic 官方） | 引导用户从零开始创作一个全新技能，交互式问答生成 SKILL.md 结构 | 解决“如何写出一个新技能”，不处理已经存在、内容已经膨胀或分散在多份文件中的旧规则如何重组 |
| SkillForge（tripleyak） | 技能创建与生态维护工具，覆盖基线测试、回归评测、跨运行时编译等全流程 | 同样面向技能作者，但核心场景是“从需求出发生成新技能并验证其效果”，而非专门解决“规则分散、单文件过大”这一结构性问题 |
本技能的差异化在于专注“重组”而非“创作”——面向的是规则已经存在但组织混乱的场景，用证据驱动的方式决定该拆成多细的目录结构，这是同类元技能工具中较少被单独产品化的一个环节。
8. 用户评价
- LDmoxeii（GitHub 用户，Codex CLI 使用者）：安装使用该技能时报告了一处模板文件被误识别为正式 SKILL.md 导致 YAML 解析报错的问题，并附上完整错误信息；作者确认复现后于当天完成修复，用户回复确认问题已解决。该记录留存于仓库 Issue #1，是该技能被安装进真实 Codex 环境并投入使用的具体证据。
9. 其他补充
仓库同时维护英文与中文两版 README（README.md / README.zh-CN.md），并提供 examples/simple-repo/ 沙盒示例，允许在不触碰真实项目的情况下先体验一次完整的重组流程。
10. 安装使用方式
- Claude Code：
/plugin marketplace add WoJiSama/skill-based-architecture后/plugin install skill-based-architecture@skill-based-architecture；可用/plugin marketplace update获取最新版本 - Cursor / Codex / Gemini / Windsurf / OpenCode 等：
git clone https://github.com/WoJiSama/skill-based-architecture.git到项目旁路径，随后用自然语言（如“使用 skill-based-architecture 整理这个项目的规则”）唤起，或让 Agent 先读取 clone 下来的SKILL.md - 安装后注意事项：首次使用建议先在
examples/simple-repo/沙盒目录内试跑一次，熟悉预览确认流程后再对真实项目执行；每次生成前都会先展示创建/保留/冲突处理计划，需用户确认后才会实际写入文件
11. 注意事项
- 面向已经积累一定规模项目规则或大型 SKILL.md 的用户；作者本人在文档中建议少于三份小规则文件的小项目不必迁移
- OpenClaw、Hermes Agent 的兼容性未见明确验证记录，实际效果需自行测试确认
- 个人开发者维护，非官方或机构出品；GitHub Release 版本号（v1.14.0）落后于最新提交，功能上仍在持续演进中，非正式发布的改动尚未体现在版本号里