craft-skills-and-memories

スキルとメモリーの作成

エージェントの指示ソースのライフサイクルの両端、つまり、価値のあるスキルやメモリーを作成して残すことと、実際にうまく機能しない場合に修正することを扱うスキルです。

壊れたスキルや古くなったメモリーはバグです。それを回避して先に進むと、次のセッションでまた問題が起こります。

対象範囲：

• スキルは汎用的です。 スキルには、プロジェクト固有の内容を含めてはいけません。特定のプロジェクトでしか当てはまらない事実は、スキルではなく、そのプロジェクトのドキュメントまたはメモリーに記載します。
• メモリーはプロジェクト固有にも共通にもできます。 事実が当てはまる範囲に合わせ、エージェントのメモリーシステムが提供するスコープ（プロジェクト、ユーザー、またはグローバル）でメモリーを作成、修正します。

適用するタイミング

作成：

• 「これをメモリーとして保存して」／「これをスキルにして」／「これを覚えておいて」
• 将来のセッションに活用するため、教訓やワークフローを記録することが決まった場合（修正への対応を決めるのは /never-twice の役割で、その第3段階でこちらに引き継ぎます）

修正：

• スキルに記載されたフラグ、コマンド、ファイルが存在しなくなった
• スキルのコピー＆ペースト用ブロックが再現可能な形で機能しない
• スキルの抽出または検証ルールで、検出すべきものを検出できない
• 呼び出されたメモリーに、存在しない、または置き換えられたファイル、フラグ、ワークフローが記載されている
• スキルまたはメモリーが正しく機能していないとユーザーが伝えた

品質基準（新規作成と修正の両方）

• 引用ではなく、例・シナリオ・コンセプトを軸にします。 具体的な事例（失敗したコマンド、修正後のブロック、実際に取り組んだシナリオ）は、抽象的な説明やユーザーの言葉そのものより、後のセッションでずっと思い出しやすくなります。
  • 各項目は事例を先に示し、何がどこで起きたか、次にそこから得られたルール、最後に適用範囲や例外を記述します。
  • 正確な文言そのものが指示（禁止事項や命名規則など）である場合に限り、短い原文の表現を残します。それ以外はルールとして言い換えます。
  • 引用を軸にした既存の項目に手を入れる場合は、この形式に改めます。
• 説明文はトリガーです。 「〜するときに使用」といった短い文で、機能させるべき瞬間を一つだけ示し、内容を要約しないでください。要約のような説明文は、起動の不具合につながります。
• スキルには、そのまま実行・コピー・貼り付けできるブロックと、初めて使うエージェントでも手順に沿って進められる具体例を含めます。
• スキル一覧は簡潔で、互いに重複しないようにします。 スキルの作成、統合、分割に関する設計条件は次のとおりです。
  • それぞれの発動条件には、必ず一つだけ対応するスキルを設けます。各スキルは固有の発動条件を示し、一覧全体でトリガーが相互に重ならないようにします。重複は不備であり、統合するか明確に分けて解消します。重複を許容してはいけません。このスキルの作成と修正のライフサイクルは、一つにまとめられます。発動条件が共通し、読者も一人だからです。
  • スキルは多いより少ないほうが適切です。同じ読者が同じ場面で使う二つのスキルは統合します。
  • スキルを過度に複雑または大規模にしないでください。大きくなったら、発動条件ごとに分割します。複雑なスキルは、トリガーが重複していても、関連する別のスキルを取り込みません。説明文を明確にしてください。
  • 全体を通して流し読みしやすくします。冒頭に要点を置いた短い段落を使い、テキストの塊は避けます（前述の「例を軸にする」ルールに沿って、内容の順序を決めます）。文体規則よりも読者にとっての読みやすさを優先し、正確性の規則は常に守ります。スキルのページやメモリ本文の文章には /working-text スキルを適用します。フロントマターの説明文は、このスキルのトリガーとして機能させます。
  • 変更に応じて各セクションの形式を選びます。この基準以外に決まった形式はありません。図と文章で同じ内容を繰り返してはいけません。プログラマー向けの文体にします。文章にこのスキルが適用される条件は、下の /natural-writing の箇条書きに示されています。
  • フォルダーも含め、後方互換性は維持しません。分割、統合、廃止は通常の変更です。削除はすべて /never-twice スキル（ガードの削除）に従って監査します。ただし、ホストリポジトリが定める互換性契約（公開済みのインストールパスなど）は、フォルダーの移動にも適用されます。
• メモリには理由を記録し、相対日付を絶対日付に変換して、関連するメモリへのリンクを追加します。保存形式（ファイル、レコード、項目など）を問わず、メモリ一つにつき事実は一つだけにします。そうすれば、誤った内容を正しい内容まで削除せずに取り除けます。誤ったメモリは、継ぎはぎで修正するのではなく削除します。
• 文章を書き直すときは、/natural-writing スキルが存在し、呼び出し可能なら適用します。ハーネスの仕様でユーザーしか呼び出せない場合は、その手順を黙って省略せず、ユーザーに /natural-writing の実行を提案します。

新規作成

1. まず既存の格納先を確認します。 そのトピックをすでに扱うスキルやメモリがあれば、更新します。重複は内容の乖離につながります。
2. スキルとメモリのどちらにするか選びます。
   • 誰でもインストールできる汎用的な動作：スキル。
   • 個人またはプロジェクトに固有の事実、ポリシー、好み：適切なスコープのメモリ。
   • 自動検出できるタスクではなく、個人のワークフローを定めるスキルは、明示的な呼び出しのみとします。つまり、フロントマターに disable-model-invocation: true を設定し、Codex の場合は agents/openai.yaml で policy.allow_implicit_invocation: false を設定します。
3. 上記の品質基準に沿って、きっかけとなった事例を示しながら記述します。
4. 必要な場所に登録します。 スキルは、リポジトリの作成チェックリスト（マニフェスト、カタログ、チェック）に従います。メモリシステムにインデックスがある場合は、同じ編集でメモリの項目も追加します。
5. ゲートがある場合は実行します（リポジトリのチェック、レビュー）。メモリの場合は、初めて読むセッションでも正しく行動できるかを確認しながら読み直します。

修正

1. 一時的な原因を除外する

バックエンドの停止、サンドボックスの制限、ローカルツールの設定は、スキルの欠陥ではありません。根本原因が指示そのものにある場合に限り、欠陥とみなします。

2. まず現在のタスクを完了する

壊れた手順を回避して、ユーザーが実際に依頼したことを完了してください。修正はその後に行い、タスクの代わりにしてはいけません。

3. 正規のソースで修正する

• 作成元のリポジトリにあるスキル：該当するソース（SKILL.md、references/、scripts/）を直接編集します。
• 編集を許可されているインストール済みまたはベンダー提供のスキルのコピー（例：個人用スキルディレクトリ）：そのコピーを編集します。上流のソースにも欠陥が残っている場合は、そのことをユーザーに伝えます。
• メモリ：保存場所にあるメモリを編集します。メモリシステムにインデックスがある場合は、同じ編集で該当エントリも更新します。単に古くなっているのではなく、誤っているメモリは、修正を加えるのではなく削除します。
• 書き込み権限がない場合：欠陥と、ユーザーに提案する修正を報告します。

4. 注記を追加するのではなく、該当箇所に修正を織り込む

該当する手順を書き直し、その記述自体が正しく、品質基準を満たすようにします。コピーして実行できるブロックは、実行可能な状態に保ちます。

一度きりの警告を末尾に付け足しても、壊れた指示はそのまま残ります。ルールを削除する書き直しには、/never-twice スキル（「ガードの削除」）に従って削除監査を行います。

機械的な失敗には、まずコードで対処します。 修正を反映する場所は、次のとおりです。

• スクリプトで動作するスキルの機械的な動作が実際に失敗する場合（プローブの読み取りミス、コマンドの誤解析、エッジケースでのクラッシュなど）：スクリプトを修正し、事象を再現する回帰テストを追加します。
• インシデント警告の文章は、対象を限定した留保事項です。トラップの説明や事前知識は、判断上の教訓にのみ留め、仕組みはスクリプトに実装します。
• 公開される契約ドキュメント（CLI の形式、スキーマ、出力フィールド）は別扱いです。説明対象のインターフェース変更と合わせて更新します。ドキュメントとソースの同期を検証するゲートがある場合は、そのゲートで両者の対応関係を厳密に担保します。
• ドキュメントのみに関する欠陥（有効化メタデータ、呼び出し例、ワークフローの説明など）は、実際のソースで修正します。失敗の原因ではないスクリプトに手を加えてはいけません。

コードを先に修正する理由：テスト済みスクリプトにトラップを織り込めば、同じ失敗は再発しません。文章だけに織り込むと、トラップのカタログが膨らみます。事象のたびに警告の段落が追加されてファイルが肥大化し、後のセッションで壊れた手順がまた手作業で書き直されます。

実例：ある監視スキルでは、シェルプローブに関するトラップ（単語分割、検索対象にも一致する grep、timeout バイナリの欠如）の説明が蓄積していました。最終的にプローブをテスト済みのスクリプトへ移し、文章は判断に関わる内容だけに絞りました。

5. 通常のゲートに変更を通す

スキルやメモリの編集も、他の変更と同様です。保存場所で適用されるチェックとレビューのプロセスを実行します。該当するプロセスがない場合（例：単純なインストール済みコピー）は、少なくとも失敗したシナリオを再実行し、書き直した指示が機能することを確認します。

作業例

作成の例。 ユーザーが、コミットメッセージを72桁で折り返すようエージェントに2回修正を求めます。

• これはスキルではなくメモリーです。個人的な方針であり、リポジトリをまたいで適用され、インストールできるものではありません。
• ユーザーレベルのメモリー commit-message-rules として保存し、修正内容を具体例として、その理由も記録します（メモリーシステムにインデックスがある場合は、それも更新します）。
• 引用ではなく、例を中心にします。ユーザーの正確な言葉ではなく、ルールと具体的な修正前後を記録します。

スキルの不具合。 レビュースキルに従っている最中に、claude -p --output-format stream-json がエラーで終了し、出力ファイルが空になります。

1. 一時的な問題でしょうか？ いいえ。毎回再現し、claude --help には --output-format stream-json には --verbose が必要だと示されています。根本原因は、スキルに記載されたコマンドです。
2. --verbose を追加して再実行し、レビューを完了します。
3. スキルの正式なソースは、作成者のリポジトリをローカルにチェックアウトしたものです。その SKILL.md にあるコピー＆ペースト用のブロックを編集し、--verbose を追加します。
4. 修正はブロック自体に反映し、記載どおりに実行できる状態にします。「注：--verbose も渡してください」という脚注は追加しません。
5. そのリポジトリのチェックを実行し、同じ変更セットに編集を含めてレビューに出します。

古くなったメモリー。 呼び出したプロジェクトメモリーには、デプロイには make release を使うとありますが、数か月前に Makefile のターゲット名が make publish に変更されています。

1. 現在のリポジトリで確認します。古くなっているのはメモリーであり、ビルドではありません。
2. 実際のターゲットを使ってデプロイを完了します。
3. プロジェクトスコープのメモリーを更新し、make publish を記載します（メモリーシステムにインデックス項目がある場合は、それも更新します）。具体例として、ターゲット名の変更も残します。

不具合ではない例。 同じコマンドがバックエンドの過負荷エラーで一度失敗しますが、再試行すると成功します。一時的な問題です。タスクを完了し、スキルには手を加えません。

スキルの使用

適合性は呼び出しごとに判断します。呼び出したスキルのガイダンスが目の前のタスクに合わない場合は、そのスキル全体または特定のルールを適用せず、判断した時点でその理由をユーザーに伝えてください。

• タスクの要件に反して、スキルに機械的に従わないでください。
• スキルを黙って無視しないでください。
• ユーザーが設定した継続的なルール（例：コミット前の必須確認）は、引き続き有効です。これは、ガイダンスが作業と実際に矛盾する場合にも適用されます。

報告

元のタスクの結果とは分けて、作成したもの、または失敗した内容、根本原因、スキルやメモリーに加えた変更をユーザーに伝えてください。