add-skill

添加面向用户的技能

用于在 skills/ 中创建技能的端到端工作流，旨在教会 AI Agent 如何使用 cx CLI 命令。通常会在 add-command 第 6 步调用此技能；也可以单独使用，为现有命令编写文档。

contributing/adding-a-skill.md 提供了完整的参考指南和可直接复制粘贴的模板。请结合本工作流阅读。

步骤 0：了解领域

开始编写前，请回答以下问题：

1. 你要编写文档的是哪个 cx 命令？ 找出该命令及其所有子命令（例如，cx alerts list、cx alerts get、cx alerts create）。
2. 用户可以用它做什么？ 列出支持的关键操作、标志和输出格式。
3. 目标读者是谁？ 技能是供 AI Agent 使用的，而不是直接面向人类。请编写 Agent 可以逐步遵循、以实现用户目标的指令。
4. 是否有大量参考资料？ 超过约 100 行的架构、枚举目录、字段参考或语言语法应放在单独的 references/ 文件中。

步骤 1：阅读现有技能

编写任何技能前，请先阅读现有技能，熟悉项目的惯例。先研究现有技能的 Agent 能产出一致的高质量结果，而不是另创格式。

务必阅读：

• contributing/adding-a-skill.md——完整指南，涵盖目录结构、frontmatter 约定、参考文件规则和可直接复制粘贴的模板
• skills/README.md——要在步骤 4 中更新的公开目录

至少研究以下两个现有技能：

技能	研究原因
skills/cx-alerts/SKILL.md	基于 REST 的命令，包含丰富示例、JSON 负载和调查工作流；同时使用共享参考文件和技能本地参考文件
skills/cx-telemetry-querying/SKILL.md	网关技能，按支柱加载共享参考文件——适合作为跨支柱路由和参考文件加载模式的范例
skills/cx-dashboards/SKILL.md	复杂的多步骤工作流；使用共享参考资料（dataprime、promql、logs、spans）以及技能本地参考文件
skills/cx-cost-optimization/SKILL.md	涵盖 5 个命令的工作流技能，统一目标为“降低成本”——适合作为多命令技能的范例

选择与当前工作最接近的两个技能，并完整阅读。

步骤 2：创建目录并编写 SKILL.md

创建 skills/cx-<domain-name>/SKILL.md。所有技能目录都使用 cx- 前缀。使用 contributing/adding-a-skill.md 中“Directory Structure”至“Complete Template”（单命令）的目录结构、frontmatter 格式和模板，或者使用“Workflow Skills”（多命令）一节中的内容。

编写有效的触发描述

frontmatter 中的 description 字段是主要触发机制——Agent 会据此决定何时启用技能。这是文件中最重要的一行。请至少写 10 个触发短语，涵盖：

• 明确的命令名称（“列出告警”、“按 ID 获取告警”）
• 用户意图（“调查告警故障”、“调试嘈杂的告警”）
• 同义词和不同说法（“检查”、“查找”、“搜索”、“分析”）
• 领域术语（“SLO 违规”、“错误预算”）

正文结构

按以下顺序编写（起始模板见 contributing/adding-a-skill.md 的“Complete Template”一节）：

1. 标题和简介——用一句话说明技能涵盖的内容以及所用的 cx 命令
2. CLI 命令表——为每个子命令添加一行，列为 | Command | Purpose | Key flags |。注明 -o json/-o toon 和 -p <profile> 的用法。
3. 工作流 / 调查步骤——列出 Agent 应遵循的编号步骤。从发现开始，以验证结束。
4. 关键原则——列出 4-6 个要点：使用 -o json 搭配 jq、多配置文件行为、始终验证等。
5. 其他资源——链接到 references/ 文件和相关技能

风格指南

• 面向 AI Agent 编写——明确说明要运行什么以及运行顺序
• 每个命令行调用都使用代码块
• 提供包含实际标志值而非占位符的真实示例
• 如果命令支持 -o json，请展示 jq 过滤示例
• 将 SKILL.md 控制在约 200 行以内；将大量内容移至 references/

第 3 步：添加参考文件并更新 README

关于何时以及如何创建 references/ 文件，请参阅 contributing/adding-a-skill.md §“Reference Files”；关于如何将技能添加到公开目录，请参阅 §“Updating skills/README.md”。

共享参考与技能专属参考

创建新的参考文件之前，请确认内容属于语言级材料还是遥测支柱材料：

• 语言指南（DataPrime 语法、PromQL 指南）→ skills/shared/
• 遥测支柱操作指南（日志查询、跨度查询、指标工作流、RUM）→ skills/shared/
• 技能专属架构或模板（告警 JSON 架构、仪表板组件模板）→ skills/cx-your-domain/references/

如果你的技能需要 skills/shared/ 中的文件：

1. 将你的技能和文件列表添加到 scripts/sync-shared-references.sh
2. 运行 bash scripts/sync-shared-references.sh——它会将文件复制到你的 references/ 中
3. 将同步脚本的更改与生成的 references/ 副本一起提交

如果要添加新的共享参考文件：

1. 在 skills/shared/ 中创建文件
2. 在同步脚本中为所有使用该文件的技能注册该文件
3. 运行脚本以生成副本，然后提交所有内容

第 4 步：验证

1. Frontmatter——name 与目录名称一致，description 包含 10 个以上的触发短语，metadata.version 为 "0.1.0"
2. 正文完整性——包含 CLI 命令表、工作流步骤、关键原则，以及附加资源（如果存在参考文件）
3. 参考链接——SKILL.md 中的任何 references/ 路径都指向实际存在的文件
4. README 已更新——skills/README.md 中包含新增的条目
5. 避免臃肿——SKILL.md 不重复超过 100 行本应放在 references/ 中的内容
6. 共享参考已同步——如果技能使用 skills/shared/ 中的文件，请确认已运行 bash scripts/sync-shared-references.sh，并已提交生成的 references/ 副本
7. 便于 Agent 阅读——AI Agent 读完此技能后，是否清楚该怎么做？如果不清楚，请补充缺少的步骤或示例

如需优化高级触发条件，请使用 /skill-creator 技能运行基于评估的描述测试，并迭代改进触发短语。

在 PR 描述中使用 contributing/adding-a-skill.md §“PR Checklist”中的 PR 检查清单。