open-knowledge-write-skill

OpenKnowledge スキルの作成

ユーザーが エージェントスキル（AI エージェントに繰り返し発生するタスクの実行方法を教える SKILL.md ファイルと、任意の references/ および scripts/）を作成できるよう支援します。OpenKnowledge では、スキルは第一級のバージョン管理されたインストール可能なアーティファクトです。write／edit スキル動詞で作成し、ユーザーのエディターに install します。

スキルの価値は、適切なタイミングで認識されることと、忠実に実行されることで決まります。作成の要点は主に 2 つです。確実に起動する description と、エージェントが実際に指示どおり動けるほど短く具体的な本文です。以下のステージを順番に進めますが、ユーザーがすでに到達している段階から始めてもかまいません。

ステージ 1 — 意図を把握し、スキルを分類する

ゲート — すでに存在するか？作成する前に確認してください。 まず skills({}) で管理対象スキルを一覧表示し、次に一致しそうなものを skills({ name }) で読み込みます。これらは、OpenKnowledge がすでに管理している Project／Global スキルです。また、タスクがこのプロジェクト以外でも再利用できそうな場合は、草案を作成する前に skills({ query: "<2-4 trigger words>" }) で公開マーケットプレイスも検索してください。各マーケットプレイスの行には name、source、description が含まれます。有力な候補の説明を確認してから、選んだ候補を import({ source, skill: name, add: [...] }) でインポートし、再利用が適切な場合に限り調整してください。OK MCP の skills({ query }) を利用できない場合に限り、Vercel の find-skills スキル、npx skills find <query>、または手動での skills.sh 検索を使います。ユーザーがすでに skills.sh のページを開いている場合は、source としてスキルページの完全な URL を渡します。例：import({ source: "https://www.skills.sh/<owner>/<repo>/<skill>", add: [...] }) — 中間のセグメントは REPO であり、文字どおりの skills ではありません。デフォルトのインストール方法として、このフローで npx skills add を実行しないでください。OpenKnowledge 経由でインポート（import({ source, skill, add })）し、来歴、バージョン管理、管理された一括展開が備わる実際のフォルダーとしてスキルを配置します。add は配置先を指定し、その後の install で保存先を変更します。ユーザーの依頼から具体的なトリガーフレーズを 2〜4 個取り出し、ドメイン名またはツール名と組み合わせてから、有力候補の説明を開いて読み、判断してください。既存スキルまたは公開スキルが要件の大半を満たす場合は、そこで止めて再利用を提案します。トリガーが重複する類似スキルを作ると、誤作動を招き、両方の有用性を損ないます。公開スキルが近いものの完全には一致しない場合は、ユーザーと相談し、OpenKnowledge にインポートして調整するか、Skills CLI で OK の外部にインストールするか、そのスキルへの引き継ぎを description で明示する、より限定的な補助スキルを作成するかを決めてください。新しいスキルを作るのは、実際に別物である場合に限ります。草案の作成や記述に着手する前に、重複状況と、インストール済みスキルおよびマーケットプレイスの検索結果をユーザーに伝えてください。これは開示のゲートです。何を確認し、何が一致し、再利用／インポート／調整／新規作成のどれが適切かを、ユーザーに伝えます。スキルの記述後に重複が判明することがないようにしてください。skills({ query })／skills.sh にアクセスできない場合は、その旨を明確に伝え、インストール済みスキルの確認を続けてください。

推測できないことだけを質問してください。

• どのような繰り返しタスクをこのスキルで扱いますか？具体例を 1 つ確認してください。
• 適用する厳密さを決めるため、スキルの種類を確認します。
  • リファレンス／テクニック（ほとんどのスキル）—「X のやり方」。説明文と例を記載します。
  • 規律 — プレッシャーがかかるとエージェントが省略しがちな行動を徹底します（例：「必ず最初に失敗するテストを書く」）。これらにはステージ 4〜6 で RED ベースラインとプレッシャーテストが必要です。リファレンススキルには不要です。
• 自由度（タスクの壊れやすさに応じて本文の精度を調整します）。 高（自由な説明 — 判断が必要なタスク）、中（パラメーター化された手順）、低（逸脱すると結果が損なわれる、固定の scripts/ コマンド）。判断が必要なタスクを過度に細かく指定したり、壊れやすいタスクの指定を不十分にしたりしないでください。

Stage 2 — スコープを最初に決める（暗黙に推測しない）

スコープによって、スキルを配置する場所と install の展開先が決まります。 これはユーザーが決定することであり、影響範囲も異なるため、明示してください。

スコープ	配置場所	install の展開先
グローバル	ホームディレクトリのスキル用ルートにある実フォルダー（例：~/.claude/skills/<name>/）	すべてのプロジェクトで、使用するエディター
プロジェクト	このリポジトリのスキル用ルートにある実フォルダー（例：.claude/skills/<name>/ または Git で共有される .agents/skills/ ハブ）	このプロジェクトのエディター。チームメンバーは git pull で取得

デフォルトの判断基準：適切なプロジェクト内で、そのタスクがプロジェクト固有なら → プロジェクト； 「すべての作業で使う／グローバルに」なら → グローバル；それ以外は質問を1つしてください。作成前に、 選択したスコープとその影響を伝えてください。

スキルリポジトリまたはプラグインを開発していますか？その場合、どちらのスコープにも該当しません。 作業中のリポジトリ自体がスキルの 配布元、つまりプラグイン（例：.claude-plugin/ マニフェストやマーケットプレイスのリスト）または他の人がインポートできるよう skills/<name>/ にスキルを格納するカタログリポジトリである場合、作成するスキルはそのリポジトリに インストールするもの ではなく、そのリポジトリの 成果物 です。リポジトリ独自のレイアウトに沿って、既存の関連スキルの隣に、リポジトリで使われている形式で作成してください。ここでは .claude/skills/ や .agents/skills/ に配置せず、install もしないでください。利用者はプラグインをインストールするか、リポジトリからインポートして取得します。また、プラグイン自身のリポジトリは、自身から何も読み込みません。install は、現在の プロジェクトまたはユーザーが読み込むスキルにのみ使います。リポジトリが配布元か利用側か判断できない場合は、質問してください。間違った場所に作成すると、誰にも見つけられないスキルを出荷することになります。

Stage 3 — 内容を計画する

• 本文 = 長期的に使える再利用可能な指示。約500行未満にします。それを超えそうな場合は、詳しい内容を references/<topic>.md（必要なときだけ読み込まれる）に移し、本文から参照してください。プロジェクトスキルでは、どちらの場合も参照先がグラフに自動接続されるため、バッククォートで囲んだ `references/<topic>.md` というパスで問題ありません。言及をクリック可能なインラインリンクにしたい場合にのみ、[[references/<topic>]] の Wiki リンクを使います。グローバルスキルでは、通常のバッククォート付きパスを使ってください。グローバルの参照はグラフドキュメントではないため、Wiki リンクにするとリンク切れになります。参照の階層は1段までにしてください。
• 含めないでください：README／CHANGELOG／QUICK_REFERENCE、スキル自体のインストール手順、バージョン履歴、ホスト固有の内容。スキルそのものが指示であり、指示についてのドキュメントではありません。
• 分野別スキルでは、修正対象の失敗パターンと、そのスキルが問題を解決したことをどう証明するかを計画してください（Stage 4）。

Stage 4 — RED ベースライン（分野別スキルのみ）

スキルを書く前に、それを使わずにシナリオを実行し、エージェントの誤った動作を、正当化の説明も含めてそのまま記録してください（例：「テストは簡単なので省略しました」）。そうした正当化こそ、スキル本文で塞ぐべき抜け道です。スキルを適用せず、新しいエージェントセッション（新しいチャット、サブエージェント、または2つ目のターミナル）でシナリオを実行し、会話記録を保存してください。クリーンな状態で実行する方法がない場合は、代わりにユーザーとベースラインを検討してください。通常のリファレンススキルでは、このステージを省略します。

Stage 5 — スキルを作成する

スキル動詞を使ってソースを作成します（fs-direct。サーバーが起動していれば、ライブプレビューが更新されます）。

write({ skill: { name: "<lowercase-hyphen-name>", description: "<triggers>", body: "<markdown>", scope: "project" } })

フロントマターの仕様（書き込み時に検証されるため、正確に記述してください）：

• name — 小文字のアルファベット、数字、ハイフンのみ。64文字以下で、ディレクトリ名と一致すること。
• description — 1024文字以下、XMLタグなし、versionフィールドなし。Stage 7を参照してください。
• これ以外は記述しないでください。OKが独自のフロントマターを挿入することはありません。管理情報は.ok/に保存されます。

本文は、エージェントに向けた直接的な指示（命令形、二人称）として、抽象的ではなく具体的に記述してください。

深掘り用ファイル（オンデマンドで読み込まれるreferences/*.mdと、テキストとして表示され、OKによって実行されることのないscripts/*）は、ネイティブのWrite／catではなく、スキル動詞を使って追加します。

# write one or more bundle files (independent of body — no need to resend SKILL.md)
write({ skill: { name: "<name>", files: [{ path: "references/tiers.md", content: "..." }] } })

# surgical edit inside one bundle file (mirrors edit({ document }))
edit({ skill: { name: "<name>", file: "references/tiers.md", find: "...", replace: "..." } })

# list the bundle, then read one file (no native cat)
skills({ name: "<name>" })                         # → files: [{ path, kind }]
skills({ name: "<name>", file: "references/tiers.md" })   # → { path, kind, text }

# delete specific bundle files (omit `files` to delete the whole skill)
delete({ skill: { name: "<name>", files: ["references/tiers.md"] } })

パスはスキル相対で、スキルディレクトリ内に収める必要があります（../や絶対パスは使えません）。references/とscripts/が一般的な配置場所で、まずはこちらを使ってください。その他のルート（assets/やハーネス固有のディレクトリ）も使用できます。公開済みのスキルにはこれらが含まれており、インポート時にもそのまま保持されるためです。referencesは1階層の深さにとどめてください。プロジェクト内の.md参照ファイルは、本文での言及方法にかかわらず、グラフ内で対応するSKILLに自動接続されるライブコンテンツドキュメントになります。バッククォートで囲んだ`references/<name>.md`パスも、[[references/<name>]]というWikiリンクと同様にグラフに追加されます。クリック可能なインラインリンクが必要な場合にのみ、Wikiリンク（または[label](references/<name>.md)）を使ってください。グローバルスキルは異なり、その参照ファイルはグラフドキュメントになりません。そのため、グローバルスキルでは通常のバッククォート付きパスを使ってください。Wikiリンクはリンク切れになります。

Stage 6 — GREEN評価＋リファクタリング

スキルを使ってシナリオを再実行します。規律を促すスキルの場合は、プレッシャーテストを行います。2～3種類のプレッシャー（時間、権威、埋没費用）を組み合わせてもエージェントがルールに従うことを確認し、抜け穴があれば修正して再テストします（references/pressure-testing.md）。リファレンススキルの場合は、エージェントがタスクを正しく実行できるようになったことと、本文が必要以上に長くないことを確認します。エージェントがすでに知っている内容は削除してください。

Stage 7 — 説明を最適化する（これによってスキルが起動します）

エージェントがスキルを読み込むかどうかを判断する際に見るのは、descriptionだけです。適切に記述してください（references/description-optimization.md）。

• 要約ではなく、起動条件を記述します。 本文の要約ではなく、ユーザーの言葉や言い回しを使って、どんなときに使うべきかを記述します。説明にワークフローを要約すると、エージェントは説明に従い、本文を読み飛ばすようになります。
• 起動漏れを防ぐため、具体的で、やや強めに記述します。 起動対象となる状況、動詞、言い回しを明示します。
• 誤判定しないか、近い内容のクエリで確認します。起動すべき言い回しと、隣接する内容でも起動すべきでない言い回しを確認してください。

ステージ 8 — インストール（利用可能な場所を選択）

スキルは、作成先のフォルダーを読み込むエージェントであれば、すでに利用可能です。スキルはそのフォルダー自体であり（下書き状態はありません）、install は利用先を追加で管理します。

install({ name: "<name>", add: ["codex", "opencode"] })   // add locations
install({ name: "<name>", remove: ["codex"] })            // remove locations
install({ name: "<name>", add: ["codex"], mode: "link" }) // ...as a symlink
install({ name: "<name>", convert: ["codex"], mode: "copy" })  // change one location's form
install({ name: "<name>", source: ".team/skills" })       // move the real folder (run alone)

場所 ID はエディターホスト ID（claude … pi）、agents（ベンダー中立のハブ）、または .team/skills のようなカスタムルートパスです。

各場所での形式。 mode が適用されるのは、呼び出しで指定した場所、つまり add または convert の対象だけです。それ以外には適用されません。add では省略してください。新しい場所には、スキルがすでに使用している形式が適用されます。スキル全体に適用されるモードはありません。インストールによって、指定していない場所が書き換えられることはありません。既存の場所の形式を変更するには convert を使います。これは場所の登録状態を変更しません。形式を統一するには、すべての場所を指定してください。

各形式の意味。 シンボリックリンクはソースを参照するため、内容が乖離しません。コピーは独立したフォルダーです。編集されていないコピーは、スキルの監視機能が実行されたとき、またはサーバーの起動時にソースから更新されるため、ソースの編集内容が反映されるまで一時的に遅れることがあります。手動で編集するとコピーが分岐し、それ以降の自動上書きが行われなくなります。

ライフサイクル。 edit({ skill }) で編集すると、ソースに反映され、その場でバージョン管理されます。「すべての場所からアンインストール」する方法はありません。他の場所をすべて削除しても、ソースフォルダーは引き続きエージェントに読み込まれます。スキルが存在しなくなるのは、ソースとすべての場所を削除する delete({ skill }) を実行したときだけです。プロジェクトスキルは history({ skill }) → restore_version({ skill, version }) で以前の状態に戻せます。このビルドでは、グローバルスキルはバージョン管理されません。プロジェクトスキルでは、スキルフォルダーをコミットしてください。通常の Git ファイルなので、チームメイトはプル時に取得できます。

注意事項

• 重複するスキルを増やすより、優れたスキルを 1 つ作ることを優先してください。トリガーが異なる場合に限り、分割してください。（ステージ 1 のゲートでこれを徹底してください。重複を後から見つければよいと放置しないでください。）
• 配置を決める基準はスコープだけです。ハーネス、形式、ツールチェーンに関する前提をスコープに含めたり、スコープの質問の文言に組み込んだりしないでください。作成するのは OpenKnowledge のスキルです。write({ skill }) で作成すると、プロジェクトの既定のスキル保存先に、帰属情報とバージョン管理を備えた実際のフォルダーが作られます。その後、install で各所に展開してください。エディターのディレクトリーにコピーを手作業でばらまかないでください。展開は install が担います。記録済みで未編集のコピーは、監視機能または起動時の同期で更新されます（手動で編集したコピーは分岐し、更新されなくなります）。このフローを使う場合は、このフローを通して作成してください。
• スキルの動作（バージョン管理、インストール先、スコープの意味）に関する説明は、このガイドまたはツールの説明に基づいてください。推測からシステムの事実を断定しないでください。
• 理由を示さずに、例外のない「必ず」や「決して」といったルールを設けないでください。そうしたルールは雑音と見なされ、無視されます。理由を説明してください。
• 実行可能な scripts/ を含むスキルは、その内容がそのまま別のエージェントの信頼境界内に置かれます。ユーザーが確認したスクリプトだけを含めてください。