HAP Skills Collection 技能更新和维护
本技能帮助用户更新和维护 HAP Skills Collection 中的 4 个核心技能。
📋 核心技能列表
HAP Skills Collection 包含以下 4 个核心技能（需要从 GitHub 仓库更新）：
- hap-v3-api - HAP V3 API 使用技能 ✅
- hap-view-plugin - HAP 视图插件开发技能 ✅
- hap-frontend-project - HAP 前端项目搭建技能 ⚠️（如果不存在，需要从仓库获取）
- hap-mcp-usage - HAP MCP 使用指南 ✅
注意: 某些技能可能尚未在本地创建，更新时会自动从 GitHub 仓库同步。
📁 技能目录结构
.claude/skills/
├── hap-v3-api/
│ └── SKILL.md
├── hap-view-plugin/
│ └── SKILL.md
├── hap-frontend-project/
│ └── SKILL.md
└── hap-mcp-usage/
└── SKILL.md🔄 更新流程
步骤 1: 检查当前技能版本
在更新技能之前，先检查当前技能的状态：
# 检查技能文件是否存在
ls -la ~/.claude/skills/hap-v3-api/SKILL.md
ls -la ~/.claude/skills/hap-view-plugin/SKILL.md
ls -la ~/.claude/skills/hap-frontend-project/SKILL.md
ls -la ~/.claude/skills/hap-mcp-usage/SKILL.md
# 或者如果是从 GitHub 仓库克隆的
cd /path/to/hap-skills-collection
ls -la .claude/skills/*/SKILL.md步骤 1.5: 检查并安装 HAP API 文档 MCP（新增）
重要: 在安装/更新技能时，必须检查用户是否已安装 应用 API - API 文档 MCP。
检查 MCP 是否已安装
根据用户当前使用的平台检查 MCP 配置文件：
Claude Code:
# 检查是否已配置
claude mcp list | grep "应用 API - API 文档"Cursor:
# 检查配置文件
cat ~/.cursor/mcp.json | grep "应用 API - API 文档"
# 或项目级
cat .cursor/mcp.json | grep "应用 API - API 文档"TRAE:
# 检查配置文件
cat ~/.trae/mcp.json | grep "应用 API - API 文档"
# 或项目级
cat .trae/mcp.json | grep "应用 API - API 文档"其他平台: 同理检查对应平台的配置文件
如果未安装，自动安装 API 文档 MCP
MCP 配置信息:
{
"mcpServers": {
"应用 API - API 文档": {
"command": "npx",
"args": ["-y", "apifox-mcp-server@latest", "--site-id=5442569"]
}
}
}自动安装步骤:
- 识别平台: 确定用户使用的 AI 工具（Claude Code / Cursor / TRAE 等）
- 读取现有配置: 增量更新，保留用户已有的 MCP 配置
- 添加 API 文档 MCP:
- Claude Code: claude mcp add "应用 API - API 文档" --command npx --args "-y,apifox-mcp-server@latest,--site-id=5442569" - Cursor/TRAE 等: 编辑 mcp.json 文件添加配置
- 验证安装: 检查配置文件是否包含 "应用 API - API 文档"
- 提示重启: 告知用户需要重启工具使配置生效
示例 - Cursor 平台:
# 读取现有配置
EXISTING_CONFIG=$(cat ~/.cursor/mcp.json 2>/dev/null || echo '{"mcpServers":{}}')
# 添加 API 文档 MCP（增量更新）
cat > ~/.cursor/mcp.json <<EOF
{
"mcpServers": {
$(echo "$EXISTING_CONFIG" | jq -r '.mcpServers | to_entries | map("\"\(.key)\": \(.value|tojson)") | join(",")'),
"应用 API - API 文档": {
"command": "npx",
"args": ["-y", "apifox-mcp-server@latest", "--site-id=5442569"]
}
}
}
EOF
# 验证安装
cat ~/.cursor/mcp.json | grep "应用 API - API 文档"告知用户:
✅ HAP API 文档 MCP 已安装
📋 配置信息：
- 平台：Cursor
- MCP 名称：应用 API - API 文档
- 配置文件：~/.cursor/mcp.json
- 已保留其他 MCP 配置
💡 下一步：
- 重启 Cursor 使配置生效
- 现在可以使用 MCP 查询 HAP API 文档了
📖 用途说明：
- 让 AI 读懂 HAP 接口文档（只读，不执行操作）
- 查询 API 文档、学习接口结构、生成 API 调用代码步骤 2: 更新技能文件
方式一：从 GitHub 仓库更新（推荐）
# 1. 克隆或更新仓库
git clone https://github.com/garfield-bb/hap-skills-collection.git
# 或如果已存在
cd hap-skills-collection
git pull origin main
# 2. 确保本地技能目录存在
mkdir -p ~/.claude/skills
# 3. 复制所有技能到本地技能目录（包括缺失的技能）
cp -r .claude/skills/hap-v3-api ~/.claude/skills/ 2>/dev/null || echo "hap-v3-api 已存在或不存在"
cp -r .claude/skills/hap-view-plugin ~/.claude/skills/ 2>/dev/null || echo "hap-view-plugin 已存在或不存在"
cp -r .claude/skills/hap-frontend-project ~/.claude/skills/ 2>/dev/null || echo "hap-frontend-project 已存在或不存在"
cp -r .claude/skills/hap-mcp-usage ~/.claude/skills/ 2>/dev/null || echo "hap-mcp-usage 已存在或不存在"
# 4. 验证更新（检查实际存在的技能）
ls -la ~/.claude/skills/hap-*/SKILL.md 2>/dev/null方式二：手动更新单个技能
如果只需要更新某个特定技能：
# 更新单个技能
cp /path/to/hap-skills-collection/.claude/skills/hap-v3-api/SKILL.md ~/.claude/skills/hap-v3-api/SKILL.md
# 更新所有 4 个技能
for skill in hap-v3-api hap-view-plugin hap-frontend-project hap-mcp-usage; do
cp /path/to/hap-skills-collection/.claude/skills/$skill/SKILL.md ~/.claude/skills/$skill/SKILL.md
done步骤 3: 验证更新
更新后，验证技能是否正确加载：
# 检查文件大小和修改时间
ls -lh ~/.claude/skills/hap-*/SKILL.md
# 检查文件内容（查看前几行）
head -10 ~/.claude/skills/hap-v3-api/SKILL.md📝 更新检查清单
更新技能时，请检查以下内容：
✅ 通用检查项
- 技能文件存在且可读
- SKILL.md 文件格式正确（包含 frontmatter）
- 技能名称和描述正确
- 文件编码为 UTF-8
- 没有语法错误
- HAP API 文档 MCP 已安装（新增）
✅ MCP 配置检查（新增）
- 检查平台的 MCP 配置文件
- 确认是否已安装 "应用 API - API 文档"
- 如果未安装，自动安装 API 文档 MCP
- 增量更新，保留用户已有的 MCP 配置
- 提示用户重启工具使配置生效
✅ 内容检查项
- hap-v3-api:
- API 使用工作流完整 - Filter 筛选器语法正确 - 鉴权配置说明清晰 - 示例代码可运行
- hap-view-plugin:
- 开发流程步骤完整（7步） - 模板选择说明清晰 - 字段类型处理正确 - API 集成说明完整
- hap-frontend-project:
- HAP 后台配置指导完整 - 前端项目结构清晰 - API 集成最佳实践正确 - 数据渲染优化说明
- hap-mcp-usage:
- 两种 MCP 类型说明清晰 - Cursor 自动化配置流程正确 - 配置文件位置准确（~/.cursor/mcp.json） - 密钥提取方法正确
🤖 AI 助手更新指南
当用户需要更新技能时，AI 应该：
1. 识别更新需求
用户可能说：
- "更新 hap-skills"
- "更新技能"
- "同步最新的 skill"
- "更新 hap-v3-api 技能"
2. 执行更新操作
如果用户有本地仓库：
# 检查仓库位置
cd /path/to/hap-skills-collection
# 拉取最新更新
git pull origin main
# 复制技能文件
cp -r .claude/skills/* ~/.claude/skills/
# 验证更新
ls -la ~/.claude/skills/hap-*/SKILL.md
# ⚠️ 重要：检查并安装 HAP API 文档 MCP
# （见步骤 1.5）如果用户没有本地仓库：
# 克隆仓库
git clone https://github.com/garfield-bb/hap-skills-collection.git /tmp/hap-skills-collection
# 确保本地技能目录存在
mkdir -p ~/.claude/skills
# 复制 4 个核心技能文件（只复制存在的）
for skill in hap-v3-api hap-view-plugin hap-frontend-project hap-mcp-usage; do
if [ -d "/tmp/hap-skills-collection/.claude/skills/$skill" ]; then
cp -r /tmp/hap-skills-collection/.claude/skills/$skill ~/.claude/skills/
echo "✅ 已更新 $skill"
else
echo "⚠️ $skill 在仓库中不存在，跳过"
fi
done
# 验证更新（只显示实际存在的技能）
ls -la ~/.claude/skills/hap-*/SKILL.md 2>/dev/null
# ⚠️ 重要：检查并安装 HAP API 文档 MCP
# （见步骤 1.5）⚠️ 关键提醒:
- 更新技能后，必须检查 HAP API 文档 MCP 是否已安装
- 如果未安装，自动帮用户安装（见步骤 1.5）
- 安装后提示用户重启工具使配置生效
3. 验证更新结果
更新后，AI 应该：
- ✅ 检查所有 4 个技能文件是否存在
- ✅ 验证文件大小是否合理（不应该为 0）
- ✅ 检查文件修改时间是否为最新
- ✅ 读取文件前几行验证格式正确
- ✅ 检查 HAP API 文档 MCP 是否已安装（新增）
- ✅ 如果未安装，自动安装 API 文档 MCP
4. 告知用户
更新完成后，AI 应该告知用户：
- ✅ 已更新的技能列表（4 个核心技能）
- ✅ 更新来源（GitHub 仓库）
- ✅ 技能文件位置（~/.claude/skills/）
- ✅ HAP API 文档 MCP 安装状态（已安装 / 已跳过 / 刚安装）
- ⚠️ 可能需要重启 AI 工具才能生效
完整的用户反馈示例:
✅ HAP Skills 更新完成！
📋 已更新技能：
1. ✅ hap-v3-api - HAP V3 API 使用技能
2. ✅ hap-view-plugin - HAP 视图插件开发技能
3. ✅ hap-frontend-project - HAP 前端项目搭建技能
4. ✅ hap-mcp-usage - HAP MCP 使用指南
📦 MCP 配置：
✅ 应用 API - API 文档 MCP 已安装
- 平台：Cursor
- 配置文件：~/.cursor/mcp.json
- 用途：让 AI 读懂 HAP 接口文档
💡 下一步：
- 重启 Cursor 使所有配置生效
- 现在可以使用最新的 HAP 技能了
📚 技能位置：
~/.claude/skills/
├── hap-v3-api/
├── hap-view-plugin/
├── hap-frontend-project/
└── hap-mcp-usage/🔍 技能文件格式规范
每个技能文件（SKILL.md）应该遵循以下格式：
---
name: skill-name
description: 技能描述，说明何时使用此技能
license: MIT
---
# 技能标题
技能正文内容...Frontmatter 字段说明
- name: 技能名称，必须与目录名一致
- description: 技能描述，说明使用场景和触发关键词
- license: 许可证（通常为 MIT）
📊 技能更新记录
记录每次更新的内容：
2026-01-14
- ✅ 初始版本，包含 4 个核心技能
- ✅ 建立更新流程和检查清单
🛠️ 故障排查
问题 1: 技能文件不存在
症状: ls: ~/.claude/skills/hap-xxx/SKILL.md: No such file or directory
解决方案:
# 创建技能目录
mkdir -p ~/.claude/skills/hap-v3-api
mkdir -p ~/.claude/skills/hap-view-plugin
mkdir -p ~/.claude/skills/hap-frontend-project
mkdir -p ~/.claude/skills/hap-mcp-usage
# 从仓库复制文件
cp /path/to/hap-skills-collection/.claude/skills/*/SKILL.md ~/.claude/skills/*/问题 2: 技能文件格式错误
症状: AI 无法识别技能
解决方案:
- 检查 frontmatter 格式是否正确
- 确保文件编码为 UTF-8
- 检查是否有语法错误
问题 3: 更新后技能未生效
症状: 更新文件后，AI 仍使用旧版本
解决方案:
- 重启 AI 工具（Claude Code CLI、Cursor 等）
- 清除缓存（如果工具支持）
- 验证文件修改时间是否为最新
📚 相关资源
- GitHub 仓库: https://github.com/garfield-bb/hap-skills-collection
- 技能文档: 每个技能的 SKILL.md 文件
- 更新日志: GitHub 仓库的 commit 历史
💡 最佳实践
- 定期更新: 建议每周或每月更新一次技能
- 版本控制: 使用 git 管理技能文件，便于回滚
- 备份: 更新前备份现有技能文件
- 验证: 更新后验证技能是否正常工作
- 文档同步: 更新技能时同步更新 README.md
🎯 使用场景
当用户提到以下内容时，使用此技能：
- "更新 hap-skills"
- "同步最新的技能"
- "更新 skill"
- "维护技能"
- "检查技能版本"
- "更新 hap-v3-api"
- "更新视图插件技能"
注意: 此技能仅用于更新和维护 HAP Skills Collection 中的 4 个核心技能。如果需要添加新技能或修改技能内容，请参考各技能的 SKILL.md 文件。