2.2 에이전트 만드는 방법

각 플랫폼에서 에이전트 파일을 작성하고 자동 호출 조건을 설정하는 단계별 방법을 설명한다. 업데이트: 2026-03-08

핵심 요약

구분	내용
📖 정의	에이전트는 마크다운 파일 + YAML frontmatter 형태로 정의되며, 지정 경로에 저장하면 즉시 인식된다
💡 핵심	`description` 필드가 자동 호출 정확도를 결정한다. 구체적인 상황과 예시를 포함할수록 정확도가 높아진다
🎯 대상	반복 전문 작업을 자동화하려는 개발자
⚠️ 주의	도구 권한은 필요 최소한으로 지정한다 (least-privilege 원칙)

문서 탐색

이전	다음
2.2.1 에이전트란?	2.2.3 에이전트 예제

1. Claude Code 에이전트 만들기

Claude Code의 서브에이전트는 마크다운 파일 + YAML frontmatter 형태로 정의한다.

저장 위치

위치	경로	사용 범위
프로젝트 전용	`.claude/agents/에이전트명.md`	해당 프로젝트에서만 사용
글로벌 (모든 프로젝트)	`~/.claude/agents/에이전트명.md`	모든 프로젝트에서 사용 가능

💡 같은 이름의 에이전트가 양쪽에 있으면 프로젝트 레벨이 우선한다.

파일 구조

---
name: 에이전트-이름
description: >
  Claude가 언제 이 에이전트를 호출할지 판단하는 기준.
  구체적이고 상황 예시가 포함될수록 자동 호출 정확도가 높아진다.
tools: Read, Grep, Glob, Bash, Write
model: sonnet
---
 
[여기가 에이전트의 시스템 프롬프트]
 
에이전트가 어떻게 동작해야 하는지 구체적으로 서술한다.

YAML frontmatter 옵션 상세

필드	필수	설명
`name`	필수	에이전트 식별자 (소문자, 하이픈 사용)
`description`	필수	Claude가 언제 이 에이전트를 호출할지 결정하는 핵심 기준
`tools`	선택	허용 도구 목록. 생략 시 메인 스레드의 도구 전체 상속
`model`	선택	`inherit`(기본), `sonnet`, `opus`, `haiku`
`color`	선택	UI 표시 색상 (blue, green, red 등)

사용 가능한 도구 목록:

Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch,
NotebookEdit, TodoWrite, Agent, Task

/agents 명령으로 생성하기

터미널에서 직접 생성하는 방법:

flowchart TD
    A["/agents 입력"] --> B["Create new agent 선택"]
    B --> C{"저장 범위 선택"}
    C --> D["User-level (글로벌)"]
    C --> E["Project-level"]
    D --> F["Generate with Claude: 에이전트 역할 설명 입력"]
    E --> F
    F --> G["Claude가 시스템 프롬프트와 설정 자동 생성"]

자동 호출 조건

Claude는 description 필드를 보고 현재 작업에 맞는 에이전트를 자동 선택한다. description에 언제 사용하는지와 예시를 명확히 작성할수록 정확도가 높아진다.

description: >
  웹 검색이 필요할 때 자동 호출.
  최신 라이브러리 문서, CVE 취약점, 시장 동향 조사 요청 시 사용.
 
  <example>
  user: "React 19 최신 변경사항 조사해줘"
  → 이 에이전트 호출
  </example>

모범 사례

원칙	내용
도구는 최소화	에이전트에 필요한 도구만 명시 (least-privilege 원칙)
description은 구체적으로	”언제 호출하는지” + “예시” 포함
모델은 용도에 맞게	빠른 처리 → haiku, 복잡한 추론 → opus
범위에 맞게 저장	범용 에이전트는 글로벌(`~/.claude/agents/`), 프로젝트 특화는 `.claude/agents/`

2. Gemini CLI 에이전트 만들기

Gemini CLI는 서브에이전트와 Agent Skills 두 가지 방식을 지원한다.

서브에이전트 (실험적)

Claude Code와 유사한 구조로, .gemini/agents/ 디렉토리에 마크다운 파일을 생성한다.

---
name: 에이전트-이름
description: 이 에이전트를 언제 호출할지 설명
tools: [bash, read, write]
---
 
[시스템 프롬프트]

저장 위치:

프로젝트: .gemini/agents/에이전트명.md
글로벌: ~/.gemini/agents/에이전트명.md

Agent Skills

Skills는 Gemini CLI의 공식 확장 방식으로, 지시사항·리소스·스크립트를 하나의 디렉토리에 패키징한다.

my-skill/
├── SKILL.md        # 필수: 스킬 정의
├── scripts/        # 선택: 실행 스크립트
└── resources/      # 선택: 참고 리소스

SKILL.md 구조:

---
name: my-skill
description: 스킬 설명
version: 1.0.0
---
 
# [스킬명]
 
## 목적
이 스킬이 수행하는 작업
 
## 실행 방법
단계별 지시사항
 
## 참고 리소스
- resources/guide.md

스킬 설치:

# 로컬 스킬 설치
gemini skill install ./my-skill
 
# 원격 스킬 설치
gemini skill install https://github.com/user/skill-repo

Hooks로 에이전트 동작 커스터마이즈

Hooks는 에이전트 루프의 특정 이벤트에 스크립트를 연결한다:

// .gemini/hooks.json
{
  "before_tool_call": "scripts/validate.sh",
  "after_tool_call": "scripts/log.sh",
  "on_error": "scripts/notify.sh"
}

3. OpenAI Codex 에이전트 만들기

Codex는 AGENTS.md(글로벌 지시)와 Skills(작업별 에이전트) 두 레이어로 에이전트를 구성한다.

AGENTS.md — 글로벌 지시사항

모든 Codex 세션에 적용되는 기본 지시사항이다. 프로젝트 루트 또는 홈 디렉토리에 위치한다.

# AGENTS.md
 
## 코딩 스타일
- TypeScript 사용, any 타입 금지
- 함수형 컴포넌트 선호
 
## 테스트
- 모든 신규 함수에 단위 테스트 작성
- Jest + Testing Library 사용
 
## 커밋
- Conventional Commits 형식 준수

Skills — 작업별 에이전트

Skills는 특정 워크플로우를 패키징한 에이전트다. SKILL.md 파일이 핵심이다.

.codex/skills/
└── code-reviewer/
    ├── SKILL.md       # 필수
    └── checklist.md   # 선택

SKILL.md 구조:

---
name: code-reviewer
description: 코드 품질 검토 전문 에이전트
---
 
## 역할
PR의 코드를 검토하고 개선사항을 제안한다.
 
## 검토 항목
- 로직 오류
- 보안 취약점
- 성능 이슈
- 코딩 컨벤션 위반
 
## 출력 형식
### [파일명]
- **이슈**: 설명
- **제안**: 개선 방법

Agents SDK로 멀티에이전트 구성

Codex CLI를 MCP 서버로 노출하고 Agents SDK로 오케스트레이션:

from openai import AgentSDK
 
# Codex를 서브에이전트로 등록
codex_agent = AgentSDK.create_agent(
    name="codex-coder",
    mcp_server="http://localhost:3001",
    instructions="코드 작성 및 리팩토링 전담"
)
 
# 멀티에이전트 워크플로우
workflow = AgentSDK.create_workflow([
    codex_agent,
    reviewer_agent,
    test_agent
])

4. 플랫폼별 에이전트 생성 방식 비교

항목	Claude Code	Gemini CLI	OpenAI Codex
파일 형식	`.md` (YAML + 프롬프트)	`.md` (YAML + 프롬프트)	`SKILL.md`
설정 파일	`frontmatter`	`frontmatter`	`AGENTS.md`
저장 경로	`.claude/agents/`	`.gemini/agents/`	`.codex/skills/`
글로벌 에이전트	`~/.claude/agents/`	`~/.gemini/agents/`	`~/AGENTS.md`
자동 호출	description 기반	description 기반	AGENTS.md 항시 적용
도구 제한	frontmatter `tools`	frontmatter `tools`	스킬별 설정
생성 명령	`/agents`	`gemini skill install`	수동 생성

문서 탐색

이전	다음
2.2.1 에이전트란?	2.2.3 에이전트 예제

JW's AI_Stash

Explorer

2.2.2 에이전트 만들기

2.2 에이전트 만드는 방법

핵심 요약

문서 탐색

목차

1. Claude Code 에이전트 만들기

저장 위치

파일 구조

YAML frontmatter 옵션 상세

/agents 명령으로 생성하기

자동 호출 조건

모범 사례

2. Gemini CLI 에이전트 만들기

서브에이전트 (실험적)

Agent Skills

Hooks로 에이전트 동작 커스터마이즈

3. OpenAI Codex 에이전트 만들기

AGENTS.md — 글로벌 지시사항

Skills — 작업별 에이전트

Agents SDK로 멀티에이전트 구성

4. 플랫폼별 에이전트 생성 방식 비교

문서 탐색

참고 자료

Graph View

Table of Contents

Backlinks