create-skill

スキルの作成

openclaw-superpowers に新しいスキルを追加するためのメタスキルです。あなたやコントリビューターが新しいスキルを追加する場合は、必ずこの手順に従ってください。

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

何かを書く前に、次の質問に答えてください。

1. このスキルは何をしますか？（1 文で）
2. エージェントはいつこれを使うべきですか？（トリガー）
3. コアスキルですか、それとも OpenClaw ネイティブですか？
   • コア： 一般的なエージェントの方法論（ブレインストーミング、デバッグ、計画）。あらゆるエージェントのランタイムで機能します。
   • OpenClaw ネイティブ： 永続性、長時間実行されるセッション、またはメモリが必要です。常時稼働する OpenClaw のモデルに特化しています。
4. 既存のスキルですでに対応できますか？ できる場合は、新しく作成するのではなく既存のスキルを拡張してください。
5. このスキルはセッション間やウェイクアップ間で状態を保持する必要がありますか？ 必要な場合は、stateful: true と STATE_SCHEMA.yaml を使用してください。

ステップ 2：名前を選ぶ

• ケバブケースを使用します：my-new-skill
• 名前にはカテゴリではなくアクションを記述します：error-handling-utils ではなく retry-with-backoff
• 短くします（最大 2～4 語）。

ステップ 3：スキルのひな形を作成する

ディレクトリとファイルを作成します。

skills/<core|openclaw-native>/<skill-name>/
  ├── SKILL.md
  └── STATE_SCHEMA.yaml   # only if stateful: true

SKILL.md には、フロントマターのテンプレートを使用します（任意のフィールドはコメントとして示されています）。

---
name: <skill-name>
description: <One sentence — what it does and when to use it.>
# cron: "<5-field cron expression>"   # optional: if skill runs on a schedule
# stateful: true                       # optional: if skill persists state
---

コンテンツの構成全体については、TEMPLATE.md を参照してください。

ステップ 4：コンテンツを書く

既存のスキルから学んだ、次の規約に従ってください。

• 直接的に書きます。 前置きではなく、中心となる原則から始めます。「計画は無駄な作業を防ぎます。」のように書き、「このスキルは計画の立て方を支援します。」とは書きません。
• 具体的な指示を書きます。 エージェントがすべきことを、手順に沿って正確に伝えます。曖昧な指針は避けてください。
• 簡潔にします。 このリポジトリの優れたスキルは 50 行未満です。それより長くなる場合は、より小さなスキルに分割してください。
• 判断基準を含めます。 いつ使うべきか、いつ使うべきでないかをエージェントに伝えてください。
• 検証手順にはチェックリストを使用します（verification-before-completion を参照）。
• スキルが複数のセッションにまたがる作業に適用される場合は、チェックポイントの指針を追加します。
• 状態を文章で記述するのは誤りです。 スキルで進捗を Markdown やメモリファイルに保存する方法を説明する場合は、stateful: true と STATE_SCHEMA.yaml を使用してください。

ステップ 5：検証する

コミットする前に、次の点を確認します。

• フロントマターが正しい — name がディレクトリ名と一致し、description が明確な 1 文になっている
• ファイルのパスが正しい — skills/<core|openclaw-native>/<name>/SKILL.md
• 既存のスキルと重複していない — 重複する場合は、明確に統合するか、違いを示す
• テンプレートに従っている — When to Use、The Process、Key Principles の各セクションがある
• 80 行未満 — それより長い場合は、分割を検討する
• 実行可能である — 各手順で、エージェントが何をするべきかを示しており、何を考えるべきかだけを述べていない
• テスト可能である — 出力を見れば、エージェントがスキルに正しく従ったかどうかを判断できる
• stateful: true の場合 — version: と fields: のキーを含む STATE_SCHEMA.yaml がある
• cron: が設定されている場合 — 式が有効な 5 フィールドの cron 構文になっている

ステップ 6：登録する

手動での登録は不要です。OpenClaw は拡張ディレクトリからスキルを自動検出します。次の点を確認してください。

1. ディレクトリが skills/core/ または skills/openclaw-native/ の下にある
2. ファイル名が正確に SKILL.md である
3. インストール用のシンボリックリンクが設定されている（install.sh が処理します）
4. ステートフルなスキルの場合、install.sh が ~/.openclaw/skill-state/<skill-name>/ を自動的に作成する
5. cron: を含むスキルの場合、次回実行時に install.sh が OpenClaw の cron に登録する

よくある間違い

• 抽象的すぎる。「エッジケースを慎重に検討する」はスキルの手順ではありません。「3つのエッジケースを挙げ、それぞれのテストを書く」は手順です。
• 範囲が広すぎる。 スキルが複数の異なるワークフローを扱う場合は、分割してください。
• トリガーが不足している。「いつ使うか」の基準が明確でないと、エージェントはスキルをいつ呼び出せばよいかわかりません。
• 既存のスキルと重複している。 同様のものを作成する前に、brainstorming、writing-plans、systematic-debugging、verification-before-completionを確認してください。
• 状態を文章で記述する。 スキルでMarkdownやメモリファイルへの進捗保存を説明している場合は、代わりにstateful: trueとSTATE_SCHEMA.yamlを使用してください。構造化されており、機械で読み取り可能で、再開もできます。