emyann/create-an-agent

Nemia에서 에이전트 생성하기

에이전트는 고용인(hire)입니다: 직업, 표준(스킬) 및 장비(도구)를 가진 사람입니다. 워크플로우의 단계(step)는 에이전트가 채우는 위치(position)이며, 하나의 에이전트는 여러 워크플로우에서 위치를 채울 수 있습니다. 사용자의 팩토리(factory)는 Nemia에서 에이전트를 가져오지 않습니다: 저장소의 팀은 workflows/에 있고, 사용자의 팀은 ~/.agent-workflows/workflows/에 있으며, 보드의 Agents 페이지는 후자를 작성합니다. 전체 형식은 Nemia의 README, An agent is a node's attachment를 참조하세요. 여기서는 절차와 배우는 데 필요한 내용을 설명합니다.

에이전트 identity

• 이름은 파일 이름과 동일합니다: agents/<name>.md이며, 사람의 이름을 소문자로 씁니다(nora). 단계는 이 이름으로 에이전트를 참조합니다(agent: nora). 보드는 이름을 사람 이름처럼(Nora) 표시하며, Blobatar로 생성된 얼굴과 함께 표시됩니다.
• **role:**은 에이전트가 맡는 직무를 몇 단어로 나타냅니다(Product engineer). **description:**은 언제 에이전트를 첨부할지 한 줄로 설명합니다. 두 속성 모두 에이전트 자체의 라인이며, harnessPrompt:와 함께 사용됩니다. 단계가 harnessPrompt:를 설정하면 거부됩니다. 단계의 skills:는 에이전트의 스킬에 추가됩니다(스킬 참조).
• **mcp:**는 세션이 로드할 MCP 서버의 이름을 나열합니다. 이름은 체크아웃의 .mcp.json에서 제공한 이름과 일치해야 합니다(mcp: playwright). 단계의 mcp:도 에이전트의 mcp:에 추가됩니다. 하나의 저장소만 가지고 있는 서버는 해당 서버가 필요한 단계에서 이름을 지정해야 에이전트가 이식 가능하게 유지됩니다. 세션은 에이전트와 단계에서 이름이 지정된 서버만 로드하며, 그 외는 로드하지 않습니다. 두 곳 모두에 라인이 없으면 서버를 로드하지 않으며, 체크아웃에서 선언되지 않은 이름은 세션 시작 시 거부됩니다. 서버를 로드해도 도구가 허용되는 것은 아닙니다. 펜스(fence)가 여전히 결정합니다. MCP 서버를 지정한 에이전트는 시험(try)할 수 없습니다. 시험에는 체크아웃이 없기 때문입니다.
• name: 라인은 파일 이름과 같아야 합니다. card:는 더 이상 사용되지 않습니다(카드는 스킬에서 생성됩니다: npx wf agents card <name>).

파일

프론트매터(Frontmatter) 다음에 지침(instructions)이 옵니다. 다른 키는 세션이 어떻게 실행되는지 결정합니다 — harness, model, effort, context, remote, output, 그리고 펜스(fence) — 에이전트를 참조하는 단계는 자체 값을 설정하지 않는 한 이를 상속받습니다. 배선(wiring)은 단계의 영역이며 여기서는 거부됩니다: after, input, workspace, check, gate, loop, budget, background.

• 펜스는 harness 블록 아래에 위치합니다: claude: { fence: { permissionMode, tools, allowedTools, disallowedTools } } 또는 codex: { fence: { sandbox } }. 블록에는 fence만 포함되며, 파일의 harness와 다른 harness의 블록은 거부됩니다. 최상위 수준의 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)를 지정하세요. 작업(job)은 사용자 설정을 읽지 않으며, 제한 없는 세션은 매 호출마다 최대 백만 토큰을 읽습니다.
• auto는 모델 측정 결과 드롭되는 모델(haiku, claude-sonnet-4-5)에서는 로드 시 거부됩니다. 규칙이 있는 경우 dontAsk를 이름을 지정하여 사용하세요.

지침

본문(body)은 지침(instructions)이며, Claude Code의 자체 프롬프트에 추가됩니다(harnessPrompt: keep). no-coding은 harness의 코딩 섹션을 삭제하고, replace는 지침을 그 자리에 넣습니다. 지침은 일반적이고 짧게 유지하세요: 누구인지, 무엇에 책임이 있는지, 절대 하지 않는 일, 턴을 종료하는 방법, 종료(closeout)에 무엇이 포함되는지. 절차는 스킬에 속하며, 기계가 처리하는 규칙(펜스, 게이트)은 문장이 필요하지 않습니다. 재개된 세션은 시작할 때의 본문을 유지합니다. 편집은 다음 실행에만 영향을 미치며, 진행 중인 실행에는 영향을 미치지 않습니다.

다섯 계층(Five Layers)

지침은 작업(task) 외에 에이전트를 형성하는 다섯 계층 중 하나이며, 각 계층은 소유자가 작성합니다:

1. 지침(Instructions) — 에이전트의 본문: 에이전트가 고용된 곳 어디에서든 identity를 정의합니다.
2. 커스텀 지침(Custom instructions) — 사용자가 에이전트를 다시 작성하지 않고 추가하는 내용으로, 사용자의 저장소에 저장되며 에이전트 이름당 하나의 파일(wf agents custom <name>)입니다. 에이전트 폴더에는 절대 저장되지 않습니다. 키를 설정하지 않으므로 펜스를 넓히거나 도구를 제공하지 않습니다. 실행 시점에 고정(freeze)되므로 편집은 이후 실행에만 영향을 미칩니다.
3. 폴더의 파일(Folder's files) — harness가 에이전트가 작업하는 폴더에서 읽는 파일(현재는 CLAUDE.md, AGENTS.md)로, 해당 폴더에서 작업하는 모든 에이전트에 적용됩니다. Nemia는 이 파일들을 조합하지 않습니다. 에이전트 자체 지침보다 우선순위가 높고, 팩토리 규칙과 단계 정책보다는 낮습니다. 다만 harness는 이 파일들을 모든 것을 재정의하는 것처럼 제시합니다. 이 프레임은 harness의 것입니다.
4. 팩토리 규칙(Factory's rules) — 하나의 팩토리에 속한 모든 에이전트에게 전달되는 규칙과 정책입니다. 팩토리당 하나의 파일이며, 저장소에 저장됩니다(nemia factory rules <name>). 저장소에는 절대 저장되지 않습니다. 커스텀 지침과 마찬가지로 단어만 포함하며, 실행 시점에 고정됩니다. 원격 에이전트의 단계에는 전달되지 않습니다.
5. 단계 정책(Step's policy) — 단계 자체의 단어와 키: 이 프로세스의 이 위치가 어떤 역할에 요구하는 사항입니다. 정상적인 계층이며, 우회 방법이 아닙니다. 여기서 하나의 워크플로우가 기대하는 것을 말하고, 지침에서는 제외하세요. 단계는 스킬을 추가할 수 있지만, 제거할 수는 없습니다.

숫자는 우선순위입니다. 두 계층이 서로 다른 내용을 말하면 더 높은 숫자가 우선하며, 작업(task)은 모든 계층 위에 있습니다. 단어가 도착하는 순서는 별도의 문제입니다 — 지침, 커스텀 지침, 팩토리 규칙, 단계 정책, 그 다음 작업이며, 폴더의 파일은 에이전트가 작업하는 곳에서 harness가 읽습니다. 새 지침이 어느 계층에 속하는지는 Nemia 자체 라우팅 규칙인 Where a new instruction goes에 따르며, 기본 제공 Five layers 절에 명시되어 있습니다. 추측하지 말고 물어보세요. 펜스는 좁혀질 뿐입니다: 단계는 에이전트의 펜스를 좁힐 수 있지만 넓힐 수는 없습니다. 단계의 disallowedTools:는 에이전트의 것에 추가되며, 로더는 에이전트가 파일에 없는 것을 허용하는 단계의 tools:, allowedTools:, permissionMode: 또는 sandbox:를 거부합니다. 따라서 지침은 역할에 대해 전반적으로 적용되는 내용만 말하고, 특정 워크플로우나 작업공간에 대해서는 말하지 않습니다.

종료(Closeout)

output: <name>.schema.json은 에이전트 옆에 있는 JSON Schema입니다. 단계가 전달하는 내용을 엄격하게 디코딩합니다. 하우스 스타일: 모든 필드는 described이고, required이며, additionalProperties: false입니다.

• 예약어: outcome, summary, artifacts, needs는 모든 종료에서 실행 자체의 것이므로, 이 중 하나를 선언하는 스키마는 로더가 거부합니다. (Iris의 의도는 proposedOutcome을 사용하는 것입니다.)
• 세션의 시도(tries) 간에 스키마를 동일하게 유지하세요. 변경된 스키마로 재개된 세션은 전체 프롬프트 캐시를 다시 빌드합니다.
• 단계는 input: <step>을 사용하여 대기하는 단계의 종료를 읽습니다. 중간 단계를 통해서도 읽을 수 있습니다. 루프(loop:)가 있는 단계는 하나의 단계만 대기할 수 있으므로, 루프 이전의 내용을 그렇게 읽습니다(검토 단계는 사양을 그렇게 읽습니다).

스킬

skills: <a>, <b>는 SKILL.md가 있는 폴더를 이름으로 지정합니다. 폴더는 agents 폴더 옆의 skills/에서, 그 다음 저장소의 .claude/skills/, 그 다음 스토어, 마지막으로 Nemia 자체 스킬에서 찾습니다. tools:는 Skill을 허용해야 합니다. 저장소의 .claude/skills/는 단계의 위치가 저장소일 때만 발견됩니다(시작 시). 테스트가 폴더를 로드하면 위치도 전달됩니다. 단계가 있는 에이전트는 자체 skills:를 사용하여 스킬을 추가할 수 있습니다. 세션은 에이전트의 스킬을 먼저, 그 다음 단계의 스킬을 각각 한 번씩 받습니다. 에이전트의 펜스는 이미 스킬을 로드하고 있어야 합니다. 단계는 펜스를 넓힐 수 없습니다.

• 스킬을 작성할 때는 스킬 생성자(skill-creator)의 방법을 따르세요: 언제 사용할지 설명하는 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는 모든 복사본에 고지를 요구합니다). 절대 편집하지 마세요. lock이 고정합니다. 에이전트 본문에서 스킬을 조정하세요. 모델이 호출할 수 있는 스킬은 vendor하세요. disable-model-invocation: true가 있는 스킬은 사용자의 슬래시 명령어입니다(grill-me는 grilling만 호출합니다).

펜스(Fence)

• 아무것도 작성하지 않는 역할은 dontAsk를 실행합니다. 작업공간에서 읽기 전용, 읽기 전용 명령어, 그리고 허용 규칙이 명명한 것만 실행합니다. 나머지는 묻지 않고 거부됩니다. 저장소 설정은 다른 역할이 작업공간에 쓰기가 필요한 명령어(예: 빌드)를 허용할 수 있으므로, Bash가 부여된 에이전트는 disallowedTools:에서 각각을 이름으로 금지합니다. 하위 에이전트는 모드와 규칙을 상속받습니다. allowedTools:에 Agent를 나열하여 디스패치 자체가 거부되지 않도록 하세요. 역할이 실행하는 각 검사(check)에 대해 설정에서 허용하지 않는 것을 정확한 이름으로 허용하세요. 해당 검사의 스킬은 각각을 하나의 호출로 명시합니다(래핑, 파이프, 리디렉션, 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:는 에이전트의 것에 추가됩니다. 단계가 추가하는 금지 사항만 작성하세요. 에이전트의 금지 사항을 제거할 수 없습니다.

사람과 대화하기

단계는 Agent SDK의 작업입니다. 대화 내에서 대기할 수 없습니다. 질문하기 위해 blocked로 종료(sign off)합니다. 사람은 보드에서 답변하거나 wf retry <run> <step> --message "…"를 사용하며, 동일한 세션이 답변을 다음 턴으로 하여 계속됩니다. 인터뷰하는 에이전트의 본문에 이 내용을 명시하고, 종료를 사람이 승인해야 하는 단계는 게이트를 설정하세요(gate: true). 작업의 마지막 턴은 종료입니다. 긴 명령어(e2e)를 실행하는 에이전트는 포그라운드에서 실행하거나 대기하도록 지시받으며, 실행 중인 명령어와 함께 종료하면 안 됩니다(한 엔지니어의 첫 웹 빌드가 e2e가 끝나기 전에 종료된 사례가 있었습니다). blocked로 종료된 종료는 자체적으로 읽히므로, 라운드로 질문하는 에이전트는 각 라운드에서 지금까지 결정된 모든 것을 전달해야 합니다. 한 인터뷰어의 세 번째 라운드에서 이전 결정이 누락된 사례가 있었습니다. 질문을 출력 스키마의 필드로 선언하세요: { "x-shape": "questions", "description": "…" }. 로더는 이를 하나의 엄격한 형태로 확장합니다. 보드는 사람이 클릭하여 답변하는 선택사항으로 표시합니다. 게이트가 있는 단계가 이후 단계의 비용을 알고 있으면 { "x-shape": "budgets", "description": "…" }를 함께 선언하세요: { step, usd, why } 리스트로, 게이트 이후 각 단계에 대해 한 번씩, 달러 단위로 0보다 크게, why는 금액의 근거입니다. 게이트는 종료 옆에 예산을 표시하며, 승인 시 해당 단계의 상한선(cap)이 됩니다. 사람이 변경한 금액(nemia approve <run> <step> --budget <step>=<amount>)도 적용됩니다. 단계 자체의 budget:보다 높은 상한선은 해당 단계에서 명시되며, 요청 없이는 승인되지 않습니다. 다른 단계를 이름으로 지정하거나 금액이 없는 종료는 세션으로 반환되어 거부됩니다.

확인하기

1. 저장소에서 npx wf agents card <name>을 실행합니다. 실제 로더가 파일을 읽습니다 — 키, 스키마의 예약된 이름, 발견된 각 스킬 — 그리고 카드를 출력하거나 수정 사항을 명시하는 거부 메시지를 표시합니다.
2. 저장소 자체의 검사를 실행하세요. 저장소의 가드(guard)가 제공된 모든 폴더(펜스, 고정된 단계, 렌더링 라운드트립)를 읽습니다. 워크플로우 폴더를 보지 않는 캐시를 우회하여 실행하세요.
3. 실행하세요. 새 에이전트를 사용하는 게이트가 있는 워크플로우를 작은 실제 카드로 실행하고, 승인 전에 종료를 읽으세요.
4. 저장소가 에이전트를 나열하는 곳에 새 에이전트의 이름을 추가하세요.

배운 점이 있을 때

에이전트 생성을 통해 이 스킬이 테스트됩니다. 이 문서의 단계가 잘못되었거나 누락된 경우 — 마주친 거부, 예상치 못한 키 — 이 파일을 에이전트와 동일한 변경사항에서 최대 세 줄까지 수정하고, 규칙이 있는 파일과 함께 수정하세요.