Skip to Content
IoT アプリ開発アプリスキル

アプリスキル

アプリスキルは、アプリのAIエージェントが必要に応じて読み込む指示のまとまりです。毎ターンsystem_promptに持たせておく必要がなくなります。

エージェントには、最初は各スキルの名前と説明だけが見えています。タスクでスキルが必要になると、エージェントがその指示を読み込みます。スキルは読み込まれるまで何のコストもかからないため、長い手順や参照資料をエージェントに与えても、すべての会話が重くなることはありません。

アプリスキルは、アプリ自身のエージェント向けの指示です。Claude Codeで開発がコーディングエージェント向けにインストールするスキルとは別のものです。

スキルとシステムプロンプトの使い分け

system_promptは毎ターン読まれます。スキルは、エージェントが読み込むと判断したときにだけ読まれます。

system_promptに入れるものスキルに入れるもの
エージェントの役割一部のタスクにだけ必要な知識
常に適用されるルール診断や試運転チェックなどの長い手順
安全に関わるルール:エージェントが決してしてはならないこと、先に確認が必要なこと故障コードや機械のパラメータなどのドメイン知識
短い事実

スキルを一度も読み込まないエージェントでも、安全に関わるルールはすべて守る必要があります。そのため、それらは常にsystem_promptに残します。

スキルフォルダの形式

スキルはアプリのリポジトリ内、.ironflock/の他のファイルと同じ場所に置きます。

.ironflock/ ├── ai-template.yml └── skills/ └── machine-diagnosis/ ├── SKILL.md └── references/ └── codes-press.md
  • .ironflock/skills/<name>/SKILL.mdは必須です。YAMLフロントマターで始まり、その後にMarkdownで指示を書きます。
  • .ironflock/skills/<name>/references/<file>.mdは任意です。一部のタスクにだけ必要な資料は、参照ファイルに置きます。エージェントは各ファイルが必要になったときにだけ読み込むため、各参照ファイルは単独で意味が通るように書いてください。どのファイルをいつ読むかはSKILL.mdに書きます。
  • スキルフォルダには、それ以外のものを置けません。スクリプト、画像、シンボリックリンクは不可です。すべてのファイルはUTF-8のテキストです。

フロントマターには2つのフィールドがあります。

--- name: machine-diagnosis description: >- How to find out why a machine is TOO_HOT or shows NO_READING. Load it before you answer such a question. ---
フィールド説明
nameフォルダ名と同じである必要があります。
descriptionプレーンテキスト。エージェントがスキルを読み込むまで、見えるのはこれだけです。

エージェントにスキルを登録する

エージェントが登録するまで、スキルは何も行いません。.ironflock/ai-template.ymlで、エージェントにskillsキーを追加し、各スキルをフォルダ名で指定します。

machines: main: true skills: [machine-diagnosis]

指定するのはフォルダ名だけです。エントリをapp/やproject/で始めてはいけません。

エージェントには、このスキルがapp/<name>という形で提供されます。ここではapp/machine-diagnosisです。system_promptやtool_descriptionでスキルに触れるときは、この形を使います。

すべてのスキルフォルダは、少なくとも1つのエージェントが登録している必要があります。また、各エージェントが同じスキルを登録できるのは1回だけです。

プラットフォームスキル

platform/<name>の形のエントリは、プラットフォームがアプリに提供するスキル用に予約されています。プラットフォームスキルはまだ利用できないため、現時点ではこの形のエントリがあるとリリースビルドが失敗します。

制限

項目制限
スキル名小文字の英字と数字を、1つのハイフンでつなぐ。最大64文字
説明最大500文字
指示(SKILL.md)最大20,000文字
参照ファイル1つ最大40,000文字
スキル1つあたりの参照ファイル数最大20
アプリあたりのスキル数最大20
アプリのすべてのスキルファイルの合計最大2 MiB
1つのエージェントが登録するスキル数最大20

リリースビルドのチェック内容

リリースを作成すると、ビルドはai-template.ymlとあわせてスキルをチェックします。チェックに失敗するとリリースはビルドされず、最初に見つかった問題が表示されます。問題を修正して、もう一度リリースを作成してください。

次の場合にビルドは失敗します。

  • エージェントが、フォルダのないスキルを登録している。
  • どのエージェントにも登録されていないスキルフォルダがある。
  • アプリにスキルフォルダはあるが、ai-template.ymlがない。
  • skillsのエントリがapp/またはproject/で始まっている。
  • エントリがplatform/で始まっている(プラットフォームスキルはまだ利用できません)。
  • スキルフォルダ内のファイルが、UTF-8のテキストでない、シンボリックリンクである、またはSKILL.mdでもreferences/<file>.mdでもない。
  • 上の表の制限を超えている。
  • エージェントにload_skillという名前のツールがある。この名前は、すべてのアプリでスキルの読み込み用に予約されています。

例

このスキルは、機械が故障を報告している理由の調べ方をエージェントに伝えます。ここでは短縮してあります。新しいアプリには、読んだり変更したり削除したりできる3つの完全なスキルが.ironflock/skills/に最初から入っています。

.ironflock/skills/machine-diagnosis/SKILL.md:

--- name: machine-diagnosis description: >- How to find out why a machine is TOO_HOT or shows NO_READING, or what is wrong with a machine a user asks about: which rows to read, when to read the machine now with current_reading, and what to tell the user. Load it before you answer such a question. --- # Diagnosing a machine A user asked why a machine is too hot, why it has no reading, or what is wrong with it. Find the cause in the app's tables and at the machine, then answer with the evidence. You only read: you cannot change the limit or a machine. ## 1. Find the device and its state Run with `execute_sql`: ```sql SELECT DISTINCT ON (device_id) device_id, device_name, state, tsp FROM devices ORDER BY device_id, tsp DESC ``` `state` is `OK`, `TOO_HOT` or `NO_READING`. When the user named no machine, take the devices whose state is not `OK`. ## 2. Check the machine now Call `current_reading` for the device and compare its values with the newest rows of `measurements`. When the call fails, the device is offline: say since when. Do not tell anyone that a machine running too hot is safe to keep running.

このスキルを登録するエージェントは、.ironflock/ai-template.ymlで次のようになります。

machines: main: true tool_description: | Delegate to this agent when the user asks about the state of a machine. system_prompt: | You answer questions about the machines this app watches. You only read. Never tell anyone that a machine running too hot is safe to keep running. When a user asks why a machine is too hot or has no reading, load the skill app/machine-diagnosis and follow it. data_access: true skills: [machine-diagnosis] tools: current_reading: description: Reads the machine at one device now. topic: current_reading

system_promptの「When a user asks」で始まる文は、このスキルをapp/machine-diagnosisとして参照しています。安全に関するルールはsystem_promptに残します。スキルを読み込まないエージェントでも、そのルールは守る必要があるからです。

リリースなしでスキルを試す

エージェントやスキルを試すのに、リリースは必要ありません。クラウドIDEには、自分の作業コピーで動く開発チャットがあります。

クラウドIDEのサイドパネルのAI エージェントセクションには、2つの操作があります。

  • 開発チャットを開くは、作業コピーを反映して、それを使うチャットを開きます。
  • AI エージェントを更新は、ai-template.ymlとスキルへのその後の編集を反映します。

開発チャットには次の特徴があります。

  • アプリの作業コピーを、プロジェクトの開発用データバックエンドで実行します。
  • プロジェクトの通常のアシスタントであり、このアプリのエージェント、ツール、スキルは作業コピーのものが使われます。
  • 作業コピーが使えるのは、このチャットだけです。他のユーザーにも、他のチャットにも、作業コピーは提供されません。

実行中の開発チャットは、次のメッセージから編集内容を使います。そのため、スキルを変更してAI エージェントを更新をクリックし、同じチャットでもう一度質問できます。

テンプレートやスキルが無効な場合は、リリースビルドと同じメッセージが表示され、前のバージョンがそのまま使われます。

開発チャットには、選択したデバイスのプロジェクトに、アプリの開発用データバックエンドが必要です。

ユーザーがスキルを確認する場所

Studioでは、アプリのAI プラグインタブに、各エージェントとそのスキルが一覧表示され、スキルごとに名前と説明が示されます。スキルの本文は、そこには表示されません。

古いインストール

まだ更新されていないアプライアンスでも、アプリはインストールされて動作します。そのエージェントはスキルなしで動き、タスクにスキルが必要なときはその旨をユーザーに伝えます。アプライアンスを更新すると、次のアプリの同期でスキルが届きます。

よいスキルの書き方

  • 説明には、スキルの用途と読み込むタイミングを書く。エージェントがスキルを読み込むまで、見えるのは説明だけです。状態の値、症状、タスクなど、ユーザーやデータで使われる言葉を使い、最後に読み込むタイミングを書きます。たとえば「機械がTOO_HOTになる理由を答える前に読み込むこと。」のようにします。「機械に関する情報」のような説明は、適切なタイミングでは読み込まれません。
  • 指示は単独で完結させる。エージェントは、ユーザーを待たせたまま、タスクの途中で指示を読みます。system_promptに頼らず、アプリのテーブル、列、ツールを正確な名前で書いてください。
  • 従う順に、命令形の手順で書く。いつ止まるか、ユーザーに何を伝えるかも書きます。
  • してはいけないことを書く。

次のステップ

Last updated on