maplibre-skill-authoring

セッションからスキルを作成する

maplibre-agent-skillsにとって最も価値のある入力は、エージェントがMapLibreについて誤った回答をし、調べ直して正しい答えを見つけ、動作するコードを完成させたセッションです。そのセッションには、後から再構築できないものがあります。最初に出てきた誤った回答です。 これはスキルを作る必要があることを示す証拠であり、コンテキストが終わるまでしか存在しません。

このスキルは、その収穫について説明します。貢献方法を繰り返し説明するものではありません。エージェント固有のルールはAGENTS.mdに、新しいスキルを作成するための手順と4つのステップはCONTRIBUTING.mdに記載されています。引き継ぎの際にはそちらを読み、セッションが終わる前にこの文書を読んでください。セッションが終わると、以下の内容のほとんどは取り戻せません。

このスキルを使う場面

• MapLibreのタスクで、ドキュメント、ソースコード、CHANGELOG、Issueスレッドなどを実際に調べる必要があった
• 最初のアプローチが誤っていた、またはMapbox GL JSでは正しくてもMapLibreでは誤っていた
• ドキュメントに明記されていないバージョン境界、注意点、失敗パターンが見つかった
• セッションをスキルとして記録するよう依頼された

まず記録し、判断は後でする

セッションがまだ開いているうちに行ってください。スクラッチファイルに4つの項目を記録します。

1. 最初の誤った回答を一字一句そのまま記録します。 確認する前に断言したこと、書いたこと、または書くつもりだったことです。これは仮説の基準点であり、後から再構築できない唯一の成果物です。正しい答えがコンテキストに入ると、モデルは要求されても再び誤った答えを出さないからです。モデルがそれなしでは失敗する場合にのみスキルを追加する価値があるため、これが評価テストを書けるようにする要素です。
2. 実際に開いた一次資料を記録します。 記憶ではなくURLを記録してください。スタイル仕様のページ、GL JSドキュメントのページ、PRやIssue、CHANGELOGの項目などです。後から記憶をたどって再構築した引用は、リンクの形をした推測です。
3. 正しい主張を1、2文で記録します。 何をしたかという説明ではなく、ルールとして書いてください。
4. バージョンと最小限の再現例を記録します。 使用したMapLibreのバージョン、SDK（GL JSとNativeでは挙動が異なります）、動作を示す最小のスタイルまたはコードを記録してください。

主張とプロジェクトを切り分ける

上記の情報は、すべて元のコードベースと絡み合っています。各項目について、**「これは別の人のプロジェクトでも正しいか？」**を判断基準にしてください。

• プロジェクト名、ファイルパス、内部アーキテクチャ、ビジネスロジックは取り除きます。コード例がアプリに依存している場合は、最小構成のマップを使って書き直してください。
• バージョン境界は残します。「Xより前では壊れていて、それ以降では動く」は有用な判断材料ですが、「動く」だけでは不十分です。
• 誤った回答にもっともらしさがあった理由は残します。これが次のエージェントの失敗を防ぐ手がかりになります。多くの場合、Mapbox GL JSでの慣習、または古くなった学習データの思い込みが原因です。
• 機密情報は公開しません。報告を匿名化してください。失敗は共有しても、勤務先のコードは共有しません。

書き始める前に規模を決める

1つのセッションの失敗から作るのは、テスト1つとセクション1つです。通常は、既存のスキルへの追加になります。新しいスキルを作ると決める前に、利用可能なスキルと未解決のIssueを確認してください。

新しいスキルを作るのが妥当なのは、その主張に既存の置き場所がない場合に限ります。公開済みのスキルのサブトピックではなく、既存のスキルが扱うべきものでもない場合です。まずセクションを追加し、次にスキル間の参照を追加し、それから最後の手段として新しいスキルを作成してください。

下書きではなく、セッションから評価を作成する

内容を書く前に、記録した成果物を評価にまとめます。伝えようとしていることではなく、実際に起きたことをもとに書いてください。

• プロンプトは、プロジェクト名を除いた、セッションが実際に始まったときの質問です。
• ルーブリックには正しい主張（成果物 3）を記載します。自分の下書きの表現に合わせるのではなく、第三者の回答を採点できるような表現にしてください。
• icontains のトリップワイヤーには、誤った回答が作り出した名前（成果物 1）を not-icontains として指定し、本当の名前を icontains として指定します。セッションで API 名が幻覚されたなら、これほど鋭いトリップワイヤーを書く機会はそうありません。

仕組み、プロバイダーのセットアップ、ベースラインの実行方法については、evals/README.md を参照してください。

正直に引き継ぐ

作成しているのは提案であり、検証済みのスキルではありません。そのことを伝えるのも引き継ぎの一部です。どの主張を一次資料で検証し、どれを検証できなかったのかを明記してください。API キーがない、またはリポジトリのクローンの外で作業しているなどの理由で評価を実行できない場合は、省略せず、その旨を明確に伝えてください。また、プルリクエストとその説明は、レビューで責任を負う人に任せてください。

成果物 1、2、4 を含む失敗報告は、それだけで完全な貢献です。裏付けのないスキルの下書きよりも価値があります。

しないこと

• トランスクリプトを貼り付けないでください。 セッションは資料であり、成果物ではありません。
• 開いていない資料を引用しないでください。 参照を再構成することは、誤った主張が自信満々にレビューを通過する最も一般的な原因です。
• 実行していない評価結果を報告しないでください。 また、評価の実行に必要な API キーをでっち上げないでください。
• プロジェクト固有の癖をスキルに昇格させないでください。 修正が自分のビルド環境に依存していたなら、それは MapLibre の知見ではありません。
• 回答が明らかに欠けているように感じても、ベースラインを省略しないでください。 モデルはすでに正解しているかもしれません。その判明自体が報告する価値のある結果であり、行き止まりではありません。

関連スキル

• maplibre-mapbox-migration — Mapbox GL JS の習慣を引き継いでしまう、もっともらしい誤答の最初の発生源です。

参考資料

• AGENTS.md — このリポジトリでエージェントが作業する際の指針。リポジトリの外から失敗を報告する場合にも役立ちます。
• CONTRIBUTING.md — 貢献の方法と、それぞれに必要な内容
• evals/README.md — プロンプト、ルーブリック、ベースラインチェック、プロバイダーのセットアップ
• Agent Skills specification — SKILL.md の仕様

---

このスキルはある時点の情報を切り取ったものです。 一次資料（上記の参考資料、MapLibre の最新ドキュメント、または実行時の MapLibre の挙動）がこの内容と矛盾する場合は、一次資料を優先してください。それに従ったうえで、資料と MapLibre のバージョンを明記して相違を報告してください。インストール済みのコピーを編集しても、ほかの人の役には立たず、次回の更新で上書きされます。