项目总结：Skills 与 HAP Skills Collection

1. 项目概述

本项目是一个技能集合（Skills）系统，包含两部分核心内容：

• 基础 Skills 框架：由 Anthropic 开发的 Claude 技能系统，提供技能的标准规范和示例
• HAP Skills Collection：专为明道云 HAP 平台开发的 AI 技能包集合，让 AI 编程工具能够自动理解并使用明道云的 API、开发规范和最佳实践

2. 业务模型

2.1 核心业务场景

1. AI 工具技能增强

   • 为 AI 编程工具（如 Claude Code、TRAE、Cursor 等）提供专业技能，提升其在特定领域的能力
   • 使 AI 工具能够理解并使用特定平台的 API 和开发规范

2. 明道云 HAP 平台开发

   • 简化 HAP 平台的开发流程，降低学习成本
   • 提供标准化的开发流程和最佳实践
   • 支持从数据查询到视图插件开发的全流程

3. 跨平台技能部署

   • 实现技能在多个 AI 工具平台的统一部署和管理
   • 提供"一次安装，到处运行"的便捷方案

2.2 目标用户

• 明道云 HAP 平台开发者：需要快速开发 HAP 应用、视图插件和前端项目的开发人员
• AI 工具用户：希望在 AI 工具中获得专业领域支持的用户
• 企业开发团队：需要标准化开发流程和最佳实践的团队

3. 需求清单

3.1 功能需求

1. 技能管理

   • 创建和管理标准化的技能目录结构
   • 支持技能的安装、更新和卸载
   • 提供技能的元数据和描述信息

2. HAP 平台集成

   • 支持 HAP V3 API 的完整使用流程
   • 提供视图插件开发的完整流程
   • 支持前端项目搭建和 MCP 配置管理

3. 跨平台支持

   • 支持多种 AI 工具平台（Claude Code、TRAE、Cursor 等）
   • 提供统一的安装和部署方案
   • 支持软链接和自动同步机制

4. 开发流程支持

   • 提供标准化的开发流程和最佳实践
   • 支持从项目初始化到发布上线的全流程
   • 提供代码生成和配置自动化

3.2 非功能需求

1. 易用性

   • 零学习成本，AI 自动理解 API
   • 一键安装和配置
   • 清晰的文档和使用示例

2. 可维护性

   • 模块化的技能结构
   • 统一的更新机制
   • 详细的版本控制和更新日志

3. 扩展性

   • 支持新技能的添加和现有技能的扩展
   • 适应明道云平台的更新和变化
   • 支持新 AI 工具平台的集成

4. 兼容性

   • 兼容多种 AI 工具平台
   • 遵循各平台的技能规范
   • 支持不同操作系统（Windows、macOS、Linux）

4. 系统设计

4.1 架构设计

┌─────────────────────────────────────────────────────────┐
│                     应用层                              │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐   │
│  │Claude   │  │TRAE     │  │Cursor   │  │其他 AI  │   │
│  │Code     │  │         │  │         │  │工具     │   │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘   │
├─────────────────────────────────────────────────────────┤
│                     技能层                              │
│  ┌───────────────────────────────────────────────────┐  │
│  │                Skills 目录                        │  │
│  │  ┌────────────┐  ┌────────────┐  ┌────────────┐  │  │
│  │  │HAP V3 API  │  │视图插件    │  │前端项目    │  │  │
│  │  │技能        │  │开发技能    │  │搭建技能    │  │  │
│  │  └────────────┘  └────────────┘  └────────────┘  │  │
│  │  ┌────────────┐  ┌────────────┐                  │  │
│  │  │MCP 使用    │  │其他技能    │                  │  │
│  │  │指南        │  │            │                  │  │
│  │  └────────────┘  └────────────┘                  │  │
│  └───────────────────────────────────────────────────┘  │
├─────────────────────────────────────────────────────────┤
│                     平台层                              │
│  ┌───────────────────────────────────────────────────┐  │
│  │                明道云 HAP 平台                    │  │
│  │  ┌────────────┐  ┌────────────┐  ┌────────────┐  │  │
│  │  │V3 API     │  │视图插件    │  │MCP Server  │  │  │
│  │  │            │  │系统        │  │            │  │  │
│  │  └────────────┘  └────────────┘  └────────────┘  │  │
│  └───────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘

4.2 目录结构

基础 Skills 框架结构：

skills-main/
├── .claude-plugin/          # Claude 插件配置
├── skills/                   # 技能目录
│   ├── algorithmic-art/      # 算法艺术技能
│   ├── brand-guidelines/     # 品牌指南技能
│   ├── canvas-design/        # 画布设计技能
│   ├── doc-coauthoring/      # 文档协作技能
│   ├── docx/                 # DOCX 文档技能
│   ├── frontend-design/      # 前端设计技能
│   ├── internal-comms/       # 内部通信技能
│   ├── mcp-builder/          # MCP 构建器技能
│   ├── pdf/                  # PDF 文档技能
│   ├── pptx/                 # PPTX 文档技能
│   ├── skill-creator/        # 技能创建器
│   ├── slack-gif-creator/    # Slack GIF 创建技能
│   ├── theme-factory/        # 主题工厂技能
│   ├── web-artifacts-builder/# Web 构件构建技能
│   ├── webapp-testing/       # Web 应用测试技能
│   └── xlsx/                 # XLSX 文档技能
├── spec/                     # 技能规范
├── template/                 # 技能模板
├── README.md                 # 项目说明
└── THIRD_PARTY_NOTICES.md    # 第三方声明

HAP Skills Collection 结构：

hap-skills-collection/
├── README.md                  # 项目主文档
├── README.en.md               # 英文文档
├── LICENSE                    # MIT 许可证
├── install.sh                 # macOS/Linux 安装脚本
├── install.ps1                # Windows 安装脚本
├── uninstall.sh               # 卸载脚本
├── docs/                      # 文档目录
│   ├── QUICK_START.md         # 快速启动指南
│   └── INSTALLATION.md        # 详细安装指南
├── .claude/skills/            # 技能目录
│   ├── hap-v3-api/            # HAP V3 API 使用技能
│   ├── hap-view-plugin/       # 视图插件开发技能
│   ├── hap-frontend-project/  # 前端项目搭建技能
│   ├── hap-mcp-usage/         # MCP 使用指南
│   └── hap-skills-updater/    # Skills 更新工具
└── mcp-mingdao-proxy/         # MCP 代理工具

4.3 核心组件

1. 技能文件（SKILL.md）

   • YAML 前置元数据（名称、描述等）
   • Markdown 格式的技能说明和指令
   • 示例和最佳实践指南

2. 安装脚本

   • install.sh：macOS/Linux 一键安装脚本
   • install.ps1：Windows PowerShell 安装脚本
   • 支持全局/项目级安装
   • 支持自动软链接创建

3. 文档系统

   • 快速启动指南
   • 详细安装指南
   • 平台兼容性说明
   • 常见问题解答

5. 功能清单

5.1 基础 Skills 框架功能

功能	描述	所在位置
技能管理	创建、安装和管理技能	skills/
文档处理	支持 DOCX、PDF、PPTX、XLSX 文档操作	skills/docx/, skills/pdf/, skills/pptx/, skills/xlsx/
设计工具	算法艺术、画布设计、主题工厂	skills/algorithmic-art/, skills/canvas-design/, skills/theme-factory/
开发工具	前端设计、Web 应用测试、MCP 构建器	skills/frontend-design/, skills/webapp-testing/, skills/mcp-builder/
通信工具	内部通信、文档协作	skills/internal-comms/, skills/doc-coauthoring/

5.2 HAP Skills Collection 功能

功能	描述	所在位置
HAP V3 API 使用	完整的 API 调用工作流、Filter 筛选器、关联字段查询	.claude/skills/hap-v3-api/
视图插件开发	7 步开发流程、4 种模板、双 API 集成	.claude/skills/hap-view-plugin/
前端项目搭建	HAP 作为后端数据库、前端技术栈集成、鉴权方案	.claude/skills/hap-frontend-project/
MCP 使用指南	MCP 服务器配置、自动化配置、密钥管理	.claude/skills/hap-mcp-usage/
跨平台支持	支持 9 种 AI 工具平台、一键安装、自动同步	install.sh, install.ps1

6. 代码规模

6.1 基础 Skills 框架

• 技能数量：15+ 个专业技能
• 文件数量：数百个文件，包括技能定义、脚本和资源
• 代码行数：估计数万行，包含各种语言（Python、JavaScript、Markdown 等）
• 主要文件类型：
  • SKILL.md：技能定义文件
  • 脚本文件（.py、.js、.sh）：工具脚本
  • 资源文件（.ttf、.xsd）：字体和架构定义

6.2 HAP Skills Collection

• 技能数量：4 个核心技能 + 1 个内部更新工具
• 文件数量：约 50+ 文件
• 代码行数：估计数千行，主要为 Markdown 文档和安装脚本
• 主要文件类型：
  • SKILL.md：技能定义文件
  • 安装脚本（install.sh、install.ps1、uninstall.sh）
  • 文档文件（README.md、QUICK_START.md、INSTALLATION.md）

7. 技术栈

7.1 基础技术

• 标记语言：Markdown（技能定义和文档）
• 脚本语言：Bash、PowerShell（安装和管理脚本）
• 编程语言：Python、JavaScript（工具脚本）
• 配置格式：YAML（技能元数据）

7.2 依赖项

• AI 工具平台：Claude Code、TRAE、Cursor、GitHub Copilot、Google Antigravity、OpenCode、Windsurf、Gemini CLI、OpenAI Codex
• 开发工具：mdye-cli（视图插件开发）
• API：明道云 HAP V3 API、MCP Server API

8. 关键特性

1. 零学习成本：AI 自动理解明道云 API，无需手动查文档
2. 最佳实践内置：基于实战经验的开发规范和技巧
3. 完整工作流：从项目初始化到发布上线的全流程支持
4. 持续更新：跟随明道云平台更新，保持最新
5. 9 平台支持：支持所有主流 AI 编程工具，一键安装
6. 一次安装，到处运行：在 Claude 目录安装一次，其他平台自动同步

9. 应用场景

1. 数据查询和操作：使用 HAP V3 API 技能查询和操作明道云数据
2. 自定义视图开发：使用视图插件开发技能创建数据看板和自定义视图
3. 独立网站搭建：使用前端项目搭建技能以 HAP 作为后端数据库
4. MCP 配置管理：使用 MCP 使用指南配置和管理 MCP Server

10. 维护和升级建议

10.1 维护策略

1. 定期更新：跟随明道云 HAP 平台的更新，及时更新技能内容
2. 版本控制：使用 Git 进行版本管理，记录更新日志
3. 测试验证：在更新技能后，在各平台进行测试验证
4. 文档维护：保持文档的准确性和完整性

10.2 升级建议

1. 技能扩展：根据实际需求，扩展现有技能或添加新技能
2. 平台支持：持续支持新的 AI 工具平台
3. 性能优化：优化技能的执行效率和响应速度
4. 安全性：确保技能中的 API 调用和数据处理符合安全最佳实践

10.3 常见问题和解决方案

1. 安装失败：检查权限和网络连接，尝试手动安装
2. 技能不生效：重启 AI 工具，确保技能目录正确
3. API 调用失败：检查鉴权信息和网络连接
4. 平台兼容性问题：参考平台兼容性说明，使用推荐的安装方式

11. 总结

Skills 与 HAP Skills Collection 项目为 AI 工具提供了强大的技能扩展能力，特别是为明道云 HAP 平台的开发提供了标准化的流程和最佳实践。通过这些技能，开发者可以：

• 快速上手明道云 HAP 平台开发
• 减少重复工作，提高开发效率
• 遵循最佳实践，保证代码质量
• 在多种 AI 工具平台上获得一致的开发体验

项目设计合理，结构清晰，易于维护和扩展，为明道云 HAP 平台的生态系统做出了重要贡献。

12. 附录

12.1 相关链接

• 明道云官网：https://www.mingdao.com
• HAP API 文档：https://apifox.mingdao.com
• Claude 技能文档：https://support.claude.com/en/articles/12512198-creating-custom-skills
• HAP Skills Collection GitHub：https://github.com/garfield-bb/hap-skills-collection

12.2 版本历史

• v2.0.0 (2026-01-18)：重大更新，新增支持 5 个平台，提供通用安装脚本
• v1.0.0 (2026-01-14)：初始发布，包含 4 个核心技能，支持 4 个平台

12.3 许可证

• 基础 Skills 框架：部分开源（Apache 2.0），部分源可用
• HAP Skills Collection：MIT 许可证