SharklyのSkills：一人の開発者のプロンプト術をチームのインフラに変える

AIコーディングエージェントを導入したチームには、必ず「プロンプトがそのまま通る」開発者が1人います。その人のレビュー依頼は、チームが好む形式で構造化されて返ってきます。テスト作成の指示は、一発でハウススタイルに合ったテストを生み出します。どうやっているのか尋ねると、たいていはスクラッチファイル、dotfilesリポジトリ、あるいは毎朝新しいセッションに貼り付けている1段落の話が出てきます。その技は本物です。問題は、それがどこに存在しているかにあります。

1人の頭の中にしかないプロンプトのノウハウは、スケールしません。休暇を挟めば消えてしまいますし、他の誰かのエージェント実行に現れることもありません。その開発者が不在になれば品質は落ちます。チームがエージェント1体から5体になれば、5体の間で仕事の進め方の認識が食い違います。

そのギャップに答えるのがSharklyのスキルです。スキルは、エージェントの作業で再利用できる指示と補助ファイルを、オーナー・スコープ・明示的な権限とともにパッケージ化したものです。まず一般的な概念を知りたい場合は、コーディングエージェントのスキルとは何かで定義と広範なエコシステムを解説しています。この記事では、Sharkly内部のワークフローに焦点を当てます。

TL;DR

Sharklyのスキルは、エージェントの作業で再利用できる指示と補助ファイルをまとめたものです。レビュールール、納品チェックリスト、ライティング基準、チームのプロセスなどが該当します。ゼロから作成する、対応している公開ソースから公開済みスキルをインストールする、ローカルランタイムが検出したスキルをインポートする、あるいはSKILL.md、.skillファイル、zipパッケージをアップロードする、といった方法で作成できます。すべてのスキルは必ず1つのスコープ（組織、スペース、エージェントのいずれか）を持ち、作成時に選択され、その後変更されることはありません。エージェントは自身のスキル設定を通じて対象となるスキルを紐づけ、変更は以降の実行に反映され、編集権限は作成者、組織オーナー、管理者に留保されます。結果として、プロンプトのノウハウは1人の開発者のdotfilesに閉じ込められず、権限管理されたチーム共有のインフラになります。

プロンプトのノウハウに「居場所」ができると何が変わるか

優れたプロンプトとスキルの違いは、テキストそのものではありません。テキストを取り巻くすべてにあります。

スクラッチファイルに入ったプロンプトには、オーナーも、利用者も、ライフサイクルもありません。誰もその存在を知らず、Slackで見つけたコピーが最新版かどうかも分からず、プロセスが変わったときに更新する責任者もいません。スキルにはその3つすべてがあります。スキルは組織に属します。スコープによって、どのエージェントが使ってよいかが明確になります。編集権限によって、誰が変更してよいかが明確になります。プロセスが変わったときは、スキルを1回更新するだけで、紐づいているすべてのエージェントの以降の実行がその変更を取り込みます。

これはレバレッジ理論を縮図にしたものです。チームのレバレッジは、AIチャットをより多く開くことからは生まれません。役割、ルール、コンテキスト、ワークフローを共有することから生まれます。そしてエージェントは結果をタスクに返すため、スキルに導かれた実行の出力は、チームがレビューできる共有の記録に残ります。

ワークフローの話に入る前に、1つ境界線を引いておきます。スキルはタスクの要件ではありません。単発の要件はタスクの説明やコメントに置いてください。今回のタスクだけに必要なものはコンテキストです。来月の実行にも必要なら、それはインフラです。

スキルをゼロから作成する

スキルは3つの要素から始まります。名前、説明、指示です。この分け方は見た目以上に重要です。

説明は、エージェントがそのスキルをいつ使うべきかを示します。これはトリガー条件であり、自分の能力を走査しているエージェントに対して「これは目の前の作業に当てはまる」と伝える一文です。指示は、再現可能なプロセスと期待される出力を定義します。つまり手順、チェック項目、結果が取るべき形式です。有用なテストは、「エージェントがいつこのスキルに手を伸ばすべきかを1文で言えるか」です。言えないなら、それはおそらく2つのスキルか、あるいはスキルではない何かです。

内部的には、主要な指示はSKILL.mdファイルに入っています。先頭にYAMLのnameフィールドとdescriptionフィールドがあり、その後に指示が続きます。テンプレート、例、参照データを提供する補助ファイルを一緒に持たせることもできます。納品チェックリストのスキルならチェックリストのテンプレートを、マイグレーション記述のスキルなら注釈付きの例を2つ、といった具合です。焦点を絞ってください。大きく無関係なファイルの集合は、エージェントの判断を改善することなくコンテキストを増やすだけです。

すでにあるノウハウを取り込む

ほとんどのチームはゼロから始めません。プロンプトのノウハウはすでに存在していて、ただ散らばっているだけです。Sharklyには3つのインポート経路があります。

対応している公開ソースからインストールする。 Sharklyは公開済みスキルを取得し、選んだスコープにマネージドコピーを作成できます。このマネージドコピーが重要です。他人のファイルにリンクするのではなく、組織が管理するスナップショットを手に入れるのです。エージェントに紐づける前に、ソースとインポートされた内容を確認してください。外部の指示は、信頼できる組織のポリシーではなく、サードパーティのコードとして扱いましょう。

ローカルランタイムからインポートする。 これはまさにdotfiles問題のために用意された経路です。オンラインのローカルランタイムは、ローカルのスキルディレクトリで検出したスキルを報告できるため、開発者がひそかに蓄積してきたノウハウが組織に見えるようになります。インポートするとスキルは組織にコピーされ、元のローカルコピーは別物として残るので、その開発者の環境が壊れることはありません。ただし1点、正直にしておくべき注意があります。エージェントのランタイムから直接利用できるローカルスキルは、そもそもプロダクト側で紐づける必要がありません。インポートするのは、それが明示的なスコープを持つ管理された再利用可能なスキルになるべき場合だけで、単に存在するからという理由ではありません。

パッケージをアップロードする。 スキルがリポジトリにある場合や同僚から受け取った場合は、SKILL.md、.skillファイル、またはzipパッケージをアップロードします。Sharklyは受け取った内容を検証します。ファイルパスは相対パスでなければならず、スキルの外へ遡ることはできません。また、アップロードとインポートでは、隠しパスや機密性の高いパス、サポートされていないバイナリコンテンツ、安全でないアーカイブエントリ、重複したパス、サービスの上限を超えるパッケージは拒否されます。スキルはエージェントが従う指示です。依存関係と同じ厳しさで精査する価値があります。

スコープ：誰がスキルを使えるかを決める

すべてのスキルは組織に属し、作成時に選択されたただ1つのスコープを持ちます。スコープはどのエージェントがそれを紐づけられるかを決め、後から変更することはできません。

ドキュメントにある経験則が正解です。意図した利用者層に合う、最も狭いスコープを選びましょう。スコープは影響範囲でもあります。スペーススコープのスキルが古くなれば1チームのエージェントが混乱しますが、組織スコープのものが古くなれば全エージェントが混乱します。dotfilesのプロンプトの利用者は、永久に1人です。スキルの利用者層は、システムに記録される意図的な決定です。

スキルをエージェントに紐づける

スキルは、エージェントがそれを携えるまで何もしてくれません。Sharklyにおいてエージェントとは保存された作業構成のことであり、スキルを紐づけることはそこに能力を追加することです。

仕組みはシンプルです。エージェントのスキル設定を使って対象のスキルを追加・削除するか、エージェントの作成時にスキルを選択します。対象となるかどうかはスコープのルールに従います。変更は以降のエージェント実行に適用されるため、今日追加した紐づけは、実行中の作業に影響を与えることなく明日以降の仕事を形作ります。

判断が求められるのは、1つのエージェントがいくつのスキルを携えるべきかです。ドキュメントは率直です。重複する多くのスキルを紐づけるのは避けてください。矛盾したり冗長な指示は実行の予測可能性を下げます。鋭いスキル2つは、互いに言い争う6つに勝ります。エージェントのスキル一覧ががらくた置き場のように見えるなら、その実行結果もそうなります。

エージェント自身の指示とスキルの間にも役割分担があります。エージェントの指示は、その1つの役割における安定した振る舞いを担います。スコープ、人に判断を仰ぐタイミング、報告の形式などです。複数のエージェントが共有しうる再利用可能な手順はスキルに入れます。3体目のエージェントの指示に同じ段落を貼り付けていることに気づいたら、その段落はスキルになることを望んでいます。

紐づけは、プラットフォームの他の部分を複利的に効かせる鍵です。あなたのレビュースキルを携えたエージェントこそ、オートメーションがスケジュールやステータス変更で起動するエージェントです。つまり、一度取り込んだ標準が、誰も手動で起動しない定期的な実行の中に現れるようになります。スキルはスクリプトからも扱えます。CLIにはJSON出力付きのsharkly skill listとsharkly skill viewが用意されています。

ガバナンス：誰が編集し、誰が削除し、誰がレビューするか

共有された能力には共有された統制が必要であり、ここがスキルとプロンプトファイルの最も大きな分岐点です。

スキルを編集または削除できるのは、その作成者、または組織のオーナーや管理者です。スペーススコープのスキルには、そのスペースへの書き込みアクセスも必要です。エージェントスコープのスキルの作成やインポート、およびエージェントのスキル紐づけの変更には、対象エージェントを管理する権限が必要です。誰かが金曜の午後にこっそりレビュー標準を書き換えることはできません。

メンテナンスも同じ「1か所」の原則に従います。プロセスが変わったら、スキルの指示と補助ファイルを更新すれば、以降の実行が新しいバージョンを取り込みます。慎重になるべき操作は削除です。削除すると、そのスキルを使っているすべてのエージェントからスキルが取り除かれるため、まず現在の紐づけを確認してください。

セキュリティルールは短く、例外はありません。パスワード、アクセストークン、秘密鍵、その他のシークレットをスキルの指示や補助ファイルに保存しないでください。外部から、あるいはローカルからインポートしたスキルは必ず使用前に確認してください。コマンドと例は最小権限に保ってください。そして、エージェントのスペース所属やスキルの内容を変更した後は紐づけを再確認してください。紐づけの下で対象条件が変わりうるからです。

このすべてを通じて、人間とエージェントの契約は維持されます。エージェントはスキルを読み込み、プロセスに従い、結果をタスクに返します。どのスキルにチームとしての権威を持たせるかを決めるのは人間です。スキルは一貫性の下限を引き上げますが、レビューする人を不要にするものではありません。

スキルを作るべきでないケース

スキルはインフラであり、インフラには維持コストがかかります。正直な判断のペアはこうです。単発の要件はタスクの説明やコメントに置き、同じ能力が今後の実行をまたいで利用可能であるべきときにスキルを作成する。

「スキルを作らない」が正解となるケースは他にもあります。手順がローカルランタイムのスキルディレクトリにあり、そのコンピューターの実行だけがそれを必要とするなら、ローカルのままにしておきましょう。2つの候補スキルが同じエージェント上で大きく重複するなら、どちらかを紐づける前に統合するか、鋭くしてください。そして、説明の一文が書けないなら、そのプロセスはまだ取り込むのに十分安定していません。

まずは1つの手順から始める

チームが繰り返し行い、そして誰か1人にこっそり依存している手順を1つ選んでください。それを1つの狭いスキルとして書き出します。名前、いつ適用されるかを示す説明、プロセスと期待される出力を定義する指示です。スコープは自分のスペースに設定します。1つのエージェントに紐づけ、そのエージェントに実際のタスクを割り当て、返ってくるものを読んでみてください。

ループはこれで全部です。1人の開発者の頭の中にあったノウハウに、名前、スコープ、オーナー、そして更新すべき1か所ができました。プラットフォームが初めてなら、Sharklyの概要でスキルがタスク、エージェント、コンピューターとどう並ぶかを説明しており、Sharklyの始め方では最初の接続を端から端まで案内しています。スキルのドキュメントでは、上記のすべてのルールを詳細に扱っています。

よくある質問

スキルとエージェントの指示の違いは何ですか？

エージェントの指示は、1つの役割における安定した振る舞いを定義します。スコープ、入力を求めるタイミング、報告の方法などです。スキルは複数のエージェントが共有しうる再利用可能な手順であり、独自の補助ファイルと権限を伴ってパッケージ化されています。ある段落をエージェント間でコピーしているなら、それはスキルに入れるべきものです。

スキルのスコープは作成後に変更できますか？

できません。スキルのスコープは作成時に固定されます。利用者層を変える必要がある場合は、適切なスコープで新しいスキルを作成し、それを必要とするエージェントを紐づけ直してください。だからこそドキュメントは、最初から意図した利用者層に合う最も狭いスコープを選ぶことを推奨しています。

インポートしたスキルはソースと同期し続けますか？

しません。対応している公開ソースからインストールすると、選んだスコープにマネージドコピーが作成され、ローカルランタイムからのインポートではスキルが組織にコピーされ、元のローカルコピーは別物として残ります。以降は組織がそのコピーを管理します。

新しいスキルを紐づけると、エージェントが現在実行中のタスクに影響しますか？

しません。エージェントのスキル紐づけの変更は、以降のエージェント実行に適用されます。すでに進行中の作業は開始時の構成のまま完了し、次の実行が更新されたスキルセットを取り込みます。

公開ソースからスキルをインストールするのは安全ですか？

確認すれば安全にできます。外部から、あるいはローカルからインポートしたすべてのスキルを、サードパーティのコードや構成として扱ってください。紐づける前に指示と補助ファイルを読み、コマンドは最小権限に保ち、シークレットをスキルに入れることは決してしないでください。Sharklyのアップロード検証は安全でないパスやアーカイブエントリを拒否しますが、その指示がチームの信頼に値するかどうかの判断は人間に委ねられています。