Skip to main content
技能は、Agent に深く、タスク専用の知識を与える Markdown ファイルです。短編小説の創作用に 1 つ、拆書ノート用に 1 つ、脚本のフォーマット用に 1 つ——Agent は今のタスクに関連する技能だけを読み込みます。

技能の仕組み

技能は段階的な読み込みでコンテキストを軽く保ちます。プロジェクトを開くと、Agent はすべての技能の名前と説明だけを見ます——それぞれ数十字です。起動時に読み込まれるのはこれだけです。 あなたのリクエストがある技能の説明と一致すると、Agent はその技能を有効にして完全な指示を読み込みます。短編小説の技能は、あなたがクエリレターを書いている間は休眠しています。ホラー小説の技能は、あなたがスリラーの大綱を作っている間はコンテキストを消費しません。

技能の構造と保存場所

各技能は SKILL.md ファイルを含むディレクトリで、ディレクトリ名がそのまま技能名になります。技能は 3 つの任意のサブディレクトリに支援ファイルを含めることもできます。
支援ファイルは、指示が参照したときにのみ読み込まれ、起動時にはコンテキストを消費しません。テンプレートは、Agent がそれを必要とするステップに到達するまで休眠しています。参考ドキュメントは、Agent が調べる必要があるときにのみ読み取られます。 グローバル技能 はシステムレベルの技能ディレクトリに保存され、すべてのプロジェクトで使えます。プロジェクトをまたいで一貫して使う能力に適しています。例えば、開幕フックを生成する技能や、標準的な作品レビューの流れを Agent に案内させる技能です。 プロジェクト技能 はプロジェクトルートの .soloent/skills/ に置きます。特定のプロジェクトやジャンルに結びついた能力に適しています——この恋愛シリーズ特有のルールで組み立てた技能や、今の作品の尺度と語りのスタイルに合わせて調整した技能です。
グローバル技能とプロジェクト技能が同名のとき、プロジェクト技能が優先されます。

技能のオン/オフ

各技能には、ファイルを削除せずに有効/無効を切り替えるスイッチがあります。現在のタスクにその技能が不要なときは無効にすると、コンテキストから外れ、意図しない有効化を防げます。

技能を作成する

SKILL.md ファイルは 2 つの部分からなります:frontmatter(メタデータ)と指示本文です。
2 つの必須 frontmatter フィールド:
  • name はディレクトリ名と 完全に一致 する必要があります
  • description は、この技能を いつトリガーするか を説明します。何ができるかではありません(1,024 文字以内)
エディタで開いた SKILL.md ファイル。name と description フィールドを表示し、右側の Skills パネルが english-short-story 技能を Workspace Skills の下に一覧表示
1

Skills メニューを開く

Agent パネルの左から 4 番目のアイコンをクリックし、Skills マネージャーに切り替えます。
2

技能を新規作成

「New skill…」をクリックして名前(例:short-story)を入力し、「+」をクリックします。Agent はテンプレートの SKILL.md ファイルを含む技能ディレクトリを作成します。
3

技能の指示を書く

SKILL.md ファイルを編集します:
  • description を更新し、この技能がトリガーされるタイミングを指定する
  • 本文に指示、チェックリスト、ワークフローのステップを追加する
  • 任意で templates/docs/ サブディレクトリに支援ファイルを追加する
以下は公式提供の english-short-story の完全な技能ファイルです——これは 領域専門家型 の技能で、完全な 6 ステップのワークフロー、チェックリスト、停止条件を含み、そのままコピーして使えます。

よくある 3 つの技能タイプ

タイプ 1:チェックリスト型

固定の節目で複数の基準を一度に検証し、抜けを防ぐのに適しています。例えば、各章を書き終えた後の提出前チェック:

タイプ 2:ワークフロー型

明確なステップ順序があり、実行前に確認が必要な操作に適しています。

タイプ 3:領域専門家型

Agent に、勘に頼らず専門家の経験に基づいて働いてほしい場面に適しています。例えば、執筆が行き詰まったときの診断技能:

完全な事例:作品まとめ

これは領域専門家型の技能です。 コンテンツ取得の経路(スクリプトが必要に応じて章を抽出)、専門的な定義(docs/ に章の識別パターンを保存)、固定の出力フォーマット(templates/ のノートテンプレート)を定義しており——この 3 要素こそ領域専門家型技能の典型的な構造です。 この技能は、ローカルの書籍ファイルから構造化されたノート——章の要約、キーとなる観点、金句——を抽出し、整形された Markdown として保存します。

ディレクトリ構造

なぜスクリプトが必要か

書籍は長いものです。章構造を抽出するために本を丸ごとコンテキストに読み込むのは、無駄で遅くなります。前処理スクリプトがこれを解決します:
  • info コマンド — 先頭 50 行を読み、書名・エンコーディング・総行数を識別する
  • chapters コマンド — 全文を読まずに章タイトルをスキャンし、行番号を返す
  • extract コマンド — ある章の内容だけを読み、Agent が章ごとに処理できるようにする
Agent はワークフローの各段階でスクリプトを呼び出します。コンテキストに入るのはスクリプトの出力だけで、書籍そのものは入りません。

なぜ docs ファイルが必要か

中国語と英語の書籍では、章タイトルの形式が大きく異なります。すべての識別パターンを SKILL.md に埋め込むより、docs/chapter-patterns.md に保存する方が良いのです。Agent は章の境界を識別する必要があるときにこのファイルを読み、それ以外のときは無視します。 参考資料を docs/ に置くと 2 つの利点があります:SKILL.md をワークフローのロジックに集中させられること、そして主指示を変更せずにパターンを更新できることです。

なぜテンプレートが必要か

出力フォーマットは固定です:どの読書ノートも同じ構造に従います——書籍概要、章の要約(キー観点と金句を含む)、全書のハイライト、個人の考察。毎回のプロンプトでフォーマットを説明し直すより、templates/note-template.md に保存する方が良いのです。 第 5 ステップ(最終まとめ)を実行するとき、Agent はテンプレートを読み込んでプレースホルダーを埋めます。フォーマットは毎回一貫し、1 か所で保守するだけで済みます。

SKILL.md が支援ファイルをどう参照するか

SKILL.md の指示は、各支援ファイルを明示的に指し示します:

効果的な技能を書く

description は「いつ使うか」を書き、「何をするか」を書かない

この 2 つは似て聞こえますが、トリガーの精度に大きく影響します。
説明は 常時コンテキストに常駐 し、有効な技能はすべて継続的に token 配分を消費します。短く、正確に、トリガーの場面を直接書きましょう:

完全なステップ・入力・出力・停止条件を備える

プロセスの冒頭だけを書き、明確な完了の合図がない技能指示だと、Agent はいつ止まるかを自分で決めてしまいます——たいていあなたの望む位置ではありません。各ステップには次を備えるべきです:
  • 入力:このステップに必要なコンテキストやファイル
  • 出力:このステップが生み出すもの
  • 停止条件:どんなときに確認を待ち、どんなときに続行するか

本文にはナビゲーションと核心的な制約だけを置き、大きな資料は支援ファイルに分ける

SKILL.md 本文は 5,000 字以内に抑えます。文体参照、識別パターン、人物設定など大量の資料が必要なら、docs/ サブディレクトリに置き、指示ではファイル名で参照します——Agent は必要なときだけ読み込み、不要なときはコンテキストを占めません。

呼び出し頻度で自動トリガーの有無を決める

はまりやすい落とし穴

トラブルシューティング

最も可能性の高い原因:説明が十分に具体的でない、または技能がオフになっている。
  • 技能が Skills パネルで有効になっているか確認する
  • description を書き直し、実際に使う短語やタスクの種類を入れる——「執筆を手伝う」ではめったに正しくトリガーされません。具体的なワークフロー、出力の種類、例となるトリガー文を挙げる
  • 技能ディレクトリに有効な SKILL.md があり、namedescription の 2 つの frontmatter フィールドを含むか確認する
  • frontmatter の name がディレクトリ名と 完全に一致 するか確認する
説明が広すぎます——トリガーしたくないリクエストに一致しています。
  • description を絞り、この技能が扱う具体的なタスクだけを説明する
  • ある技能が不要なときは、Skills パネルでオフにする
  • 複数の技能の説明に重なりがあるなら、それぞれの説明をより具体的に書き、各自の適用範囲を明確にする
以下のよくある問題を確認してください:
  • 指示がコンテキスト上限を超えている可能性——SKILL.md を 5,000 字以内に抑え、参考資料を docs/ サブディレクトリに移す
  • あるグローバルまたはプロジェクトのルールが技能の一部の挙動を上書きしている可能性——現在有効なルールが技能指示と衝突していないか確認する
  • 技能がチェックリストを使う場合、各重要な節目に明確な「確認を待つ」ゲートがあるか確認する。なければ Agent は自動で進みます
  • 指示が参照する支援ファイルは、指定パスに存在する必要があります——ファイルが欠けると、そのステップは静かにスキップされます
Agent は、指示が明示的に参照したときにのみ支援ファイルを読み込みます。
  • 指示中のファイルパスが実際の場所と一致しているか確認する(例:chapter-outline.md ではなく templates/chapter-outline.md
  • ファイルが技能ディレクトリ下の正しいサブディレクトリ(templates/docs/scripts/)にあるか確認する
  • SKILL.md の中でファイル名で参照されていなければ、Agent がそれを読み込む理由はありません
プロジェクト技能は常に同名のグローバル技能より優先されます。
  • これは想定どおりの動作です——プロジェクト技能が有効なら、同名のグローバル技能は完全に無視されます
  • グローバル技能を効かせたいなら、プロジェクト技能を改名または削除する
  • 両方を共存させたいなら、別々の名前を付け、それぞれの説明を更新する

さらに高度なテクニック

Workflows(ワークフロー)

ワークフローファイルで、繰り返しの多段階プロセスを自動化する

Rules(ルール)

あなたの執筆の好みをルールに書き、Agent が常にあなたのスタイルで書くようにする

Rule・Workflow・Skill の選び方

3 つの AI 指示の方式はそれぞれ役割が違う——違いと適した場面を知る