Skip to main content التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
يتجاوز الأمر المباشر Prompt المخصّص للمراجعة. افحص المصدر قبل تشغيله.
npx skills add https://github.com/ynitto/sandbox --skill statemachine-useيبقى الأمر في سطر واحد. مرّر أفقيًا لمراجعته كاملًا قبل النسخ.
تفضّل نسخة محلية؟ نزّل الملفات المتاحة حاليًا لدى SkillsMP.
المهن ذات الصلةSOC
استنادا إلى تصنيف SOC المهني
| name | statemachine-use |
| description | 「ステートマシンを実行して」「ステートマシンを作成/作って」「YAMLワークフローを動かして」「ワークフローを回して」「エージェントループを起動して」「このYAMLを実行して」などで発動。作成モード（手順を.statemachine/{名前}/に生成）と実行モード（YAMLをLLM駆動で実行）を持つ。 |
| metadata | {"version":"2.1.0","tier":"experimental","category":"workflow","tags":["statemachine","yaml-workflow","agent-loop","hybrid-execution"]} |
YAML ステートマシン スキル
YAMLと外部マークダウンファイルで定義されたLLM駆動ステートマシンを作成・実行します。
モードの選択
| ユーザーの意図 | モード |
|---|
| 「〜という手順でステートマシンを作って」 | 作成モード |
| 「〜を実行して」「〜を動かして」「YAMLを回して」 | 実行モード |
作成モード
ユーザーが自然言語で説明した手順を .statemachine/{名前}/ フォルダ以下のYAML+マークダウンに落とし込む。
ステップ1: 利用可能なスキルを調査する
ls .github/skills/
出力されたスキル名を記録する。アクション定義でスキル呼び出しを活用できる場合に参照する。
ステップ2: 手順を状態遷移として分解する
LLM読み飛ばし防止の設計原則（重要）
- ルーティングロジックをアクションに書かない — 分岐判断はトランジション条件に書く
- 出力形式を強制する — 条件が評価しやすいキーワード出力を要求する（例:
PASS / FAIL）
- 将来のステートをヒントとして含めない — アクションは現在のステートの作業のみを指示する
- アクションの末尾に単一指示を付与する — 全アクションmdの末尾に必ず下記を追記する:
この指示に従ってタスクを実行してください。
完了後、指定された形式で出力のみを返してください。次のステップは別途指示されます。
- スクリプトは原則作成しない — スキル（ステップ1で確認）や他のAI機能でアクションを実行する
`skill-name` スキル と書く。この記法が無いと実行ハーネスはスキルを読み込まず、スクリプトの場所も分からない成功条件を output_validator で定義する — 「第1行が OK か FAILED」のような機械が判定できる出力契約を states に書く。書かないとアクションの成否を確認できず、失敗したまま次のステートへ進む成果物の正しさは check で測る — output_validator が見るのは書式だけで、「OK」と書くのはモデル自身である。成果物が実際に仕様どおり動くかを見るには、ハーネスが実行する検査コマンドを宣言する（下記）check — 遷移の材料を自己申告から実測へ移す
states:
implement:
action_file: actions/implement.md
output_validator: "startswith:OK"
check: "python3 -m pytest tests/test_x.py -q"
check_retries: 2
transitions:
- from: implement
to: review
condition_rule: "equals:check_ok:true"
検査が落ちたら、測った不一致を課題文へ足して同じステートをやり直す。再投入を使い切っても
落ちるなら、実行を止めて escalate（この段では解けない = 上位の段へ回すシグナル）を返す。
ローカルモデルで定型作業を回すなら、これが受入率を決める唯一のレバーである。実測では
検知を伴わない分解は受入を下げ（0/3）、決定的な検知 + 再投入で 3/3 になった。逆に通る課題に
ゲートは課金しない（呼び出し回数は増えない）。書式・使える宣言の形・失敗時の動作は
references/schema.md の「決定的検査 (check)」を参照。作例は examples/gated_implement.yaml。
検査を置ける単位で割る — ステートを細かく割ること自体に効果は無い（実測では逆に下がる）。
分解の目的は検査を差し込む場所を作ることである。1 つのステートを設計するとき、
「このステートの成果は、どのコマンドの終了コードで測れるか」を先に決める。決められないなら、
そのステートはまだ割り方が正しくない。
実行できるスクリプトの範囲（ハーネスが強制する。定義側もこれに合わせて書く）:
| 決まり | 意味 |
|---|
アクション本文が名指しした .py / .js / .sh、または移譲先スキルの SKILL.md に載っている .py / .js / .sh のみ | scripts/ に置いてあるだけの下請けは呼べない |
固定インタプリタで実行する（.py→python / .js→node / .sh→bash または sh） | shebang や実行ビットで走らせるものを決めさせない |
| スキル名は実行コマンドではない | `demo` スキル の demo を command に置いても動かない。スクリプトのパスを書く |
bash -c などの任意シェルは使えない | シェル経由の合成コマンドは拒否される |
| コマンドの stdout が空でも exit 0 なら成功 | 出力の有無で成否を判定しない。空の結果は正常な空結果 |
パターンの自動検出 — 詳細テンプレートは references/patterns.md を参照:
| 手順の特徴 | 適用するパターン |
|---|
| 「同時に」「並列で」「〜と〜を一緒に」 | Fan-out/Fan-in |
| 処理後に次があるか確認してループ | ContinueAsNew Loop |
| 副作用の大きい操作（変更・デプロイ等）の後 | ゲートステート |
| 複雑な判断・推論を含むステート | ReActアンカリング |
| 「失敗したら元に戻す」「ロールバック」 | Saga |
| 5ステート以上の長いワークフロー | マイルストーンアンカー |
ステップ3: scaffold で骨組みを生成する
フォルダとファイルを手で書かない。ステップ2で決めた状態列を scaffold へ渡す:
python .github/skills/statemachine-use/scripts/scaffold.py {名前} \
--state "first_state:説明" --state second_state
--state ID[:説明] を実行順に並べる。終端は --terminal ID[:説明]（省略時は complete を自動で足す）。.statemachine/{名前}/ に workflow.yaml と actions/*.md スタブを生成し、生成直後に検証する
（通らない骨組みは残さない）。- 骨組みは直列遷移。分岐・ループ・複雑な条件（
conditions/{from}_to_{to}.md）はステップ4で足す。
- 新スキーマの口（
output_validator / check / check_retries / check_on_exhausted / write）は
コメント付きで含まれる——ステップ2で決めた検査コマンドのコメントを外して実値にする。
ステップ4: スタブを埋める
生成された workflow.yaml と actions/*.md を以下の形へ埋める。全フィールドの仕様は references/schema.md を参照:
name: "ワークフロー名"
initial_state: first_state
context:
config:
max_steps: 30
states:
state_id:
description: "ラベル"
action_file: actions/state_id.md
output_key: result_key
terminal: false
transitions:
- from: state_id
to: other_id
condition: "自然言語条件"
priority: 1
## [state_id: 何をするか]
（スキル呼び出しや具体的な指示）
**入力:** {{input}}
**前のステートの出力:** {{last_output}}
**出力形式:** XXX または YYY の一語のみで回答してください。
この指示に従ってタスクを実行してください。
完了後、指定された形式で出力のみを返してください。次のステップは別途指示されます。
conditions/{from}to{to}.md（複雑な条件のみ）:
以下の条件をYES/NOで評価してください:
- {{retry_count}} が {{max_retries}} 未満である、かつ
- 最後の出力が RETRY で始まる
両方を満たす場合のみ YES と回答してください。
作成例
name: "コードレビュー"
initial_state: analyze
states:
analyze:
action_file: actions/analyze.md
output_key: analysis_result
approve:
action_file: actions/approve.md
terminal: true
request_revision:
action_file: actions/request_revision.md
terminal: true
transitions:
- from: analyze
to: approve
condition: "analysis_result が PASS で始まる"
priority: 1
- from: analyze
to: request_revision
condition: "analysis_result が PASS 以外で始まる"
priority: 2
<!-- .statemachine/review_code/actions/analyze.md -->
## [analyze: コード品質を分析する]
以下のコードを品質の観点で分析してください。
**対象コード:** {{input}}
確認項目: バグ、コードの臭い、エラーハンドリング漏れ、パフォーマンス問題
**出力形式:** 最初の行に PASS / MINOR / MAJOR / CRITICAL のいずれか一語、その後に問題点を列挙してください。
この指示に従ってタスクを実行してください。
完了後、指定された形式で出力のみを返してください。次のステップは別途指示されます。
定義のメンテナンス — migrate
スキーマは加算的に拡張される（check → check_on_exhausted → write）。手持ちの定義は
migrate で検査し、追随させる:
python .github/skills/statemachine-use/scripts/migrate.py path/to/workflow.yaml
python .github/skills/statemachine-use/scripts/migrate.py .statemachine --apply
検出項目: check 宣言の無いステートからの check_* 分岐（検証エラー・修正案の提示）、
シェル記号入り check（投入前に落ちる）、write 未割付（編集対象が一意に決まる場合だけ提案）、
check_on_exhausted の暗黙既定の明示化。後ろ 2 つはコメントを保ったまま --apply で書き換える。
正規化・検証は engine.py の 1 実装を使うので、判定が実行系とずれることはない。
実行モード
⛔ ハーネス実行プロトコル — 禁止行動（違反時は即座に停止して再確認）
| 禁止行動 | 代替行動 |
|---|
| アクション実行前に条件リストを取得する | ① 実行 → 出力確定 → ② 条件取得 の順を守る |
| 現在のステート以外の作業を実行する | 現在のステートの作業のみ実行する |
## [現在のステート: {state_id}] 宣言を省略する | 毎ステートの冒頭で必ず宣言する |
| 条件を評価せずに遷移先を独断で決める | 必ず ④ の Python スクリプトで遷移先を確定する |
| 複数ステートをまとめて実行する | 1ステート = 1ターンを厳守する |
Step 0: 検証と開始ステートの取得
python .github/skills/statemachine-use/scripts/run_machine.py .statemachine/{名前}/workflow.yaml --dry-run
python .github/skills/statemachine-use/scripts/next_state.py {名前} --initial-state
出力された state_id を現在のステートとして実行を開始する。
Step 1〜N: ステートループ（terminal まで繰り返す）
現在のステートに入ったことを宣言する（毎ステート必須）:
現在のステートのアクションプロンプトを実行し、出力を last_output として記録する。
重要: アクション実行前に条件を確認してはならない。出力が確定してから条件リストを取得する。
状態値は --context の JSON オブジェクトで渡す（last_output と各 output_key）。
python .github/skills/statemachine-use/scripts/next_state.py {名前} \
--state {現在のstate_id} --auto-eval \
--context '{"last_output":"{last_outputの第1行}"}'
遷移先がここで確定する応答は 2 形。どちらも ③④ を飛ばして ⑤ へ進む:
auto_advance: true — 無条件トランジション。conditions は返らず next_state が遷移先。resolved が null 以外 — condition_rule だけで確定。
auto_advance が省くのは条件評価だけ。① のアクション実行と output_validator による成功確認は省略しない。
アクションが失敗したステートから遷移してはならない。
resolved が null の場合のみ needs_llm_eval: true の条件を LLM で評価する。
旧ハーネス互換として --list-conditions / --last-output / --output KEY=VALUE も受け付ける。
旧引数は --context に無いキーの補完としてのみ効く。新規の呼び出しでは使わない。
needs_llm_eval: true の条件のみ last_output に対して YES / NO で評価し、JSON を構築する:
（needs_llm_eval: false の条件インデックスは省略可。--eval 渡し時に自動上書きされる）
python .github/skills/statemachine-use/scripts/next_state.py {名前} \
--state {現在のstate_id} --eval '{"1": false}' \
--context '{"last_output":"{last_outputの第1行}"}'
出力: 次の state_id、NONE（一致なし）、TERMINAL（終端）
condition_rule がある条件は --context から自動評価され、--eval の値を上書きする。
## [ステート {state_id} 完了]
- 出力: {last_outputの第1行}
- 遷移先: {次のstate_id または TERMINAL}
- 次の
state_id → そのステートへ移動して Step 1 に戻る
TERMINAL → 実行完了、最終出力を表示NONE → on_no_transition 設定に従う（デフォルト: エラー）
