emyann/create-an-agent

Nemiaでエージェントを作成する

エージェントは雇用人材です：仕事、基準（スキル）、および装備（ツール）を持つ人物です。ワークフローのステップは、エージェントが埋めるポジションです。1つのエージェントは複数のワークフローでポジションを埋めることができます。個人のファクトリーはNemiaからエージェントを取得しません：リポジトリのチームはそのworkflows/に、個人のチームは~/.agent-workflows/workflows/にあり、ボードのエージェントページは後者に書き込みます。完全なフォーマットについては、NemiaのREADME『エージェントはノードのアタッチメント』を読んでください。ここでは手順と、それを学ぶためにかかったコストを説明します。

エージェントの正体

• 名前はファイル名と同じ、agents/<name>.md、小文字の個人名（nora）、ステップはこれでエージェントを指定します（agent: nora）。ボードは名前を個人名（Nora）として、そこから生成された顔（Blobatar）とともに表示します。これはどこでも同じです。
• role: はエージェントが担う仕事を数語で表します（Product engineer）。description: はいつエージェントをアタッチするかを1行で示します。どちらもエージェント自身の行であり、harnessPrompt: も同様です：これを設定するステップは拒否されます。ステップの skills: はそのエージェントのスキルに追加されます（そのスキル）。
• mcp: はセッションがロードするMCPサーバーを、チェックアウトの.mcp.jsonが与える名前で指定します（mcp: playwright）。ステップの mcp: は、skills: と同様にエージェントのものに追加されます：1つのリポジトリだけが持つサーバーは、それを必要とするステップによって名前が指定されるため、エージェントは移植可能なままです。セッションは、そのエージェントとステップが指定するサーバーのみをロードし、それ以外はロードしません：どちらにも行がない場合は何もロードされず、チェックアウトが宣言していない名前はセッションの開始時に拒否されます。サーバーをロードしてもそのツールは許可されません：フェンスが依然として決定します。サーバーを指定するエージェントは試行できません。試行にはチェックアウトがないためです。
• name: 行はファイル名と等しくなければなりません。card: は廃止されました（カードはスキルから生成されます：npx wf agents card <name>）。

ファイル

フロントマター、その後に指示。他のキーは、セッションの実行方法 — harness、model、effort、context、remote、output、およびフェンス — を指定し、それを指定するステップは、自身で設定しない限りそれぞれを引き継ぎます。配線はステップのものであり、ここでは拒否されます：after、input、workspace、check、gate、loop、budget、background。

• フェンスはハーネスのブロックの下に配置します：claude: { fence: { permissionMode, tools, allowedTools, disallowedTools } }、または codex: { fence: { sandbox } }。ブロックには fence のみが保持され、ファイルのハーネス以外のハーネスのブロックは拒否されます。フェンスキーがトップレベルにある場合は以前のスペルであり、引き続き読み取られます。nemia frontmatter rewrite <folder> でブロック内に移動します。
• ステップがオーバーライドできるものを指定します：overridable: model, effort, fence, skills、各単語は OVERRIDABLE のいずれか（model、effort、context、harness、remote、output、fence、skills、mcp）。これ以外を設定するステップはロード時に拒否され、キーとエージェントが指定されます。行がない場合、ステップはすべてをオーバーライドでき、nemia start は行を追加するように指示します。

---
role: Code reviewer
harness: claude
model: opus
overridable: model, effort, fence
claude:
  fence:
    permissionMode: dontAsk
    tools: Read, Grep, Glob, Bash
    allowedTools: Bash(git log:*), Bash(git diff:*)
---

• フロントマターはYAMLであり、ステップやスキルのものと同様に、すべての値は書かれたテキストとして読み取られます。: や # を含む値、またはYAML記号（[、{、*、&、!、|、>、-、?）で始まる値は引用符で囲みます（例：description: "Reviews a change: its correctness"）。長い値はリテラルブロック |- とその下の行にインデントして記述します。リストキーは Read, Grep または [Read, Grep] を取ります。ボードは最初の形式を書き込みます。
• effort: と context:（200k）を指定します：ジョブはユーザー設定を読み取らず、バインドされていないセッションは呼び出しごとに最大100万トークンを読み取ります。
• auto は、それを削除することが測定されたモデル（haiku、claude-sonnet-4-5）でロード時に拒否されます。ルールとともに dontAsk を指定してください。

その指示

ボディはその指示であり、Claude Code自身のプロンプトに追加されます（harnessPrompt: keep。no-coding はハーネスのコーディングセクションを削除し、replace は指示をその場所に配置します）。指示は汎用的かつ簡潔に保ちます：それが誰であるか、何に対して責任があるか、決してしないこと、ターンを終了する方法、クローズアウトに何が含まれるか。手順はスキルに属し、機械が保持するルール（フェンス、ゲート）には文は必要ありません。再開されたセッションは開始時のボディを保持します：編集は次の実行に反映され、進行中の実行には決して反映されません。

5つのレイヤー

指示は、タスクとは別にエージェントを形成する5つのレイヤーの1つであり、それぞれはそれを所有する者が記述します：

1. 指示 — エージェントのボディ：それが誰であるか、どこに雇われていても。
2. カスタム指示 — 人がエージェントを書き換えずに使用するために追加するもので、ストアに保持され、エージェント名ごとに1ファイル（wf agents custom <name>）、エージェントのフォルダーには決してありません。単語のみ：キーを設定しないため、フェンスを広げたりツールを与えたりすることはありません。実行は開始時にカスタム指示を固定するため、編集はその後の実行にのみ影響します。
3. フォルダーのファイル — ハーネスがエージェントの作業フォルダーから読み取るファイル（現在は CLAUDE.md、AGENTS.md）：そこで作業するすべてのエージェントに対して保持されるもの。Nemiaはそれらを何も構成しません。それらはエージェント自身の指示よりも上位にランクされ、ファクトリーのルールとステップのポリシーよりも下位にランクされます。ただし、ハーネスはそれらをすべてをオーバーライドするものとして提示します：そのフレーミングはハーネスのものです。
4. ファクトリーのルール — 1つのファクトリーのルールとポリシーで、そこに雇われるすべてのエージェントに伝えられます：ファクトリーごとに1ファイル、ストアに保持され（nemia factory rules <name>）、リポジトリには決してありません。単語のみで、カスタム指示と同様に実行開始時に固定されます。リモートエージェントのステップには通知されません。
5. ステップのポリシー — ステップ自身の単語とキー：このプロセスのこのポジションがロールに要求すること。通常のレイヤーであり、回避策ではありません：そこで1つのワークフローが期待することを述べ、指示には含めないでください。ステップはスキルを追加できますが、削除することはできません。

番号は優先順位です：2つのレイヤーが異なることを述べている場合、番号が大きい方が優先され、タスクはそれらすべてよりも上位です。単語が到着する順序は別のものです — 指示、カスタム指示、ファクトリーのルール、ステップのポリシー、次にタスク、エージェントが作業する場所のフォルダーのファイルはハーネスによって読み取られます。新しい指示がどのレイヤーに属するかは、Nemia自身のルーティングルール『新しい指示の行き先』であり、出荷された『5つのレイヤー』の節で一度述べられています：推測するよりも質問してください。フェンスは厳しくなるだけです：ステップはエージェントのフェンスを狭めることはできますが、広げることはできません。ステップの disallowedTools: はエージェントのものに追加され、ローダーはエージェントのファイルが持っていないものに対してステップの tools:、allowedTools:、permissionMode:、または sandbox: を拒否します。したがって、指示はロールがどこでも保持することを述べ、1つのワークフローや1つのワークスペースについては何も述べません。

そのクローズアウト

output: <name>.schema.json、エージェントの横にあるJSON Schema：ステップが引き渡すものを厳密にデコードします。ハウススタイル：すべてのフィールドは described、required、additionalProperties: false。

• 予約済み： outcome、summary、artifacts、needs はすべてのクローズアウトで実行自身のものです。ローダーはこれらを宣言するスキーマを拒否します。（Irisの意図はそのため proposedOutcome を使用します。）
• セッションの試行全体でスキーマを同じに保ちます：変更されたスキーマを与えられた継続セッションは、プロンプトキャッシュ全体を再構築します。
• ステップは、それが待機する任意のステップから input: <step> でクローズアウトを読み取ります。その間のステップも含みます。ループするステップ（loop:）は1つのステップのみを待機できるため、そのようにしてループの前に来たものを読み取ります（レビューステップは仕様をそのように読み取ります）。

そのスキル

skills: <a>, <b> は SKILL.md を保持するフォルダーを指定し、エージェントフォルダーの横の skills/、次にリポジトリの .claude/skills/、次にストア、最後にNemia自身のスキルで検索されます。tools: は Skill を許可する必要があります。リポジトリの .claude/skills/ は、リポジトリがステップの場所である場合にのみ見つかります：開始時に与えられるためです。フォルダーをロードするテストも場所を渡します。エージェントを持つステップは、自身の skills: でスキルを追加できます：セッションはエージェントのもの、次にステップのものを、それぞれ1回ずつ取得します。エージェントのフェンスはすでにそれらをロードしている必要があります。ステップがそれを広げることは決してありません。

• スキルを作成するには、スキル作成者の方法を使用します：いつ使用するかを示す description:、短いボディ、その横のファイルに詳細を記述します。
• 誰かのスキルをそのまま使用する：スクラッチプロジェクトで、DO_NOT_TRACK=1 npx skills add <owner>/<repo> --skill <name> --agent claude-code --copy -y。フォルダーを .claude/skills/ にコピーし、skills-lock.json にエントリをマージし、作成者、ソース、ライセンスを THIRD_PARTY_NOTICES.md に追加します（MITはすべてのコピーに通知を要求します）。決して編集しないでください — ロックがそれを固定します — そしてエージェントのボディで適応させてください。モデルが呼び出す可能性のあるスキルをベンダリングしてください：disable-model-invocation: true と指定するものは、個人のスラッシュコマンドです（grill-me は grilling のみを呼び出します）。

そのフェンス

• 何も書き込まないロールは dontAsk で実行されます。 ワークスペース内での読み取りのみ、読み取り専用コマンド、および許可ルールが指定するもののみが実行され、それ以外は尋ねずに拒否されます。リポジトリの設定は、他のロールがワークスペースに書き込むために必要なコマンド（ビルドなど）を許可する場合があるため、Bash を与えられたエージェントは disallowedTools: でそれぞれを名前で拒否します。サブエージェントはモードとルールを継承します。allowedTools: に Agent をリストして、ディスパッチ自体が拒否されないようにします。設定が許可しないチェックをロールが実行する場合、それぞれを正確な名前で許可します。そのスキルはそれぞれを裸で綴り、呼び出しごとに1つとします（ラップ、パイプ、リダイレクト、または cd、git -C、VAR=、for の後ろにあるものは拒否されます）。読み取りや検索はBashではなくRead、Grep、Globに送信します。
• 編集するロールは auto で実行され、決して実行してはならないものを名前で拒否します：Bash(git push)、Bash(git push:*)、Bash(git branch -D:*)、Bash(git branch --delete --force:*)、Bash(pkill:*)、Bash(killall:*)、mcp__playwright__browser_run_code_unsafe。
• ステップはフェンスを厳しくするだけであり、overridable: が fence を指定する場合に限ります。エージェントのファイルが与えていないツール、許可、モードを必要とするステップは、別のエージェントを必要とします。ステップの disallowedTools: はエージェントのものに追加されます：ステップが追加する拒否のみを記述します。エージェントの拒否を取り除くことは決してできません。

人間との会話

ステップはエージェントSDK上のジョブです：会話内で待機することはできません。質問するには、blocked で質問とともにサインオフします。人間はボード上で、または wf retry <run> <step> --message "…" で回答し、同じセッションが回答を次のターンとして続行します。面談を行うエージェントのボディにその旨を記述し、人間がクローズアウトを受け入れなければならないステップをゲートします（gate: true）。ジョブの最後のターンはサインオフです：長時間実行コマンド（e2eなど）を実行するエージェントは、コマンドをフォアグラウンドで実行するか、コマンドを待機するように指示され、実行中のコマンドでサインオフしてはなりません（あるエンジニアの最初のウェブビルドは、e2eが終了する前にサインオフしました）。blocked でサインオフされたクローズアウトはそれ自体で読み取られるため、ラウンドで質問するエージェントは、これまでに決定されたすべてを各ラウンドに保持します：面談者の3回目のラウンドは、以前の決定を一度失いました。質問を出力スキーマのフィールドとして宣言します：{ "x-shape": "questions", "description": "…" }。ローダーはこれを1つの厳密な形状に展開します：ボードはそれらを人間がクリックして回答する選択肢として描画します。自身の後のステップのコストを知っているゲートされたステップは、{ "x-shape": "budgets", "description": "…" } をそれらの横に宣言します：{ step, usd, why } のリスト。各ステップはゲートの後、1回、0より大きいドル単位で、why はその金額の根拠です。ゲートはそれらをクローズアウトの横に表示し、承認するとそれらをそれらのステップの上限にします。人間が変更した金額も含みます（nemia approve <run> <step> --budget <step>=<amount>）。ステップ自身の budget: を超える上限はそこに示され、尋ねられずに承認されることは決してありません。別のステップや金額なしを指定するクローズアウトは、そのセッションに拒否されて戻されます。

確認する

1. リポジトリから npx wf agents card <name>：実際のローダーがファイル — そのキー、スキーマの予約名、見つかった各スキル — を読み取り、カードを印刷するか、修正を指定する言葉で拒否します。
2. リポジトリ自身のチェック。ガードが出荷するすべてのフォルダー（フェンス、固定されたステップ、レンダリングのラウンドトリップ）を読み取ります：ワークフローフォルダーを認識しないキャッシュをバイパスして実行します。
3. 実行する：それを指定するゲートされたワークフローを、小さな実際のカードで実行し、承認前にクローズアウトを読み取ります。
4. リポジトリがエージェントをリストする場所に新しいエージェントを指定します。

何かを学んだとき

エージェントの作成は、このスキルがテストされる方法です。ここでのステップが間違っていたり欠けていたりする場合 — 遭遇した拒否、驚かされたキー — このファイルをエージェントと同じ変更で、ルールを保持するファイルとともに、最大3行で修正します。