skill-authoring

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Authoring & Improving Grafana Skills

编写与改进Grafana Skills

How to write, review, and improve SKILL.md files so they pass the repo's CI gate and score well against the Anthropic-aligned rubric Tessl uses.

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

Critical rules (always)

核心规则（必须遵守）

Description is the primary trigger — third-person, ≤1024 chars, must include explicit "Use when..." phrasing AND list concrete trigger terms users naturally say. See references/descriptions.md for the pushy-description pattern that combats undertriggering.
Body under 500 lines — split into
```
references/*.md
```
if approaching the limit. SKILL.md is the routing layer, not the entire knowledge base.
One level of nesting for references — link from SKILL.md directly, never
```
SKILL.md → a.md → b.md
```
. Claude may use
```
head -100
```
previews on nested chains and miss content.
Imperative voice — "Run X" not "You should run X" not "It is important to run X". Explain why over heavy-handed
```
MUST
```
markers.
Concrete examples beat prose — copy-paste-ready commands, real config snippets. Tessl's
```
actionability
```
dimension scores this directly.
No reserved words in
name
—
```
anthropic
```
and
```
claude
```
are forbidden in skill names.
No time-sensitive language in the body — "after August 2025…" rots. Use an
```
<details>
```
"Old patterns" section for legacy info instead.

Validate before committing —

./scripts/lint-skills.sh skills/<plugin>/<your-skill>

clean + Tessl score ≥75 (run

tessl skill review --json <dir>

描述是主要触发条件 —— 第三人称，≤1024字符，必须包含明确的“适用于……”表述，并列出用户自然会使用的具体触发词汇。请查看references/descriptions.md了解解决触发不足问题的“主动式描述”模式。
正文不超过500行 —— 若接近此限制，拆分至
```
references/*.md
```
中。SKILL.md是路由层，而非完整知识库。
引用仅支持一级嵌套 —— 直接从SKILL.md链接，禁止
```
SKILL.md → a.md → b.md
```
的嵌套方式。Claude可能对嵌套链使用
```
head -100
```
预览，从而遗漏内容。
使用祈使语气 —— 用“执行X”而非“你应该执行X”或“执行X很重要”。通过解释原因替代生硬的
```
MUST
```
标记。
具体示例优于文字描述 —— 提供可直接复制粘贴的命令、真实配置片段。Tessl的“可操作性”维度会直接对此评分。
name
字段中禁止使用保留词 —— skill名称中禁止使用
```
anthropic
```
和
```
claude
```
。
正文禁止使用时效性语言 —— 类似“2025年8月之后……”的内容会失效。如需保留旧信息，可使用
```
<details>
```
标签创建“旧模式”章节。
提交前验证 —— 运行
```
./scripts/lint-skills.sh skills/<plugin>/<your-skill>
```
确保无错误，且Tessl评分≥75（运行
```
tessl skill review --json <dir>
```
查看分数）。

The rubric

评分标准

CI fails any PR where a touched SKILL.md scores below 75 on four 0-3 dimensions: conciseness, actionability, workflow clarity, progressive disclosure. Full per-dimension scoring + Anthropic-doc mapping in references/rubric.md.

若被修改的SKILL.md在四个0-3分维度（简洁性、可操作性、工作流程清晰度、渐进式披露）中的总分低于75，CI将拒绝该PR。各维度详细评分标准及与Anthropic文档的对应关系请查看references/rubric.md。

Score variance

分数波动

The judge is an LLM and swings 7-10 points run-to-run. Local 94 commonly lands at CI 85. Ship only on three consecutive local 100s.

评分由LLM执行，每次运行分数波动7-10分。本地测试得94分，在CI中通常会降到85分。仅当连续三次本地测试均得100分时再提交。

Decision tree for a new skill

新skill决策树

What product / domain does this skill belong to? Pick the right plugin folder:
```
grafana-core/
```
,
```
grafana-cloud/
```
,
```
grafana-lgtm/
```
,
```
grafana-app-sdk/
```
,
```
grafana-k6/
```
,
```
grafana-plugins/
```
. If none fits cleanly, ask the user before creating a new plugin group (a new group requires updating three
```
marketplace.json
```
files).
Estimate body length.
- <200 lines of substance → single
```
SKILL.md
```
  , no bundle
- 200-500 lines →
```
SKILL.md
```
  +
```
references/<topic>.md
```
  for the long-form material
- 500 lines → mandatory bundle split; see references/anatomy.md § Splitting strategies
Write a "pushy" description first. The description is the only thing always loaded into context. If agents don't trigger the skill, nothing else matters. See references/descriptions.md for the pattern.
Draft body with the four-dimension rubric in mind.
- Cut every sentence Claude already knows (Conciseness)
- Replace prose explanations with code blocks (Actionability)
- Number every multi-step procedure + add a validation step at the end (Workflow clarity)
- If you reach for
```
<details>
```
  , consider whether that content belongs in
```
references/
```
  instead (Progressive disclosure)

Register in marketplace manifests. Add the skill path to the

skills

array in all three:

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

Validate locally.

bash

# 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>

If the run fails: read the lint error / Tessl suggestion, fix, re-run. Don't open the PR until both checks pass cleanly. The feedback-loop pattern beats one-shot writing.

该skill属于哪个产品/领域？ 选择合适的插件文件夹：
```
grafana-core/
```
、
```
grafana-cloud/
```
、
```
grafana-lgtm/
```
、
```
grafana-app-sdk/
```
、
```
grafana-k6/
```
、
```
grafana-plugins/
```
。若没有完全匹配的文件夹，创建新插件组前需询问用户（新组需更新三个
```
marketplace.json
```
文件）。
预估正文长度
- 实质内容<200行 → 单个
```
SKILL.md
```
  ，无需打包
- 200-500行 →
```
SKILL.md
```
  +
```
references/<topic>.md
```
  存储长内容
- 500行 → 必须拆分为包；请查看references/anatomy.md § 拆分策略
先编写“主动式”描述 描述是始终加载到上下文的唯一内容。如果agents无法触发该skill，其他内容都无关紧要。请查看references/descriptions.md了解具体模式。
结合四维评分标准撰写正文草稿
- 删除Claude已知晓的所有句子（简洁性）
- 用代码块替代文字解释（可操作性）
- 为所有多步骤流程编号，并在末尾添加验证步骤（工作流程清晰度）
- 若考虑使用
```
<details>
```
  标签，先判断该内容是否更适合放在
```
references/
```
  中（渐进式披露）

在市场清单中注册 将skill路径添加到以下三个文件的

skills

数组中：

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

本地验证

bash

# 1. 检查无错误（0个错误）
./scripts/lint-skills.sh skills/<plugin>/<your-skill>

# 2. Tessl评审分数≥75（CI门槛）
tessl skill review --json skills/<plugin>/<your-skill> | jq '.review.reviewScore'

# 3. 若分数低于75或想要≥85：运行--optimize（需要授权）
tessl skill review --optimize --yes --max-iterations 3 skills/<plugin>/<your-skill>

若运行失败：阅读检查错误/Tessl建议，修复后重新运行。直到两项检查均通过后再提交PR。“反馈循环”模式优于一次性编写。

Fixing a low-scoring existing skill

修复低评分现有skill

Read the judge's verbatim Suggestions text (non-JSON output):
bash
```
tessl skill review skills/<plugin>/<name>
```
The
```
Suggestions:
```
block under each dimension names the exact sentences/sections to cut. Copy the suggestion — don't guess. Then verify the lowest dimension matches your read.
Apply the fix pattern from references/rubric.md:
- Conciseness 1-2 → cut intros, definitions, multi-line tables that mostly point to refs
- Actionability 1-2 → replace prose with code blocks and CLI commands
- Workflow clarity 1-2 → add numbered steps + validation checkpoints
- Progressive disclosure 1-2 → split into
```
references/*.md
```
If the skill is intentionally a routing document (like
```
grafana-k6/k6-docs
```
), don't let
```
--optimize
```
inline the bundle back into SKILL.md. Hand-craft a minimal copy-paste "validation loop" inline so SKILL.md is independently actionable, while preserving the bundle.
Re-score five times locally. Don't stop until all five runs hit 100 — see "Score variance" above for why.

阅读评审者的原始建议文本（非JSON输出）：
bash
```
tessl skill review skills/<plugin>/<name>
```
每个维度下的
```
Suggestions:
```
块会指出需要删除的具体句子/章节。直接采纳建议——不要猜测。然后确认得分最低的维度是否与你的判断一致。
应用references/rubric.md中的修复模式：
- 简洁性1-2分 → 删除介绍、定义、主要指向引用的多行表格
- 可操作性1-2分 → 用代码块和CLI命令替代文字描述
- 工作流程清晰度1-2分 → 添加编号步骤和验证检查点
- 渐进式披露1-2分 → 拆分至
```
references/*.md
```
  中
若该skill是有意设计的路由文档（例如
```
grafana-k6/k6-docs
```
），不要让
```
--optimize
```
将包内容重新内联到SKILL.md中。手动编写一个最小化的“验证循环”内联到SKILL.md中，使其具备独立可操作性，同时保留包结构。
本地重新评分五次。直到五次运行均得100分再停止——原因请参考上文“分数波动”部分。

Anti-patterns

反模式

See references/anti-patterns.md.

请查看references/anti-patterns.md。

References

参考资料

```
references/descriptions.md
```
— the pushy-description pattern + trigger-term checklist
```
references/rubric.md
```
— per-dimension scoring with Anthropic-doc citations and concrete fix patterns
```
references/anatomy.md
```
— three-level progressive disclosure, bundle layout, splitting strategies
```
references/anti-patterns.md
```
— what NOT to do, with examples
Anthropic — Agent Skills best practices
anthropics/skills — skill-creator SKILL.md
The Complete Guide to Building Skills for Claude (PDF)

```
references/descriptions.md
```
—— 主动式描述模式 + 触发词汇清单
```
references/rubric.md
```
—— 各维度评分标准，包含Anthropic文档引用及具体修复模式
```
references/anatomy.md
```
—— 三级渐进式披露、包布局、拆分策略
```
references/anti-patterns.md
```
—— 禁止操作示例
Anthropic — Agent Skills最佳实践
anthropics/skills — skill-creator SKILL.md
《Claude Skills构建完全指南》(PDF)