创建或审查 Grafana SKILL.md 时：按四维…

在编写、审查或修复 Grafana Agent Skill 的 SKILL.md，使其通过 lint 与 Tessl ≥75 的 CI 门禁并获得高分时，按该流程执行。

适用场景

解决思路

1. 把 description 作为主要触发入口：使用第三人称、≤1024 chars、包含显式 `Use when...` 句式，并列出用户自然会说的具体触发词；参考 references/descriptions.md 的 pushy-description pattern 防止 undertriggering。
2. 控制正文在 500 行以内；接近上限时拆到 references/*.md，让 SKILL.md 只做路由层，而不是承载整个知识库。
3. references 只保留一层嵌套：从 SKILL.md 直接链接，禁止 SKILL.md → a.md → b.md；因为 Claude 可能对嵌套链使用 `head -100` 预览而漏掉内容。
4. 使用祈使语气：写 `Run X`，不要写 `You should run X` 或 `It is important to run X`；优先解释 why，少用重手 `MUST` 标记。
5. 用具体示例代替散文：提供可复制粘贴的命令、真实配置片段；Tessl 的 actionability 维度会直接评分这一点。
6. 不要在 `name` 中使用保留词：skill 名称禁止出现 `anthropic` 和 `claude`。
7. 不要在正文使用时间敏感语言，例如 `after August 2025…` 会腐烂；遗留信息放进 `<details>` “Old patterns” 区块。
8. 提交前验证：运行 `./scripts/lint-skills.sh skills/<plugin>/<your-skill>` 必须 clean，且 Tessl 分数 ≥75；运行 `tessl skill review --json <dir>` 查看分数。
9. 按四项 0-3 维度自评并确保 CI 通过：conciseness、actionability、workflow clarity、progressive disclosure；任一被改动的 SKILL.md 低于 75 会导致 PR 失败；完整评分和 Anthropic 文档映射见 references/rubric.md。
10. 考虑评分方差：评审是 LLM，run-to-run 会波动 7-10 分，本地 94 常到 CI 85；只在连续三次本地 100 时才 ship。
11. 决定新技能归属：选择正确插件目录 `grafana-core/`、`grafana-cloud/`、`grafana-lgtm/`、`grafana-app-sdk/`、`grafana-k6/`、`grafana-plugins/`；若都不合适，先问用户再创建新 plugin group（新 group 需更新三个 `marketplace.json` 文件）。
12. 估算正文长度并选择结构：<200 行实质内容用单个 SKILL.md，不打包；200-500 行用 SKILL.md + `references/<topic>.md` 承载长文材料；>500 行必须拆成 bundle，参考 references/anatomy.md § Splitting strategies。
13. 先写 pushy description：description 是唯一始终加载到上下文的内容；若 agent 不触发该 skill，其他内容都无意义；模式见 references/descriptions.md。
14. 按四维 rubric 起草正文：删除 Claude 已知道的所有句子（Conciseness）；把 prose 解释替换为 code blocks（Actionability）；为每个多步骤流程编号并在末尾增加 validation step（Workflow clarity）；若想用 `<details>`，考虑内容是否应放到 references/（Progressive disclosure）。
15. 注册到 marketplace manifests：把 skill path 添加到三个文件的 `skills` 数组：`.claude-plugin/marketplace.json`、`.cursor-plugin/marketplace.json`、`.agents-plugin/marketplace.json`。
16. 本地验证第 1 步：运行 `./scripts/lint-skills.sh skills/<plugin>/<your-skill>`，要求 0 errors。
17. 本地验证第 2 步：运行 `tessl skill review --json skills/<plugin>/<your-skill> | jq '.review.reviewScore'`，要求 ≥75（CI gate）。
18. 若低于 75 或想达到 ≥85：运行 `tessl skill review --optimize --yes --max-iterations 3 skills/<plugin>/<your-skill>`（需要 auth）。
19. 若运行失败：阅读 lint error / Tessl suggestion，修复，再重新运行；两项检查都干净前不要开 PR；使用 validate-fix-rerun 反馈循环而不是一次性写作。
20. 读取 judge 的逐字 Suggestions 文本（非 JSON 输出）：运行 `tessl skill review skills/<plugin>/<name>`；每个维度下的 `Suggestions:` 区块会指出要删除的确切句子/章节；复制该建议，不要猜；然后确认最低维度与你的判断一致。
21. 对 Conciseness 1-2：删除 intros、definitions、主要指向 refs 的多行表格。
22. 对 Actionability 1-2：用 code blocks 和 CLI commands 替换 prose。
23. 对 Workflow clarity 1-2：增加 numbered steps + validation checkpoints。
24. 对 Progressive disclosure 1-2：拆分到 references/*.md。
25. 若 skill 有意作为 routing document（如 `grafana-k6/k6-docs`）：不要让 `--optimize` 把 bundle inline 回 SKILL.md；手工在 SKILL.md 内写最小可复制粘贴的 “validation loop”，使 SKILL.md 可独立执行，同时保留 bundle。
26. 本地重新评分五次；直到五次都达到 100 才停止（原因见 Score variance）。
27. 查看 anti-patterns：参考 references/anti-patterns.md，避免其中列出的做法。
28. 需要时查阅以下资料：references/descriptions.md、references/rubric.md、references/anatomy.md、references/anti-patterns.md、Anthropic — Agent Skills best practices、anthropics/skills — skill-creator SKILL.md、The Complete Guide to Building Skills for Claude PDF。

适用边界 · 注意事项

• 不适用于非 Grafana skills 仓库：插件目录、三份 `marketplace.json`、CI/Tessl ≥75 门禁和 Tessl `--optimize` 是仓库特定流程；没有这些工具或账号时不能照搬。
• 不适用于普通文档或不需要被 agent 自动触发的 README/说明文写作；此时无需 pushy description 和 SKILL.md 结构。
• 如果无法运行 lint/Tessl 且不能做本地多轮评分，不要依赖本经验的 CI 门禁与 score variance 规则。