はじめに

starlight-skills は Astro Starlight 向けのプラグインです。 ドキュメントサイトの著者が、ドキュメントページと AI エージェントがインストール可能なスキル を一元管理できるようにすることを目的としています。

starlight-skills の哲学

昨今、AIによる開発はデザイン・コーディング・レビューなど多くの場面で主流になってきているものの、依然として人間の手から離れていない領域も存在します。

すべてを AI に任せようとする動きがある一方で、それによって障害が多くなり、人間の手にコントロールを戻すような動きもあります。はっきりとした結論が出ていない今の状況において、ドキュメントは人間とAIのどちらにとっても最適であるべきであるという主張が、このプラグインの原点であり、最も重要なコンセプトです。

このプラグインを使用することで、一つのリポジトリ・一つの Markdown ファイルが、人間向けの知識ベースとしても機械向けの手順書としても機能するようになります。

2つのユースケース

このプラグインは性格の異なる 2 つのユースケースを想定しています。どちらのユースケースにおいても、1つのページがドキュメントとスキルの両方として機能 するため、著者が内容を二重管理する必要はありません。

Axis A: ドキュメントをスキルにする

人間向けに書かれたドキュメントを、そのまま AI のスキル（ルールセット）として利用させる場合です。

• 主たる対象: 人間の読者
• AIの役割: ドキュメントの内容を手順・ルール・知識として利用します。
• 構成: 従来のドキュメントの慣習に従います（説明・例示・背景・根拠を含む）。
• 著者のフォーカス: 人間に伝わりやすいドキュメントを書くことだけに集中します。AI スキル形式への変換はプラグインが裏側で担います。

Axis B: スキルをドキュメントにする

AI 向けに書かれたスキル（プロンプト）を、人間にも読ませたい規約やガイドラインとして公開する場合です。

• 主たる対象: AI エージェント
• 人間の役割: サイト上のスキル内容を規約や開発ルールとして参照・確認します。
• 構成: AIスキルの慣習に従います（簡潔・命令的・箇条書き中心の Do / Don’t 形式）。
• 著者のフォーカス: AIのパフォーマンスが最大化するようなスキル指示を書くことに集中します。それが美しく整理されたポータルとして Starlight 上に展開されます。