agent-sop-author

Agent SOP Author

概要

Agent SOP（標準作業手順書）は、自然言語、パラメーター化された入力、制約ベースの実行を用いて、AI エージェントを高度なワークフローに沿って導く Markdown 形式の指示セットです。このスキルでは、さまざまな AI システムで機能する Agent SOP の作成（または更新）、構成、検証方法を説明します。

使用方法

Agent SOP を扱う際、次の作業が必要な場合：

• 新しいワークフロー自動化 SOP を作成する
• 既存のワークフロー自動化 SOP を更新する
• 複数のステップからなるエージェントのワークフローを構成する
• RFC 2119 の制約（MUST、SHOULD、MAY）を適用する
• SOP の形式と構造を検証する
• ワークフローを再利用可能なテンプレートに変換する
• SOP がさまざまな AI システム（Claude、Kiro、Cursor など）で機能するようにする

主な概念

Agent SOP とは

Agent SOP は、次の内容を定義する標準化された Markdown ファイル（.sop.md）です。

• 詳細な概要を含む明確な目標
• 柔軟に再利用できるパラメーター化された入力
• RFC 2119 の制約を含むステップごとの指示
• 確実な実行のための例とトラブルシューティング
• マルチモーダルな配布（MCP ツール、Agent Skills、Python モジュール）

主な機能

RFC 2119 の制約：標準化されたキーワード（MUST、SHOULD、MAY）を使用して、固定的なスクリプトを使わずにエージェントの動作を正確に制御します。

パラメーター化：さまざまなプロジェクト、チーム、要件に合わせて動作をカスタマイズするパラメーターを受け付けます。

再開可能性：エージェントの作業中に進捗を記録することで、中断された場合でも状況を把握して簡単に再開できます。

Agent SOP の作成

ファイルの場所

現在の作業ディレクトリに agent-sops/ ディレクトリがあるかMUST確認してください。

• agent-sops/ が存在する場合は、そこに SOP ファイルをMUST書き込んでください
• agent-sops/ が存在しない場合は、現在のディレクトリに SOP を書き込むか、保存先をユーザーに尋ねることがMAYできます

ファイル名

次の命名規則にMUST従ってください。

• .sop.md の拡張子を使用する
• ファイル名にはケバブケースを使用する（例：code-assist.sop.md、idea-honing.sop.md）
• SOP の目的が分かる説明的な名前を選ぶ

検証

変更を行うたびに、MUST validate-sop.sh を実行してください。

検証スクリプトは、この SKILL.md ファイルと同じディレクトリにあります。このスキルを読むと SKILL.md の完全なパスが分かり、検証スクリプトが同じディレクトリにあることも確認できます。

<skill-directory>/validate-sop.sh path/to/your-sop.sop.md

先に進む前に、すべてのエラー（❌）をMUST修正してください。警告（⚠️）には可能な限り対処することがSHOULDです。

必須の構造

すべての Agent SOP には、次のセクションを順番どおりに含めることがMUSTです。

# [SOP Name]

## Overview
[Concise description of what the SOP does and when to use it]

## Parameters

- **required_param** (required): Description
- **optional_param** (optional, default: "value"): Description

**Constraints for parameter acquisition:**
- If all required parameters are already provided, You MUST proceed to the Steps
- If any required parameters are missing, You MUST ask for them before proceeding
- When asking for parameters, You MUST request all parameters in a single prompt
- When asking for parameters, You MUST use the exact parameter names as defined

## Steps
### 1. [Step Name]
Description of what happens in this step.

**Constraints:**
- You MUST [specific requirement]
- You SHOULD [recommended behavior]
- You MAY [optional behavior]

## Examples
[Concrete usage examples]

## Troubleshooting
[Common issues and solutions]

Parameters セクション

次の形式でパラメーターを定義することがMUSTです。

## Parameters

- **parameter_name** (required): Description of required input
- **another_param** (required): Description
- **optional_param** (optional): Description of optional input
- **with_default** (optional, default: "default_value"): Description

**Constraints for parameter acquisition:**
- If all required parameters are already provided, You MUST proceed to the Steps
- If any required parameters are missing, You MUST ask for them before proceeding
- When asking for parameters, You MUST request all parameters in a single prompt
- When asking for parameters, You MUST use the exact parameter names as defined

パラメーターの命名規則：

• 小文字を使用することがMUSTです
• スペースの代わりにアンダースコアを使用することがMUSTです（snake_case）
• 目的が分かる説明的な名前を使用することがMUSTです
• 必須パラメーターを任意パラメーターより先に記載することがMUSTです

パラメーター取得の制約セクション：

• すべての Parameters セクションにこのセクションを含めることがMUSTです
• 次の指示を含めることがMUSTです。
  • 「必須パラメーターがすべてすでに指定されている場合は、Steps に進むことが MUST です」
  • 「必須パラメーターが不足している場合は、先に進む前にそれらを尋ねることが MUST です」
  • 「パラメーターを尋ねる際は、すべてのパラメーターを 1 つのプロンプトで要求することが MUST です」
  • 「パラメーターを尋ねる際は、定義されたパラメーター名を正確に使用することが MUST です」
• 柔軟な入力方法に関する追加の制約を加えることがMAYできます。

**Constraints for parameter acquisition:**
- If all required parameters are already provided, You MUST proceed to the Steps
- If any required parameters are missing, You MUST ask for them before proceeding
- When asking for parameters, You MUST request all parameters in a single prompt
- When asking for parameters, You MUST use the exact parameter names as defined
- You MUST support multiple input methods including:
  - Direct input: Text provided directly
  - File path: Path to a local file
  - URL: Link to an internal resource
- You MUST use appropriate tools to access content
- You MUST confirm successful acquisition before proceeding
- You SHOULD save acquired data to a consistent location

Steps セクション

ステップは次のようにMUST構成してください。

1. 番号付き見出し（### 1.、### 2. など）
2. ステップ名
3. 自然言語による説明
4. RFC 2119 のキーワードを含む**Constraints:**セクション

例：

### 1. Setup
Initialize the project environment and create necessary structures.

**Constraints:**
- You MUST validate directory structure exists
- You MUST create missing directories
- You MUST NOT proceed if directory creation fails
- You SHOULD log all setup actions
- You MAY skip validation if --force flag is provided

条件分岐の場合：

### 3. Conditional Processing
If validation passes, proceed with processing. Otherwise, report errors.

**Constraints:**
- You MUST check validation status before proceeding
- If validation passes, You MUST process the data
- If validation fails, You MUST report specific errors
- You MUST NOT continue with invalid data

RFC 2119 キーワード

RFC 2119 で定義されている以下のキーワードを必ず使用してください。

• MUST / REQUIRED：絶対的な要件
• MUST NOT / SHALL NOT：絶対的な禁止事項
• SHOULD / RECOMMENDED：強く推奨される事項（無視しても妥当な理由がある場合があります）
• SHOULD NOT / NOT RECOMMENDED：強く推奨されない事項（受け入れても妥当な理由がある場合があります）
• MAY / OPTIONAL：真に任意の項目

否定的な制約

否定的な制約を使用する場合は、必ずその背景を説明してください。

良い例（背景あり）：

- You MUST NOT use ellipses (...) because your output will be read aloud by text-to-speech
- You SHOULD NEVER delete Git history files since this could corrupt the repository
- You MUST NOT run `git push` because this could publish unreviewed code

悪い例（背景なし）：

- You MUST NOT use ellipses
- You SHOULD NEVER delete Git files
- You MUST NOT run git push

否定的な制約でよく使用される背景：

• 技術的な制限：「システムで処理できないため……」
• セキュリティリスク：「機密データが漏えいする可能性があるため……」
• データの整合性：「重要な情報が破損する可能性があるため……」
• ユーザーエクスペリエンス：「ユーザーが混乱するため……」
• 互換性：「統合が機能しなくなるため……」
• パフォーマンス：「大幅な速度低下を引き起こす可能性があるため……」

例のセクション

以下を示す具体例を含めることを推奨します。

• 入力パラメーターの例
• 期待される出力または動作
• よくある使用パターン

## Examples

### Example 1: Basic Usage
**Input:**
- task_description: "Create user authentication system"
- mode: "interactive"

**Expected Behavior:**
Agent will guide through TDD workflow, creating tests first, then implementation.

### Example 2: Automated Mode
**Input:**
- task_description: "Fix bug in payment processing"
- mode: "auto"

**Expected Behavior:**
Agent will automatically implement fix following established patterns.

トラブルシューティングのセクション

よくある問題と解決策を含めることを推奨します。

## Troubleshooting

### Parameter Validation Fails
If parameter validation fails, check that:
- All required parameters are provided
- Parameter names use snake_case
- Values match expected types

### Step Execution Hangs
If a step appears to hang:
- Check for missing tool permissions
- Verify file paths are accessible
- Review constraint requirements

対話型 SOP

ユーザーとのやり取りが必要な SOP では、次のようにします。

1. ユーザーとのやり取りが必要なタイミングを明確に示すことを推奨します
2. ユーザーの応答をどのように処理するかを必ず指定してください
3. やり取りの記録をどこに保存するかを指定することを推奨します

例：

### 2. Requirements Clarification
Guide the user through questions to refine their initial idea.

**Constraints:**
- You MUST ask one question at a time
- You MUST append each Q&A to "idea-honing.md"
- You SHOULD adapt follow-up questions based on previous answers
- You MUST continue until sufficient detail is gathered

ベストプラクティス

SOP を作成する際は、以下のプラクティスに従うことを推奨します。

1. 各ステップの目的を絞る：各ステップでは、明確な目標を1つ達成するようにします
2. 制約を明確にする：要件と推奨事項を具体的に区別します
3. 例を示す：複雑なワークフローでは、具体的な使用例を示します
4. 自然な言葉を使う：理解しやすい説明を記述します
5. 複雑さを最小限にする：深くネストした条件分岐ロジックは避けます
6. 成果物を明記する：作成するすべての成果物について、ファイルパスを記載します
7. 十分にテストする：さまざまな AI システムで SOP が機能することを検証します
8. エッジケースを文書化する：よくある問題のトラブルシューティングを含めます

クイックリファレンス

要素	形式	必須
ファイル拡張子	.sop.md	はい
タイトル	# SOP Name	はい
概要	## Overview	はい
パラメーター	## Parameters	はい
手順	## Steps と ### N.	はい
制約	RFC 2119 に基づく **Constraints:**	はい
例	## Examples	推奨
トラブルシューティング	## Troubleshooting	推奨

よくあるパターン

変更前：構造化されていないプロンプト

Please implement a user authentication system using TDD.
Make sure to write tests first and follow best practices.

変更後：構造化された SOP

# Code Assist

## Overview
This SOP guides implementation using test-driven development.

## Parameters
- **task_description** (required): Description of task
- **mode** (optional, default: "interactive"): "interactive" or "auto"

## Steps
### 1. Setup
Initialize project environment.

**Constraints:**
- You MUST validate directory structure
- You MUST create test directory if missing
- You MUST NOT proceed if setup fails

### 2. Test Creation
Create tests based on requirements.

**Constraints:**
- You MUST write tests before implementation
- You SHOULD follow existing test patterns
- You MAY add additional edge case tests

よくある間違い

否定的な制約の背景が不足している

問題： 理由を説明せずに MUST NOT を使用する。 修正： 常に背景を説明します：「Y のため、X を MUST NOT とする」

パラメーターの説明が曖昧

問題： 「input_data（必須）：データ」 修正： 「input_data（必須）：ユーザープロファイルのフィールド（名前、メールアドレス、役割）を含む JSON オブジェクト」

要件レベルの混同

問題： 任意の動作に MUST を使用したり、重要な要件に MAY を使用したりする。 修正： RFC 2119 のキーワードを正確に使います。絶対的な要件には MUST、推奨事項には SHOULD、任意の項目には MAY を使用します。

例が不足している

問題： 具体的な使用例がない複雑なワークフロー。 修正： 入力パラメーターと期待される動作を示す完全な例を少なくとも1つ含めます。

ステップが複雑すぎる

問題： ネストした条件分岐を含む1つのステップで、複数の目標を達成しようとしている。 修正： それぞれ明確な制約を持つ、目的を絞った複数のステップに分けます。

ワークフローの図

flowchart TD
    Start[Create SOP] --> Name[Choose descriptive name]
    Name --> Structure[Add required sections]
    Structure --> Overview[Write overview]
    Overview --> Params[Define parameters]
    Params --> Steps[Create steps with constraints]
    Steps --> Examples[Add examples]
    Examples --> Troubleshoot[Add troubleshooting]
    Troubleshoot --> Validate[Validate format]
    Validate --> Test[Test with AI agent]
    Test --> Done[Distribute SOP]

    style Start fill:#90EE90
    style Done fill:#90EE90
    style Validate fill:#FFB6C1

要点

エージェント SOP は、複雑なワークフローを、さまざまな AI システムで利用できる再利用・共有可能な指示に変換します。RFC 2119 の制約を取り入れた標準 Markdown 形式を使用し、エージェントの推論能力を保ちながら、正確に制御できます。

SOP を作成する際は、明確な構成、コンテキストを伴う具体的な制約、具体例に重点を置いてください。信頼性を確保するため、さまざまな AI システムで十分にテストしてください。