Skip to content

Skills 模块结构重构(对齐 shadcn-ui 精细化分层,但保持技能独立) #1128

@hotlong

Description

@hotlong

背景

当前 repo 下的 skills 以每个领域独立子目录呈现,如 objectstack-data, objectstack-api, objectstack-ui 等,每个 skill 的 SKILL.md 内容庞杂,所有细则几乎全部内联,扩展性、可测试性和 AI 理解友好性均有待提升。

https://github.com/shadcn-ui/ui/tree/main/skills/shadcn

shadcn-ui/ui 的 skills/shadcn 目录采用了精细化分层的结构:主控 SKILL.md 只写摘要与用例,其它规则、CLI、定制内容拆分成 rules/、cli.md、customization.md 等子文件,且具备 evals/ 目录用于测试。shadcn 此模式极大增强了易维护性、AI 消化能力和用例复用。

但本项目领域远超 shadcn,直接合并所有 skill 为单 skill 或用"全局路由 skill"不可行(会影响 plugin/slill 的独立分发与兼容性)。

目标

  • 为每个 objectstack-* skill 参考 shadcn 的分层模式(而非将所有技能合并为一个),并将主干内容与规则、用例、测试解耦。
  • 保证每个 skill 保持独立、可单独安装/引用,不需要 skill 之间显式"路由"。

具体方案(建议)

  • 以 objectstack-data 举例,skill 目录重构如下:
    skills/objectstack-data/
    ├── SKILL.md          # 精炼主控(摘要/决策树+规则/案例索引+引用)
    ├── rules/
    │   ├── naming.md         # 命名规范 error/correct 对比
    │   ├── relationships.md  # 关系类型/模式最佳实践
    │   ├── validation.md     # 校验规则(可直接移自现有SKILL.md)
    │   └── indexing.md       # 索引策略等
    ├── evals/                # 测试用例(可后续补充)
    └── references/           # 现有 schema 参考
    
  • 其它 skills(如 objectstack-kernel, objectstack-ui, objectstack-api, objectstack-automation 等)同样进行 rules/ 与 evals/ 结构补全和拆分
  • SKILL.md 文件保持"主控索引"与"快速案例/规则小节",细节与代码对比、多层场景拆分等内容全部放入 rules/ 或其它子文件,AI 可通过相对路径引导定位详细判据
  • 不设置全局 skill 路由或统一 skill 入口——repo 保持每个 skill 自包含,分发 & 选择灵活
  • 推荐 hooks skill 内容整合到 objectstack-data/rules/hooks.md,减少冗余与领域重叠
  • 测试用例与 evals/ 内容为可选,可逐步补充

验收标准

  • 每个 skill 的 SKILL.md 都高度聚焦/短小,rules/ 文件内具备 Incorrect/Correct 对比案例
  • skills 无显式路由依赖,单 skill 安装仍可获得全部原本能力
  • 结构优化后,AI(Copilot/Cursor/Chatbot)能更精确理解各 skill 使用场景与区别

  • 变更需同步 CHANGELOG.md 并补充/核对测试用例,如有较大重构应更新 ROADMAP.md

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions