notis-skill-creator

Notis スキル作成ツール

このスキルでは、新しいスキルを一から作成する手順や、既存のスキルを反復して改良する手順を説明します。スキルとは、アシスタントの機能を拡張する、手順、参考資料、任意のスクリプトをまとめた独立した単位です。

このスキルを使う場面

• ユーザーが新しいスキルの作成を希望している場合（例：「X 用のスキルを作成してください」「Y を実行するスキルが必要です」）
• ユーザーが既存のスキルを改良またはパッケージ化している場合
• スキルの構成、検証、配布方法についてユーザーから質問された場合

スキル開発のワークフロー

ステップ 1：スキルを定義する

ファイルを作成する前に、次の点を明確にします。

• 名前 — ケバブケース（例：my-skill、api-helper）
• 説明 — スキルの機能と使用する場面を、1～2 文で説明します
• 範囲 — 手順のみか、手順にスクリプト／参考資料／アセットを加えるか

ステップ 2：内容を計画する

• SKILL.md — 必須です。YAML フロントマター（name、description）と主要な手順を記述します。
• scripts/ — 任意です。アシスタントが実行できるコード（Python、Bash など）を配置します。
• references/ — 任意です。必要に応じて読み込むドキュメントや参考ファイルを配置します。
• assets/ — 任意です。出力に使用するテンプレート、画像、その他のファイルを配置します。
• 状態 — スキルが実行間で何らかの情報（履歴、進捗、承認、キュー、キャッシュ、結果など）を保持する場合は必須です。スキルは Notis バックエンドで実行されることがあり、その場合ローカルファイルは保持されないため、あらかじめ Notis データベースを計画します。
  • 適切なデータベース（LOCAL_NOTIS_DATABASE_LIST_DATABASES）を再利用するか、LOCAL_NOTIS_DATABASE_UPSERT_DATABASE で作成し、スキルが属する Space にそのメインビューを関連付けます（notis-query のデータベース検出リファレンスを参照）。キーとなるプロパティ名と、各実行で読み書きするフィールドを指定します。
  • データベースのスラッグに対して LOCAL_NOTIS_DATABASE_GET_DATABASE が返す row_write_tool を使って行を書き込むよう、スキルに指示します。生成されたツール名をハードコードしてはいけません。
  • ユーザーが保持するドキュメントは、ローカルファイルではなく Notis のドキュメントまたはレポートに保存します。
  • スクリプトが書き込めるのは、一時ディレクトリ内の作業用ファイルのみです。スキルフォルダーは同期時にアップロードされるため、スキル自身のフォルダーには書き込みません。
• モデル処理 — 生成、分類、調査は、スキルを実行するエージェントまたはそのサブエージェントが担当します。ユーザーが明示的に求めた場合に限り、モデルプロバイダー API を呼び出すスクリプトを同梱します。

インテリジェンスと呼び出し時のオーバーライド

• 委任する各ステップには、その作業に応じて low、medium、high を指定します。スキルでレベルを指定していない場合は high を使用します。手順、スクリプト、テンプレート、例には、ベンダーのモデル名、バージョンの固定指定、ファミリーの別名、価格表、独立した作業量の対応表を含めないでください。
• 共有の contract と現在のハーネスの対応付けの両方について、LOCAL_NOTIS_GET_INTELLIGENCE_POLICY を直接、または認証済みの Notis CLI 経由で使用します。リポジトリにあるスキルとアカウントにインストールされたスキルの両方で、同じランタイム契約を使用します。インテリジェンスに関する指針として、チェックアウト相対の docs/ リンクを必須にしてはいけません。モデルと作業量をまとめて解決し、レベルから作業量を推測しないでください。
• この呼び出しにおけるユーザーの明示的な選択は、特定のモデルや作業量の指定も含め、スキルのデフォルトより優先されます。求められない限り、保存済みのアカウントのデフォルトは変更しません。
• 固定モデルのハーネスは現在の設定を引き継ぎ、要求されたレベルが適用されなかったことを報告します。特定の選択を必須とする自動ランチャーは、現在のポリシーを取得できない場合、副作用が発生する処理を始める前に停止します。フォールバックを推測してはいけません。
• メディアは、ハードコードされた画像／音声／動画エンジン名ではなく、検出された機能を通じてリクエストします。実際に使用されたモデルのレシートは来歴情報として保持します。スキーマが結果を生成した実際の識別子を要求する場合、レベルを保存してはいけません。
• ポリシーの変更、明示的なオーバーライド、未対応のハーネス、取得不可の状況で検証します。毎週の対応付けの変更に、スキルの編集が必要になってはいけません。

ステップ 3：スキルの初期化

ここで、実際にスキルを作成します。

開発中のスキルがすでに存在し、反復またはパッケージ化が必要な場合に限り、このステップをスキップしてください。その場合は次のステップに進みます。

新しいスキルを一から作成する場合は、ディレクトリ構造を手動で作成します。

mkdir -p my-skill/scripts my-skill/references my-skill/assets

次に、適切な YAML フロントマターを含む my-skill/SKILL.md を作成します。

---
name: my-skill
description: "Description of what this skill does and when to use it"
---

# My Skill

## Instructions

(Add your skill instructions here)

サポートファイルがあれば、適切なディレクトリに作成します。

• 実行可能コード（Python、Bash など）には scripts/
• 必要に応じて読み込むドキュメントには references/
• 出力で使用するファイル（テンプレート、画像など）には assets/

ステップ 4：作成と反復

• 指示を明確で実行可能なものにします。スキルを使用するタイミング、必要な入力、期待される出力を含めてください。
• スクリプトやアセットはパス（例：scripts/helper.py、references/glossary.md）で参照します。
• 実際のシナリオでアシスタントにスキルを実行させて、スキルをテストします。

ステップ 5：該当するスキルを保存または更新する

ネイティブのスキルツールを検出し、まず現在インストールされているスキルの一覧を読み取ります。 既存のスキルは、（LOCAL_NOTIS_LIST_SKILLS に記載された）正確な ID、所有者、Space リンクに基づいて特定してください。名前が最初に一致したものを選んではいけません。編集ではその ID を更新し、新規作成は本当に新しいスキルの場合に限ります。

• 単一ファイルの作成：検出した LOCAL_NOTIS_CREATE_SKILL を name、description、skill_md とともに使用します。単一ファイルの編集：LOCAL_NOTIS_UPDATE_SKILL を skill_id と変更したフィールドのみで使用します。無関係な agent_targets と status は保持してください。
• 複数ファイルの作成または更新：SKILL.md、scripts、references、assets を含む完全なフォルダーをパッケージ化します。検出した CREATE または UPDATE ツールで、CLI の --file bundle_url=./skill.zip アップロードパスを使用します（UPDATE には skill_id を含めます）。架空の公開 URL 通知を待ったり、既存のリソースを削除したりしないでください。
• 厳選されたスキルは正規のソースで管理され、別途公開されます。通常のユーザースキルの更新で、厳選されたコンテンツを置き換えることはできません。Space にリンクされた Skill は共有リソースです。編集すると、それをリンクしているすべての Space に反映され、Space ソースのデプロイでは、変更された Skill フォルダーがリリースとともにコミットされます。
• フロントマター、リソースパス、意図した変更を検証し、変更をドライランします。同じ ID、コンテンツ、保持された割り当てを読み戻して確認します。バンドルの場合は、リソース一式を検証します。更新によってインストール済みレコード数が増加してはなりません。
• ネイティブのスキルリンクを提供します。ユーザーから求められた場合に限り、zip をエクスポートして提供します。

SKILL.md のフロントマター

すべてのスキルには、少なくとも以下を含む SKILL.md が必要です。

---
name: skill-name
description: "Clear description of what the skill does and when to use it."
---

• name — kebab-case 形式の識別子です。パッケージ化と表示に使用されます。
• description — スキル一覧に表示され、振り分けに使用されます。具体的に記述してください。

ベストプラクティス

1. 目的を明確にする — 各スキルは、ひとつのことを適切に実行できるようにします。
2. 適切な説明を記述する — 説明はスキルを呼び出すタイミングの判断に使われます。検索しやすく、正確に記述してください。
3. 一貫した構造にする — ユーザーとツールがファイルの場所を把握できるよう、scripts/、references/、assets/ を一貫して使用します。
4. パッケージ化する前に検証する — フロントマター、命名規則、参照されるすべてのファイルの存在を確認します。
5. 状態は Notis に保存する — 後続の実行で必要になる情報は、Notis のデータベース行またはドキュメントに保存してください。スキルフォルダーやマシン上のファイルには保存しないでください。

Notis 固有の注意事項

• 製品ソースは server/skills/ に、開発ワークフローは .agents/skills/ にあります。生成されたミラーやベンダーキャッシュを正規のソースとして編集しないでください。
• CLI が所有する同期機能は、アカウントバンドルを実体化し、エージェントごとのリンクを管理します。Desktop の自動同期は任意です。行を保存しただけでは、ローカルで利用可能になったことの証明にはなりません。ターゲットの割り当てを保持し、対象アカウントでサポートされている同期ワークフローを使用してください。利用可能だと主張する前に、コンテンツの実体化と検出を確認します。
• リポジトリのメンテナーは docs/notis-skills-lifecycle.md と docs/skills-sync.md に従ってください。