skill-authoring

Grafana スキルの作成と改善

リポジトリの CI ゲートを通過し、Tessl が使用する Anthropic 準拠の評価基準で高得点を得るために、SKILL.md ファイルを作成、レビュー、改善する方法です。

重要なルール（常に守ること）

1. 説明が主なトリガーです — 三人称で、1024 文字以下にし、「Use when...」という表現を明示的に含め、ユーザーが自然に使う具体的なトリガー語を列挙します。発動不足を防ぐための強めの説明パターンについては、references/descriptions.md を参照してください。
2. 本文は500行未満にします — 上限に近づいたら references/*.md に分割します。SKILL.md はルーティング層であり、ナレッジベース全体ではありません。
3. 参照のネストは1階層にします — SKILL.md から直接リンクし、SKILL.md → a.md → b.md とはしないでください。Claude はネストされた連鎖のプレビューに head -100 を使用し、内容を見落とす可能性があります。
4. 命令形を使います — 「X を実行してください」とし、「X を実行するべきです」や「X を実行することが重要です」とはしません。強引な MUST マーカーを多用するより、理由を説明してください。
5. 具体例は説明文に勝ります — コピーしてすぐ使えるコマンドや、実際の設定スニペットを用意します。Tessl の actionability 次元では、これが直接評価されます。
6. name に予約語を使いません — anthropic と claude はスキル名で使用できません。
7. 本文で時期に依存する表現を使いません — 「2025年8月以降は……」のような記述はすぐに古くなります。古い情報には <details> の「古いパターン」セクションを使用してください。
8. コミット前に検証します — ./scripts/lint-skills.sh skills/<plugin>/<your-skill> がエラーなしで完了し、Tessl のスコアが75以上であることを確認します（tessl skill review --json <dir> を実行）。

評価基準

変更対象の SKILL.md の4つの0～3点の次元、簡潔さ、実用性、ワークフローの明確さ、段階的な情報開示のいずれかでスコアが75を下回ると、CI は PR を失敗させます。次元ごとの完全な採点基準と Anthropic ドキュメントとの対応については、references/rubric.md を参照してください。

スコアのばらつき

評価者は LLM であり、実行ごとに7～10点変動します。ローカルで94点でも、CI では通常85点になります。ローカルで3回連続して100点を取った場合のみ、提出してください。

新しいスキルを作成するための判断フロー

1. このスキルはどの製品／ドメインに属しますか？ 適切なプラグインフォルダーを選びます：grafana-core/、grafana-cloud/、grafana-lgtm/、grafana-app-sdk/、grafana-k6/、grafana-plugins/。どれにも適切に当てはまらない場合は、新しいプラグイングループを作成する前にユーザーに確認してください（新しいグループを作成するには、3つの marketplace.json ファイルを更新する必要があります）。

2. 本文の長さを見積もります。

   • 実質的な内容が200行未満 → SKILL.md のみ。バンドルは不要です。
   • 200～500行 → SKILL.md と、長文の内容を記載する references/<topic>.md
   • 500行超 → バンドルへの分割が必須です。references/anatomy.md § Splitting strategies を参照してください。

3. まず「強め」の説明を書きます。 説明は常にコンテキストに読み込まれる唯一の情報です。エージェントがスキルを発動しなければ、それ以外は意味がありません。パターンについては references/descriptions.md を参照してください。

4. 4つの次元の評価基準を意識して本文を下書きします。

   • Claude がすでに知っている文はすべて削ります（簡潔さ）。
   • 説明文をコードブロックに置き換えます（実用性）。
   • 複数手順の手順にはすべて番号を付け、最後に検証ステップを追加します（ワークフローの明確さ）。
   • <details> を使おうとしたら、その内容を代わりに references/ に置くべきか検討します（段階的な情報開示）。

5. マーケットプレイスのマニフェストに登録します。 次の3つすべての 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>
   

   実行に失敗した場合は、リンターのエラーまたは Tessl の提案を読み、修正して再実行します。両方のチェックが問題なく通るまで PR を作成しないでください。フィードバックループを回す方法は、一度だけ書いて終わらせる方法より効果的です。

低スコアの既存スキルを修正する

1. 審査員の提案を、原文どおり（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. ローカルで5回再スコアリングします。5回すべてで100点になるまで止めないでください。「Score variance」の説明も参照してください。

アンチパターン

references/anti-patterns.md を参照してください。

参考資料

• references/descriptions.md — 強引な説明のパターンとトリガー語のチェックリスト
• references/rubric.md — Anthropic のドキュメントからの引用と具体的な修正パターンを含む、評価軸ごとの採点基準
• references/anatomy.md — 3段階の段階的な情報開示、バンドルのレイアウト、分割方法
• references/anti-patterns.md — 例を交えた、避けるべきパターン
• Anthropic — Agent Skills のベストプラクティス
• anthropics/skills — skill-creator SKILL.md
• Claude のスキル構築完全ガイド（PDF）