mcpField
A
agent-conventions

agent-conventions

github.com/wyattowalshエージェントワークフロー566 回インストール9 週間前に更新
リポジトリ

agent-conventions について

agent-conventionsは、AIエージェント定義の作成・変更に使うスキルです。命名、frontmatter、READMEの索引、検証の規則とスキャフォールド用コマンドを示します。

主な機能

  1. 01必須・任意のfrontmatter規則
  2. 02エージェントの命名と本文規則
  3. 03README索引の更新要件
  4. 04スキャフォールドと検証コマンド

活用シーン

  1. 01新しいエージェント定義の作成
  2. 02エージェントのメタデータと索引の確認
  3. 03既存のエージェント用システムプロンプトの変更

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/wyattowalsh/agents --skill agent-conventions

インストール後、Claude Code で/agent-conventionsを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

evals/
agent-creation-trigger.json
evals.json
readme-sync.json
references/
readme-template.md
scripts/
check.py
scaffold_agent.py
validate_agent.py
validate-agent-index.py
scripts/asset_toolkit/
__init__.py
_shared.py
common.py
package.py
validate_evals.py
validate_hooks.py
validate_skill.py

詳細

エージェントの規約

AI エージェントの定義を作成または変更する際は、以下の規約に従ってください。

ディスパッチ

$ARGUMENTSアクション
Active (エージェントファイルの作業時に自動的に呼び出されます)以下のすべての規約を適用します
Empty規約の概要を表示します
check検証チェックのみを実行します

参照

ファイル用途
references/readme-template.mdエージェントの README.md インデックス項目のテンプレート

スキャフォールディング

次のコマンドで、新しいエージェント定義を作成します。

python skills/agent-conventions/scripts/scaffold_agent.py <name>

規約

必須のフロントマター

すべてのエージェントファイルには、YAML フロントマターに以下のフィールドを含める必要があります。

  • name -- ケバブケースを使用し、.md を除いたファイル名と一致させます
  • description -- 空ではない値を指定し、エージェントの目的を説明します
任意のフロントマター
  • tools -- 使用を許可するツールのカンマ区切りリスト（デフォルト：すべて）
  • disallowedTools -- 使用を禁止するツールのカンマ区切りリスト
  • model -- sonnet | opus | haiku | inherit（デフォルト：inherit）
  • permissionMode -- default | acceptEdits | delegate | dontAsk | bypassPermissions | plan
  • maxTurns -- エージェントのターン数の上限を表す整数
  • skills -- エージェントのコンテキストに事前読み込みするスキルのリスト
  • mcpServers -- このエージェントが利用できる MCP サーバーのリスト
  • memory -- user | project | local
  • hooks -- このエージェントに適用されるライフサイクルフック

メモリフィールドの規約：

  • 最も限定的なメモリのスコープを選択します。一時的な知見には local、共有するパターンには project、プロジェクトをまたいで使う好みには user を使用します
  • メモリのエントリーポイントファイルは 200 行未満にしてください。これを超える内容は読み込み時に切り詰められます
  • メモリは時系列ではなく、トピック別（例：debugging.md、api-patterns.md）に整理します
  • MEMORY.md をインデックスファイルとして使用し、詳細なメモにはトピックごとに別のファイルを作成します
命名
  • すべてのエージェント名にケバブケースを使用します：^[a-z0-9][a-z0-9-]*$
  • .md を除いたファイル名は、フロントマターの name フィールドと完全に一致させる必要があります
  • ハイフンを連続させず、先頭や末尾にハイフンを付けないでください
README インデックスの要件

次のいずれかの場所で新しいエージェントを定義する場合は、必ず対応してください。

  • ~/.{gemini|copilot|codex|claude}/agents/
  • .claude/agents/（プロジェクトレベル）
  • プロジェクトローカルのエージェントディレクトリ

同じディレクトリにある対応する README.md インデックスを更新します。

  1. インデックステーブルに、エージェント名、説明、主要フィールドを含む行を追加します
  2. 使用方法の詳細を記載した説明セクションを追加します
  3. テーブルは名前のアルファベット順に並べます
本文の内容
  • システムプロンプトは命令形で書きます（「Check the logs」であり、「Checks the logs」ではありません）
  • エージェントの定義は、単一の責任に焦点を絞ります
  • スキルの内容をそのまま本文に含めず、スキル名を参照します

重要なルール

  1. エージェントを追加または変更する際は、必ず README.md インデックスを更新します
  2. すべてのエージェント名をケバブケースにし、ファイル名と完全に一致させます
  3. フロントマターには必須の name と description の両方を含めます
  4. エージェントの機能を重複させないでください。まず既存のエージェントを確認します
  5. 保守性を保つため、エージェントのシステムプロンプトは 500 行未満にします
  6. エージェントのフロントマターを変更した後は、python scripts/validate_agent.py --check-index を実行します
  7. エージェント本文全体で命令形を使用します

標準用語（以下の表記を厳守してください）：

  • agent -- agents/ ディレクトリにある AI エージェントの定義ファイル
  • frontmatter -- --- 区切り文字の間にある YAML メタデータ
  • system prompt -- フロントマターの後に続く Markdown 本文
  • index table -- すべてのエージェントを一覧表示する README.md 内の Markdown テーブル
  • kebab-case -- ハイフンで区切った小文字の単語

検証の要件

このスキルの変更を完了とする前に、次を実行します。

python skills/agent-conventions/scripts/check.py

完了基準：

  1. scripts/check.py が終了コード 0 で終了すること。
  2. エージェントのフロントマターの変更が scripts/validate_agent.py --check-index に合格すること。

コメント

Markdown 対応