본문으로 건너뛰기

커스텀 Agent 만들기

Elftia는 커스텀 Agent를 만드는 두 가지 방법을 지원합니다: 앱 내 UI를 통하거나, .claude/agents/*.md 설정 파일을 직접 작성하는 방법입니다. 두 방법 모두 최종적으로 Markdown 형식의 Agent 설정 파일을 생성합니다.

UI를 통한 생성​

단계​

  1. Agent 패널 열기 (사이드바의 Agent 아이콘)
  2. "내 Agent" 탭으로 전환
  3. "Agent 만들기" 버튼 클릭
  4. 다음 설정 필드를 채웁니다:
필드설명예시
이름Agent의 표시 이름프론트엔드 코드 리뷰어
설명Agent 기능을 한 문장으로 요약React/TypeScript 코드 품질 검토
시스템 프롬프트Agent의 핵심 지침 (Markdown 형식)아래 예시 참조
모델사용할 LLM 모델 또는 별칭main, background
도구 목록허용된 도구 (비워두면 = 전체 상속)Read, Grep, Glob
Skills자동으로 로드할 Skillscode-standards
MCP 서버연결할 MCP 서버github-mcp
권한 모드도구 실행 보안 수준default
  1. "저장"을 클릭하여 완료

저장 위치 선택​

생성 시 저장 위치를 선택할 수 있습니다:

  • 프로젝트 수준 — 현재 프로젝트의 .claude/agents/ 디렉터리에 저장되며, 이 프로젝트에서만 사용 가능합니다
  • 개인 수준 — ~/.claude/agents/에 저장되며, 모든 프로젝트에서 사용 가능합니다

파일을 통한 생성​

.claude/agents/ 디렉터리에 Markdown 파일을 만들면 됩니다. 파일 이름이 Agent의 식별자가 됩니다.

파일 형식​

---
name: Agent 이름
description: Agent 설명
model: main
permissionMode: default
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
  - ListDir
  - WebSearch
  - WebFetch
skills:
  - code-standards
---

이 부분이 시스템 프롬프트의 본문 내용입니다 (Markdown 형식).

Agent는 작업을 실행할 때 이 지침을 따릅니다.

전체 필드 참조​

필드타입기본값설명
namestring파일 이름Agent 표시 이름
descriptionstring없음Agent 설명
modelstringmain모델 선택 (별칭 지원)
permissionModestringdefault권한 모드
toolsstring[]전체 상속허용된 도구 허용 목록
skillsstring[]없음자동 로드할 Skills

설정 예시​

예시 1: 프로그래밍 어시스턴트​

코딩 작업에 집중하며 파일 시스템과 셸에 대한 완전한 접근 권한을 가집니다.

---
name: 풀스택 프로그래밍 어시스턴트
description: TypeScript/React/Node.js에 능숙한 풀스택 개발 어시스턴트
model: main
permissionMode: acceptEdits
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
  - ListDir
  - WebSearch
  - WebFetch
  - spawn_agent
skills:
  - code-standards
  - architecture-index
---

당신은 TypeScript, React, Node.js에 능숙한 풀스택 개발 어시스턴트입니다.

## 워크플로

1. 먼저 요구 사항을 이해하고, 필요하면 명확한 질문을 합니다
2. Glob/Grep을 사용하여 관련 코드를 찾습니다
3. Read를 사용하여 핵심 파일을 검토합니다
4. 구현 계획을 수립합니다
5. Write/Edit을 사용하여 코드를 작성합니다
6. Bash를 사용하여 테스트를 실행합니다

## 코딩 표준

- 프로젝트의 ESLint 및 Prettier 설정을 따릅니다
- 새 파일은 400줄을 초과하지 않습니다
- TypeScript strict 모드를 사용합니다
- 공개 API에 JSDoc 주석을 추가합니다

예시 2: 리서치 분석 Agent​

읽기 전용 모드로, 정보 수집과 분석에 집중합니다.

---
name: 리서치 애널리스트
description: 코드베이스와 웹에서 정보를 수집하여 심층 분석 수행
model: main
permissionMode: plan
tools:
  - Read
  - Glob
  - Grep
  - ListDir
  - WebSearch
  - WebFetch
  - list_skills
  - read_skill
---

당신은 코드베이스와 웹에서 정보를 수집하여 분석하는 데 능숙한 리서치 애널리스트입니다.

## 작업 방식

1. 리서치 주제를 신중하게 이해합니다
2. Grep/Glob을 사용하여 코드베이스에서 관련 정보를 검색합니다
3. WebSearch를 사용하여 외부 참조 자료를 찾습니다
4. WebFetch를 사용하여 웹 콘텐츠의 자세한 내용을 가져옵니다
5. 모든 정보를 종합하여 구조화된 분석 보고서를 작성합니다

## 출력 형식

Markdown 형식으로 보고서를 작성하며 다음 내용을 포함합니다:
- 요약
- 주요 발견 사항
- 상세 분석
- 권고 사항 및 결론

예시 3: 작업 자동화 Agent​

백그라운드 하위 Agent를 사용하여 여러 하위 작업을 병렬로 처리합니다.

---
name: 작업 오케스트레이터
description: 복잡한 작업을 하위 작업으로 분해하여 병렬 실행
model: main
permissionMode: acceptEdits
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
  - ListDir
  - spawn_agent
  - Notify
---

당신은 복잡한 작업을 병렬화 가능한 하위 작업으로 분해하는 데 능숙한 작업 오케스트레이터입니다.

## 워크플로

1. 작업을 분석하고 병렬로 실행할 수 있는 하위 작업을 파악합니다
2. spawn_agent를 사용하여 각 하위 작업에 대한 하위 Agent를 시작합니다
3. 하위 Agent의 결과를 수집합니다
4. 결과를 통합하고 일관성을 검증합니다
5. Notify를 사용하여 작업 완료를 알립니다

## 하위 Agent 원칙

- 각 하위 Agent는 명확하게 정의된 하나의 하위 작업을 담당합니다
- 병렬 실행을 위해 백그라운드 모드(background: true)를 우선적으로 사용합니다
- 하위 Agent에게 최소한의 필요한 도구 세트를 제공합니다
- 무한 루프를 방지하기 위해 적절한 maxIterations를 설정합니다

도구 허용 목록 설정​

tools 필드는 Agent가 사용할 수 있는 도구를 제어합니다.

사용 가능한 도구 이름​

도구설명민감도
Read파일 내용 읽기안전
Write파일 쓰기민감
Edit파일 편집 (찾기 및 바꾸기)민감
ListDir디렉터리 내용 나열안전
Glob파일명 패턴 매칭안전
Grep내용 검색안전
Bash셸 명령 실행민감
WebSearch웹 검색안전
WebFetch웹 콘텐츠 가져오기안전
spawn_agent하위 Agent 시작민감
list_skills사용 가능한 Skills 나열안전
read_skillSkill 내용 읽기안전
Notify데스크톱 알림 보내기안전
SessionsYieldAgent 루프 종료안전

:::tip 전체 도구 상속을 위해 생략 tools 필드를 설정하지 않으면 Agent가 사용 가능한 모든 도구(MCP 도구 포함)를 상속합니다. 도구 범위를 제한해야 할 때만 허용 목록을 설정하세요. :::

모델 별칭 상세 정보​

별칭동작
main / inherit현재 세션의 기본 모델 사용
background사용자가 설정에서 구성한 백그라운드 모델 사용 (일반적으로 Haiku 같은 경량 모델)
sonnet상위 모델의 패밀리 이름을 sonnet으로 교체 (예: claude-3-opus → claude-3-sonnet)
opus상위 모델의 패밀리 이름을 opus로 교체
haiku상위 모델의 패밀리 이름을 haiku로 교체

백그라운드 모델에 적합한 사용 사례:

  • WebFetch 콘텐츠 요약
  • 하위 Agent의 간단한 보조 작업
  • 높은 추론 능력이 필요하지 않은 데이터 처리

Skill 연결​

skills 필드에 Skill 이름을 나열하면 Agent 시작 시 해당 내용이 시스템 프롬프트에 자동으로 주입됩니다:

skills:
  - code-standards      # 프로젝트 코딩 표준
  - architecture-index  # 프로젝트 아키텍처 인덱스

Skill 조회 순서:

  1. 프로젝트 디렉터리 .claude/skills/<name>/SKILL.md
  2. 개인 디렉터리 ~/.claude/skills/<name>/SKILL.md
  3. 플러그인 디렉터리 ~/.elftia/plugins/skills/<name>/SKILL.md
  4. 내장 Skills

테스트 및 디버깅​

Agent를 만든 후 다음 테스트를 수행하는 것이 권장됩니다:

  1. 기본 대화 — Agent가 자신의 역할과 기능을 이해하는지 확인
  2. 도구 호출 — 도구 허용 목록이 올바르게 설정되었는지 검증
  3. 권한 확인 — 권한 모드가 예상대로 동작하는지 확인
  4. Skill 로딩 — Skills가 시스템 프롬프트에 올바르게 주입되었는지 확인
  5. 경계 테스트 — Agent가 허가되지 않은 도구를 사용하도록 시도하여 올바르게 거부되는지 검증

FAQ​

문제원인해결 방법
Agent가 지정된 도구를 사용하지 않음시스템 프롬프트에 사용 안내가 없음시스템 프롬프트에 언제 어떤 도구를 사용하는지 명시적으로 기술
Agent가 시스템 프롬프트를 무시함사용자 메시지가 지침을 덮어씀더 단호한 시스템 프롬프트 사용. "반드시" 같은 키워드 추가
Skills가 적용되지 않음Skill 이름 오타list_skills 도구로 사용 가능한 Skill 이름 확인
파일이 잘못된 위치에 저장됨경로가 잘못됨파일이 .claude/agents/ 또는 ~/.claude/agents/ 아래에 있는지 확인
YAML frontmatter 파싱 실패형식 오류--- 구분자를 사용했는지, YAML 문법이 유효한지 확인

관련 링크​