skill-authoring

编写和改进 Grafana Skills

如何编写、审查和改进 SKILL.md 文件，使其通过仓库的 CI 门禁，并在 Tessl 使用的 Anthropic 对齐评分标准中取得好成绩。

关键规则（始终遵守）

1. 描述是主要触发条件——使用第三人称，不超过 1024 个字符，必须包含明确的“Use when...”表述，并列出用户自然会说出的具体触发词。有关能够应对触发不足问题的强势描述模式，请参阅 references/descriptions.md。
2. 正文少于 500 行——接近上限时，将内容拆分到 references/*.md 中。SKILL.md 是路由层，而不是整个知识库。
3. 参考资料只嵌套一层——从 SKILL.md 直接链接，切勿使用 SKILL.md → a.md → b.md。Claude 可能会对多层嵌套链使用 head -100 预览，从而遗漏内容。
4. 使用祈使语气——写“Run X”，不要写“You should run X”，也不要写“It is important to run X”。着重解释原因，而不是大量使用 MUST 标记。
5. 具体示例胜过文字说明——提供可直接复制粘贴的命令和真实配置片段。Tessl 的 actionability 维度会直接对此评分。
6. name 中不得包含保留词——技能名称中禁止使用 anthropic 和 claude。
7. 正文中不得包含时效性表述——“after August 2025...” 这类内容会过时。对于旧信息，请改用 <details>“Old patterns”部分。
8. 提交前先验证——运行 ./scripts/lint-skills.sh skills/<plugin>/<your-skill>，确保无错误；Tessl 评分须达到 ≥75（运行 tessl skill review --json <dir>）。

评分标准

CI 会拒绝任何修改后的 SKILL.md 评分低于 75 的 PR。评分涵盖四个 0–3 维度：简洁性、可操作性、工作流清晰度和渐进式披露。各维度的完整评分细则以及与 Anthropic 文档的对应关系，请参阅 references/rubric.md。

评分波动

评分由 LLM 判定，同一内容每次运行的结果会波动 7–10 分。本地评分 94 通常在 CI 中会变成 85。只有本地连续三次评分 100 才能提交。

新建技能的决策树

1. 此技能属于哪个产品／领域？ 选择合适的插件目录：grafana-core/、grafana-cloud/、grafana-lgtm/、grafana-app-sdk/、grafana-k6/、grafana-plugins/。如果都不合适，请先询问用户，再创建新的插件分组（新分组需要更新三个 marketplace.json 文件）。

2. 估算正文长度。

   • 实质内容少于 200 行 → 单个 SKILL.md，不需要拆分
   • 200–500 行 → SKILL.md + references/<topic>.md，存放长篇内容
   • 超过 500 行 → 必须拆分；请参阅 references/anatomy.md § Splitting strategies

3. 先写一段“强势”描述。 描述是唯一始终会加载到上下文中的内容。如果 Agent 没有触发该技能，其他内容都无关紧要。请参阅 references/descriptions.md 了解相应模式。

4. 起草正文时牢记四维评分标准。

   • 删除 Claude 已经知道的所有内容（简洁性）
   • 用代码块替代文字说明（可操作性）
   • 为所有多步骤流程编号，并在末尾添加验证步骤（工作流清晰度）
   • 如果想使用 <details>，请考虑该内容是否更适合放在 references/ 中（渐进式披露）

5. 在 marketplace 清单中注册。 将技能路径添加到以下三个文件的 skills 数组中：

   • .claude-plugin/marketplace.json
   • .cursor-plugin/marketplace.json
   • .agents-plugin/marketplace.json

6. 在本地验证。

   # 1. Lint clean (0 errors)
   ./scripts/lint-skills.sh skills/<plugin>/<your-skill>
   
   # 2. Tessl reviewScore ≥75 (the CI gate)
   tessl skill review --json skills/<plugin>/<your-skill> | jq '.review.reviewScore'
   
   # 3. If below 75 or you want ≥85: run --optimize (requires auth)
   tessl skill review --optimize --yes --max-iterations 3 skills/<plugin>/<your-skill>
   

   如果运行失败：阅读 lint 错误或 Tessl 建议，修复后重新运行。两项检查都通过后再创建 PR。采用反馈循环的模式，优于一次性写作。

修复低分的现有技能

1. 阅读评审者逐字给出的 Suggestions 文本（非 JSON 输出）：

   tessl skill review skills/<plugin>/<name>
   

   每个维度下方的 Suggestions: 区块会指出需要删改的确切句子／章节。照抄建议，不要猜。然后确认最低分维度与你的判断一致。

2. 按照 references/rubric.md 中的修复模式进行修改：

   • 简洁性 1-2 → 删除引言、定义，以及大部分内容只是指向参考资料的多行表格
   • 可执行性 1-2 → 用代码块和 CLI 命令替换散文
   • 工作流清晰度 1-2 → 添加编号步骤和验证检查点
   • 渐进式信息披露 1-2 → 拆分到 references/*.md

3. 如果该技能本来就是路由文档（例如 grafana-k6/k6-docs），不要让 --optimize 把整个资料包内联回 SKILL.md。手工编写一段简短、可直接复制粘贴的“验证循环”并内联，使 SKILL.md 本身即可独立执行，同时保留资料包。

4. 在本地重新评分五次。除非五次运行都达到 100 分，否则不要停止——有关原因，请参阅上文的“分数波动”。

反模式

请参阅 references/anti-patterns.md。

参考资料

• references/descriptions.md — 强引导式描述模式和触发词检查清单
• references/rubric.md — 各维度评分、Anthropic 文档引文及具体修复模式
• references/anatomy.md — 三级渐进式信息披露、资料包布局和拆分策略
• references/anti-patterns.md — 不该怎么做及示例
• Anthropic — Agent Skills 最佳实践
• anthropics/skills — skill-creator SKILL.md
• 构建 Claude 技能完整指南（PDF）