skill-creation

スキルの作成

このスキルは、新しいスキルの作成と既存スキルの改善に役立ちます。学び方を教えるスキルだと考えてください。

スキルを作る理由

問題を解決しても、その知識はたいていセッションとともに失われます。スキルがあれば、それを防げます。「一度解決した」を「解決方法を知っている」に変える手段です。

スキルを作成する理由はいくつかあります。

• 来月、同じ解決策を再発見する必要がなくなります
• ほかのセッションやユーザーも、学んだことを活用できます
• 複雑なワークフローを、壊れやすいものではなく、繰り返し実行できるものにできます

基本の形式

スキルは、SKILL.md ファイルを含むフォルダーに置きます。

.factory/skills/my-skill/
└── SKILL.md

このファイルには、YAML フロントマターと Markdown の本文があります。

---
name: my-skill
version: 1.0.0
description: |
  What this skill does.
  When to use it.
---

# My skill

Instructions go here.

description は非常に重要です。エージェントが、特定のタスクでスキルを読み込むかどうかを判断するために使います。スキルが解決する問題を具体的に記述してください。

スキルを作成するタイミング

すべての作業がスキルに値するわけではありません。スキルは、誰かが繰り返したり共有したりする可能性のある、複雑または長いワークフローに適しています。単発で簡単な作業には、スキルは大げさです。

具体性の適切な度合いが重要です。「コードベースのデバッグ」スキルは、エージェントが遭遇する可能性のある一般的な失敗パターンが多ければ役立ちます。「ログインフローのデバッグ」スキルは、範囲が狭すぎるかもしれません。再利用できるほど汎用的でありながら、役立つほど具体的なバランスを見つけてください。

自分に問いかけてみてください。

• 理解するために、あちこち調べる必要がありましたか？
• もう一度ゼロから解決することになったら、面倒だと感じますか？
• ドキュメントを読むだけでは分からないことがありますか？

どれか一つでも当てはまるなら、スキルにする価値があるでしょう。簡単に済んだ場合や、チュートリアルに従っただけの場合は、作成を見送りましょう。

スキルには、好みやベストプラクティスを盛り込むこともできます。たとえば、データ分析をするときにユーザーがいつも特定のプラットフォームにログインする場合や、チームが何度もつまずく落とし穴がある場合です。ユーザーから繰り返し修正や調整を求められることに気づいたら、それを含める価値があります。

セッションからスキルを抽出する

session-navigation スキルを使って過去のセッションを調べ、抽出する価値のあるパターンを見つけてください。何度も出てきたこと、解決するのに実際に苦労したこと、繰り返し実行しているワークフローを探します。

見つけたら、一般化してください。具体的なパスをパターンに置き換え、前提条件を記し、前提としていることを明示します。見つけた事例だけでなく、類似の状況にも対応できるスキルにしてください。

スキル設計のヒント

スキルを書くときは、human-writing スキルを使ってください。宣伝文句のようなスキルのドキュメントは、内容が伝わりにくくなります。

小さく始めましょう。 何でも扱おうとするスキルより、ひとつのことをうまく行うスキルが優れています。必要に応じて、複数のスキルを組み合わせられます。

検証方法を含めましょう。 スキルが機能したと、どうすれば分かるでしょうか？ 最後に確認項目を追加してください。

## Verify it worked

Run `npm test` and make sure nothing broke.
Check that the new file exists at `src/config.ts`.

失敗についても記録しましょう。 うまくいかないことは何でしょうか？ 避けるべきことは何でしょうか？ こうした情報が、将来の無駄な苦労を防ぎます。

## What not to do

Don't run this on a dirty git working directory.
The `--force` flag will overwrite without asking.

最新の状態を保ちましょう。 スキルは古くなります。依存関係が変わり、API が更新され、よりよい方法が生まれます。スキルが機能しなくなったり、古く感じられたりしたら、更新するか削除してください。

スキルの保存場所

場所	閲覧できる人
.factory/skills/	プロジェクトの全員（git にコミットしてください）
~/.factory/skills/	すべてのプロジェクトで自分だけが使えます

プロジェクトスキルは、チームの規約に適しています。個人スキルは、自分のワークフローに適しています。

既存スキルの改善

スキルの改善が必要な兆候：

• 実行後にユーザーから追加の質問がある
• 繰り返し発生するエッジケースで失敗する
• 作成時よりもよい方法がある

パターンを見つけるには：

# Which sessions used this skill?
rg -l "skill-name" ~/.factory/sessions/*.jsonl

# Where did things go wrong?
rg "error|failed|retry" ~/.factory/sessions/*.jsonl -C 3

スキルを更新するときは、バージョンを上げてください。破壊的変更（出力や入力の変更）の場合は、メジャーバージョンを上げます。

調査メモ

この一部は、学習するエージェントに関する学術研究に基づいています。

Voyager は、エージェントが時間をかけてスキルライブラリを構築し、各スキルをより単純なスキルから構成できることを示しました。

CASCADE は、スキルを1つのエージェントのために保存するだけでなく、エージェント間で共有できることを実証しました。

SEAgent は、失敗から学ぶことが成功から学ぶことと同じくらい価値があると明らかにしました。

Reflexion は、言葉によるフィードバック（何がうまくいかなかったのかを平易な言葉で説明すること）が、エージェントの振る舞いの改善には数値スコアより効果的であることを示しました。

ループ

1. 何かに取り組む
2. 自明でないことを学んだときに気づく
3. それをスキルとして抽出する
4. 次回、そのスキルを使う
5. うまくいったかどうかに基づいてスキルを改善する
6. 繰り返す