volcengine-skills CLAUDE.md

volcengine-skills

本仓库是 Volcengine Team 维护的 skill marketplace，为 AI coding agent 提供火山引擎场景能力。

仓库结构

• skills/：只保留 core/ 分类。
• skills/core/：只允许 volcengine-cli、volcengine-troubleshooting、volcengine-knowledge-search、volcengine-find-skills。
• plugins/volcengine-core/：默认核心 plugin，包含 hooks 和上述四个 core skill 的生成副本。
• plugins/volcengine-<domain>/：按产品域拆分的可选 plugin，也是其 skill 的唯一源码位置。
• scripts/sync_plugins.py：从 finder catalog 复制 core skill，并生成 plugin manifest 与 marketplace。
• scripts/validate_codex_plugin_layout.py：校验目录、清单、同步状态和默认安装约束。
• hooks/：跨 skill 复用的 telemetry hook。

核心 skill 只修改 skills/core/，不要直接修改 plugins/volcengine-core/skills/。可选 skill 则直接修改所属 plugins/volcengine-<domain>/skills/。

什么时候使用

• 操作火山引擎 ECS / VPC / VKE / CLB / RDS / Redis / TOS / DNS / CDN 等资源。
• 使用 ve、tosutil、veFaaS 或 Volcengine SDK。
• 处理火山引擎部署、监控、运维、合规、Landing Zone 等场景。
• 用户消息包含「火山」「火山引擎」或 volcengine。
• 用户需要查找或安装尚未加载的 Volcengine skill。

修改约束

• 所有 skill 必须以 volcengine- 为前缀；读 env / 调 bin 必须在 metadata.openclaw.requires 声明。
• 用户补充某个 API 的精确 payload、Action、Version 或服务名时，脚本、skill 正文、reference 和测试示例必须同步使用该精确值。
• 跨 skill 经验放在“决策发生的 skill”里；工具型 skill 只保留自身能力、参数约束和安全边界。
• 不要把一次验证里的具体地域、规格、镜像、镜像源候选、清理顺序或临时资源形状写成默认流程，除非它是强依赖约束。
• 排障 skill 按症状、证据类型和判断分支组织；仅在存在真实依赖时规定顺序。
• 不得提交账号信息、AK/SK、本地绝对目录、真实资源 ID 或 TRN。
• 资源 ID 脱敏时保留固定前缀，例如 vpc-<id>、clb-<id>；账号或数字 ID 使用 <account-id> 等语义占位符。

新增或移动 skill

1. 核心 skill 放在 skills/core/volcengine-<name>/；可选 skill 放在 plugins/volcengine-<domain>/skills/volcengine-<name>/。
2. 更新 skills/core/volcengine-find-skills/references/catalog.json 中的 plugin 和 skill 映射。
3. 同步更新 README.md、README_en.md、.cursor/rules/volcengine-skills.mdc、GEMINI.md 的 skill 清单。
4. 运行 python3 scripts/sync_plugins.py 复制 core skill 并生成 manifest。
5. 运行 python3 scripts/validate_codex_plugin_layout.py，确保 core 目录、marketplace 策略和 core 副本一致。
6. 运行 python3 -m unittest discover -s tests -v，验证同步器的路径与写入边界。

不要手工维护 plugins/volcengine-core/skills/、plugin manifest 或 marketplace 条目；它们由 catalog 和同步脚本生成。可选 plugin 的 skills/ 是源码，必须直接维护。