step-by-step

GG → ステップバイステップ → ワークフロー

概要

このスキルを使用すると、タスクリスト、計画のチェックリスト、学習の展開、手動検証マトリックスを、常に1つのステップだけを実行中にするワークフローに変換できます。まず可能な範囲で検証を行い、今すぐ行うことをユーザーに正確に伝え、選択可能な支援方法と自動化方法を提示し、タイムスタンプ付きのセッションフォルダーに作業状態を保存します。現在のステップが解決するまで、次のステップには進みません。

このスキルを使用する場合

次の場合にトリガーします：

• タスクにエージェントの作業と、ユーザーが実行する手動作業または検証が混在している。
• 実行にステップ間で人間の確認が必要である。
• 計画、学習、またはタスクに、順序立てて実施する展開、セットアップ、検証のチェックリストが含まれている。
• ユーザーが明示的にステップバイステップの案内を求めている、または次に何をすべきか尋ねている。

次の場合はスキップします：

• ユーザーの関与なしに、エージェントがタスク全体を自律的に実行できる。
• ユーザーが対話形式での案内ではなく、チェックリスト全体を一度に提示するよう求めている。
• 順序付きのステップキューを特定または安全に作成できない。

よくある誤解

#	誤解	正しい理解	重要な概念
1	ユーザーが計画全体を確認できるよう、エージェントはすべてのステップを一度に提示すべきです。	一度に提示するのは、実行中のステップ1つだけです。キュー全体はセッション成果物で確認できます。	単一アクティブステップ
2	ステップが明白に思える場合、エージェントは証拠なしで解決済みにできます。	すべての解決には、そのステップの検証方法に合致する証拠が必要です。	証拠によるゲート
3	会話のコンテキストが短ければ、セッションフォルダーは省略できます。	常にタイムスタンプ付きのセッションフォルダーを初期化し、そこに状態を保存してください。引き継ぎ時のコンテキスト喪失を防げます。	永続化
4	選択可能なオプションは単なる丁寧な提案なので、省略できます。	実行中の各ステップのパケットには、AUTOMATION_OPTIONS、HELP_OPTIONS、CONTROL_OPTIONSを必ず含めてください。	選択可能なオプション
5	ユーザーがステップの完了を伝えたら、エージェントはすぐに次へ進むべきです。	次へ進む前に、リポジトリの状態、コマンド出力、または明示的な証明を使って、解決済みか再確認してください。	進む前に検証
6	すべてのステップは自動化できます。	人間にしか実行できない作業（手動レビュー、判断、確認）が必要なステップもあります。	人間のみが実行できるステップ
7	ステップキューは固定です。	依存関係が変わった場合や、ステップを分割した場合は、キューを再正規化してください。	動的なキュー
8	事前チェックは省略できます。	ユーザーに指示を出す前に、必ず事前検証を実行してください。	事前検証

クイック判断ガイド

シナリオ	このスキルを使用	代わりに使用
実行前に複数の選択肢から選ぶ	いいえ	decisions/SKILL.md
完全に自動化可能なバッチを実行する	いいえ	エージェントによる直接実行
手動での展開やセットアップのチェックリストを案内する	はい	--
完了した学習の検証リストを再開する	はい	学習そのものにはstudy/SKILL.md
外部のタスクトラッカーでチェックリスト項目を追跡する	はい	ローカルに完了メモを残し、簡潔な引き継ぎ要約を返す
案内が必要な手動ステップを含む計画を立てる	はい	計画そのものにはplan/SKILL.md

ステップ品質チェックリスト

アクティブなステップを提示する前に、このチェックリストを使用してください。各項目はゲートです。必要な項目がすべて満たされるまで、そのステップは準備完了ではありません。

#	チェック項目	重要な理由	ゲート
1	キューの正規化 — STEP_ID とステータスを含む順序付きステップキュー	単一のアクティブステップを可能にします	ステップ前
2	セッションフォルダーの初期化 — .tmp/step-by-step/ 内のタイムスタンプ付きフォルダー	永続化を可能にします	ステップ前
3	次のステップの特定 — 未解決のステップのうち、最も優先度が高いもの	ステップのスキップを防ぎます	ステップ前
4	事前確認の実施 — エージェントが検証できる確認を完了	ユーザーの負担を軽減します	ステップ前
5	担当者の分離 — エージェントとユーザーのアクションを明確に区別	混乱を防ぎます	下書き
6	簡潔なタイトル — ステップのタイトルを明確な一文にする	素早く把握できるようにします	下書き
7	前提条件の列挙 — 依存関係を明示	順序どおりに進められるようにします	下書き
8	検証方法の明示 — 解決に必要な正確な証拠	検証を可能にします	下書き
9	選択可能なオプションの提示 — AUTOMATION／HELP／CONTROL オプションを含める	ユーザーが主導権を持てるようにします	下書き
10	解決基準の明確化 — 「完了」とみなす条件を明示	再オープンを防ぎます	クローズ処理
11	永続化の維持 — 変更のたびに状態を保存	再開を可能にします	クローズ処理
12	引き継ぎの準備 — スキル間の移行に必要な出力を準備	連携を可能にします	クローズ処理

品質レベル

レベル	基準	使用する場面
最小限	項目 1～3、6、10	シンプルな単一ステップのタスク
標準	項目 1～8、10～11	人による作業を含む複数ステップのワークフロー
完全	12 項目すべて	スキル間の連携を伴う複雑な展開

ステップ前の検証

アクティブなステップを提示する前に、次の項目を確認してください。

□ Step queue normalized with STEP_IDs and positions
□ Session folder initialized in .tmp/step-by-step/
□ Next unresolved step identified
□ Preflight checks completed (agent-verifiable items)
□ Agent vs user actions separated
□ Title is concise (< 60 chars)
□ Prerequisites listed with dependencies
□ Verification method stated with exact evidence
□ Chooseable options included (AUTOMATION/HELP/CONTROL)
□ Resolution criteria clear
□ State will be persisted after this step

ステップ整合性バリデーター

ステップを提示する前に、次の整合性チェックを実行してください。チェックに一つでも失敗したステップは、提示する前に修正する必要があります。

整合性チェックマトリックス

チェック	確認する内容	修正方法
ステップと前提条件	このステップの前に前提条件が解決されている	キューを並べ替える
ステップと検証	検証方法で完了を実際に証明できる	方法を具体化する
ステップとオプション	オプションがこのステップのアクションに関連している	オプションを更新する
ステップと引き継ぎ	スキルを移行する場合、引き継ぎ用の出力が準備できている	出力を準備する
キューと依存関係	依存関係が実際の前提条件の連鎖と一致している	正規化し直す

危険信号（提示禁止）

次のいずれかに該当するステップは、提示する前に修正する必要があります。

• 検証方法がないステップ
• 解決できない前提条件があるステップ
• 選択可能なオプションがないステップ
• セッションフォルダーが初期化されていない
• エージェントのアクションをユーザーのみが実行できるものとして提示している
• ユーザーのアクションをエージェントのみが実行できるものとして提示している

必須ポリシー

1. 最初のアクティブなステップを提示する前に、すべてのタスクを明示的な順序付きステップキューに正規化します。
2. 一度に提示するアクティブなステップは、必ず一つだけにします。
3. 各ステップの前に事前検証を実行します。エージェントが直接検証できることを、決してユーザーに任せないでください。
4. 各ステップのパケットで、エージェントが実行できる作業とユーザーのみが実行できるアクションを分けます。
5. すべてのアクティブステップのパケットは references/step-presentation-contract.md に従い、選択可能な自動化、ヘルプ、制御のオプションを、表示されるトークンと、利用可能な場合はハーネスの「ユーザーに質問」ピッカー（chooseable-options/references/ask-user-harness.md）の両方で提示する必要があります。
6. 検証方法を満たす証拠が得られるまで、ステップを解決済みとしてマークしないでください。証拠が不完全な場合は、何が不足しているかを明確に示し、ステップをアクティブなままにします。
7. 最初のステップの前にタイムスタンプ付きのセッションフォルダーを初期化し、ステータスを変更するたびに状態を永続化します。すべてのステップが解決、延期、またはブロックされるまで、キューを保持します。

セッションの永続化

ガイド付きの実行ごとに、gitignore 対象のセッションフォルダーを .tmp/step-by-step/YYYY-MM-DD-HHmmss-<session-slug>/ の下に作成します。タスクのタイトルまたはチェックリストの件名から、短いスラッグを作成してください。成果物は references/session-artifact-contract.md に従って保存します。

永続化が必須の最低限の出力：正規化されたキューのスナップショット、各ステップの現在のステータス、アクティブステップのパケット、解決を示す証拠の要約、最終的なセッションの要約。

ステップキューの正規化

次の優先順位で、利用可能な最善の情報源からステップキューを正規化します。

1. ユーザーが明示したチェックリスト。
2. アクティブな .plans/... のチェックリストまたは実行セクション。
3. アクティブな調査の展開または検証リスト。
4. アクティブな外部タスクトラッカーのチェックリストまたは手動フォローアップのセクション。
5. 現在の会話から作成する、セッション専用の代替リスト。

各ステップを次の項目で正規化します。

• STEP_ID
• キュー内の位置
• 人が読みやすいタイトル
• 担当者（user、agent、または shared）
• 前提条件
• 検証方法
• 完了を示す許容可能な証拠
• エージェントが提案できる自動化
• 現在のステータス（pending、active、resolved、deferred、blocked）

元の成果物に順序がすでに含まれている場合は、依存関係の衝突によって並べ替えが必要になる場合を除き、その順序を維持します。並べ替える場合は、続行する前に理由を説明してください。

1 ステップずつの対話ループ

1. 順序付けされたステップキューを作成するか、既存のキューを取り込みます。
2. タイムスタンプ付きの .tmp/ セッションフォルダーを初期化し、最初のキューのスナップショットを永続化します。
3. 次に未解決のステップを特定します。
4. ユーザーにプロンプトを表示する前に、事前確認を実行し、ローカルの証拠を収集します。
5. references/step-presentation-contract.md を使用して、アクティブステップのパケットを提示します。その契約で指定されている場合に限り、STEP_<ID>_AUTOMATE_IMPROVE_INSTRUMENTATION を含めます。
6. アクティブステップのパケットと現在のセッション状態を永続化します。
7. ユーザーが自動化オプションを選択した場合、安全なエージェント側の作業を先に実行します。
8. ユーザーからの証拠、確認、または追加の質問を待ちます。
9. リポジトリの状態、コマンド出力、スクリーンショット、ログ、またはユーザーが明示した証明を使って、解決を再確認します。
10. 更新したステータスをセッションフォルダーに永続化し、アクティブなプラン、調査、またはタスクの成果物がある場合は、そこにも反映します。
11. 次に未解決のステップへすぐに進むか、未解決のままであれば同じステップにとどまります。
12. キューが完了した場合、または先へ進めない場合は、完了またはブロック状態を簡潔にまとめて終了します。

受け付ける応答モード

ユーザーが次のいずれかを行った場合、現在のステップをアクティブなままにします。

• オプショントークンを選択する。
• 説明を求める。
• 追加の自動化を依頼する。
• 証拠やコマンド出力を貼り付ける。
• ステップが完了したと伝える。
• ステップがブロックされていると伝える。
• ステップをより小さなサブステップに分割するよう依頼する。

ネイティブのピッカー選択、自然言語での返信、明示的なセレクタートークンを受け付けます。ユーザーの返信が曖昧な場合は先へ進まず、アクティブなステップを再提示して、不明な点のみを確認します。

トラブルシューティング

症状	考えられる原因	対処方法
ユーザーがキューに圧倒されている	表示されているステップが多すぎる、またはタイトルが分かりにくい	タイトルを短くし、依存関係に基づく順序を厳格化して、再度正規化します。
ステップが何度も未完了に戻される	検証方法が曖昧すぎる、または証拠が不十分	Resolution Check で具体的な証拠を指定するように、検証方法を改善します。
セッション状態が失われたように見える	ステータス変更後に状態が永続化されていない	.tmp/step-by-step/ で最新のセッションフォルダーを確認し、session-state.json と queue.json を照合します。
ユーザーがブロック中のステップをスキップしたい	そのステップが残りのキューをブロックしている	ステップを blocked にし、後続のステップへの影響を説明して、キューを維持します。
スキル間の引き継ぎでステップのコンテキストが失われる	セッションディレクトリのパスが引き継がれていない	引き継ぎの出力には必ず、セッションディレクトリのパス、currentStepId、queue.json を含めます。

よくある落とし穴

1. セッションフォルダーの初期化を忘れる。 最初のアクティブなステップを提示する前に、必ずタイムスタンプ付きフォルダーを作成してください。references/session-artifact-contract.md を参照してください。
2. エージェント専用のアクションとユーザー専用のアクションを混在させる。 エージェントが実行できることと、ユーザーが実行する必要があることを分けてください。ユーザーのアクションは What You Need To Do に、エージェントのアクションは What I Can Do For You に記載してください。
3. 曖昧な返答を受けて先に進む。 ユーザーの返答が不明確な場合は、推測するのではなく、アクティブなステップを再提示して確認を求めてください。
4. ステータス変更後の永続化を省略する。 キューの正規化後、アクティブなステップの各パケットの後、エビデンスが変更されるたび、スキルを引き継ぐ前に、状態を永続化してください。
5. サブステップをトップレベルのステップとして提示する。 ステップを分割する場合は、新しいサブステップで正規化済みキューを更新し、その場しのぎで提示せずに番号を振り直してください。
6. 前提条件の概要を省略する。 すべてのステップパケットに前提条件の概要を含め、ユーザーが依存関係を理解できるようにしてください。

スキル間の連携

• plan/SKILL.md — 計画に手動実行、セットアップ、または検証のステップが含まれており、一括で提示するのではなく対話形式で進める必要がある場合に使用します。
• study/SKILL.md — 完了した調査から、ロールアウト、再現、または検証のチェックリストを引き継ぐ場合に使用します。
• decisions/SKILL.md — 選択肢から決定する場合は decisions を使用します。方針が決まり、ユーザーが対話形式の実行を必要とする場合は、ここに戻ります。
• chooseable-options/SKILL.md — ステップの選択肢について、トークンを表示し、ネイティブの Ask User 形式で提示する役割を担います。
• research-online/SKILL.md — 現在のステップを解決する前に、最新の外部ドキュメントや製品の動作を確認する必要がある場合に使用します。
• instrumentation/SKILL.md — references/step-presentation-contract.md に記載されている場合にのみ、STEP_<ID>_AUTOMATE_IMPROVE_INSTRUMENTATION を提案します。これを選んでも、ステップは解決されません。

引き継ぎ時の出力

上流のワークフロースキルへ

• ステータスを含む正規化済みキュー。
• 現在のアクティブな STEP_ID。
• 解決済みのステップで収集したエビデンス。
• 解決されていないアクティブなステップのブロッカー概要。
• ステップごとのセッションディレクトリのパス。
• 推奨する次のステップ、または明示的なブロック状態。

plan/SKILL.md へ

• 計画から抽出した手動ステップのキュー。
• 完了済みと残りのステップ。
• 対話型ループ中に得られた検証エビデンス。
• ブロッカーまたはフォローアップとして計画に再追加すべきステップ。

instrumentation/SKILL.md へ

オペレーターが STEP_<ID>_AUTOMATE_IMPROVE_INSTRUMENTATION を選択した後に限ります。

• STEP_ID
• セッションディレクトリ
• ステップで検証する動作
• 実行によって答えを出す必要がある問い

エビデンスが返されるまで、ステップはアクティブなままです。この引き継ぎによって、ステップが解決されることはありません。

明示的な依頼がある場合の下流タスク追跡へ

• トラッカーの URL／ID（記載されている場合）。
• セッション中に完了したチェックリスト項目。
• タスク本文に永続化する価値のあるエビデンスまたは出力スニペット。
• ステップごとのセッションディレクトリのパス。
• タスク追跡で可視状態を保つ必要がある、延期またはブロックされたステップ。

タスクの種類に応じた参照ファイルの読み込み

診断の依頼では、参照ファイルを読み込む前に、 .tmp/step-by-step/ 内の最新のセッションフォルダーを確認してください。

タスクの種類	読み込むファイル	読み飛ばすファイル
セッションのセットアップまたは再開	session-artifact-contract.md	step-presentation-contract.md
ステップパケットの提示または確認	step-presentation-contract.md	session-artifact-contract.md
永続化または再開の問題のデバッグ	session-artifact-contract.md	step-presentation-contract.md
ステップ構成または選択肢の調整	step-presentation-contract.md	session-artifact-contract.md

タスクに必要な範囲だけを読み込んでください。

ローカルコーパスのレイアウト

references/ フォルダーはフラット（サブフォルダーなし）で、2 つのファイルが含まれています。

ファイル	説明
session-artifact-contract.md	必須の .tmp/ セッションフォルダーのレイアウト、キューのスナップショットとステップ記録のファイル名、永続化のタイミング規則、再開規則。
step-presentation-contract.md	アクティブステップのパケットの正確な構造、必須の選択可能なオプショングループ、解決確認の規則。

ステップ生成テンプレート

アクティブステップを提示するときは、このテンプレートを使用します。各セクションに具体的な内容を入力してください。

アクティブステップのパケット構造

# Step: [STEP_ID] - [Concise title]
**Status:** active
**Quality Tier:** [Minimal | Standard | Full]
**Owner:** [user | agent | shared]
**Session:** [path to session folder]

## What This Step Does
[Brief description of what needs to happen]

## Prerequisites
- [ ] [Prerequisite step ID]: [What must be completed first]
- [ ] [Artifact path]: [Required artifact or context]

## What I Can Do For You
[Any agent-verifiable checks or automation]

## What You Need To Do
[Specific manual action with clear instructions]

## Verification Method
[How to verify this step is complete]
- Required evidence: [Specific output, screenshot, or confirmation]
- Agent will verify: [What the agent can check automatically]

## AUTOMATION_OPTIONS
- `STEP_[ID]_AUTOMATE_[ACTION]`: [Description of automation]

## HELP_OPTIONS
- `STEP_[ID]_HELP_[TOPIC]`: [Description of help topic]

## CONTROL_OPTIONS
- `STEP_[ID]_SKIP`: Skip this step
- `STEP_[ID]_DEFER`: Defer to later
- `STEP_[ID]_SPLIT`: Split into substeps

## Next Step
**Following:** [Next STEP_ID or "Queue exhausted"]

STEP_[ID]_AUTOMATE_IMPROVE_INSTRUMENTATION は、すべてのパケットに含まれるわけではありません。references/step-presentation-contract.md で検証がプロジェクトの動作として定められており、事前確認でコマンドもページも見つからなかった場合にのみ含めます。

ステップ正規化テンプレート

{
  "STEP_ID": "STEP_001",
  "title": "Concise step title",
  "owner": "user|agent|shared",
  "prerequisites": ["STEP_000"],
  "verificationMethod": "How to verify completion",
  "acceptableEvidence": ["output", "screenshot", "confirmation"],
  "status": "pending|active|resolved|deferred|blocked",
  "automations": ["what the agent can offer"],
  "options": {
    "automation": ["STEP_001_AUTOMATE_*"],
    "help": ["STEP_001_HELP_*"],
    "control": ["STEP_001_SKIP", "STEP_001_DEFER", "STEP_001_SPLIT"]
  }
}

クイックコマンド

# Initialize a step-by-step session
# Runner alternatives: bunx tsx / pnpm dlx tsx / deno run -A npm:tsx / node --import tsx / yarn dlx tsx
npx tsx .agents/skills/step-by-step/scripts/init-session.ts --name <session-name> --source <source-plan-or-study>

# Check step completeness (12-item checklist)
npx tsx .agents/skills/step-by-step/scripts/check-step-completeness.ts --step <step-id>
npx tsx .agents/skills/step-by-step/scripts/check-step-completeness.ts --session <session-dir>

# Normalize a step queue from an artifact
npx tsx .agents/skills/step-by-step/scripts/normalize-queue.ts --source <artifact-path>

# Verify step resolution
npx tsx .agents/skills/step-by-step/scripts/verify-step.ts --step <step-id> --evidence <evidence-path>

同梱アセット

ファイル	説明
assets/icon-small.svg	IDE エージェント一覧用の小さいスキルアイコン。
assets/icon-large.png	IDE エージェント一覧用の大きいスキルアイコン。

ガイダンスの整合性：リポジトリのガイダンスを AGENTS.md に従って一貫して適用してください。このスキルファイルを更新した場合は、IDE に新しいバージョンをすぐに反映するため、npm run skills:sync を実行してください。