Claude Code 서브에이전트가 목록에 안 뜰 때
.claude/agents 에 만든 서브에이전트가 호출되지 않거나 목록에 없을 때, 파일 위치 · frontmatter · 디버그 로그 · 재시작 조건을 순서대로 확인합니다.
서브에이전트 파일을 만들었는데 Claude 가 그 이름을 모른다고 하면, 파일이 조용히 건너뛰어진 경우가 대부분입니다. 아래는 2.1.302 에서 일부러 틀린 파일 8개와 정상 파일 1개를 두고 어느 것이 로드되는지 본 결과입니다.
[1] 먼저 Claude 에게 보이는 서브에이전트 이름을 뽑습니다.
$ claude -p "List the name of every subagent type available to your Agent/Task tool, one per line, nothing else." --max-turns 2badyamlbrokenyamlclaudeExploregeneral-purposegood-reviewerPlanstatusline-setup[2] /agents 로 확인하려 했다면 버전부터 봅니다. 공식 문서 기준으로 v2.1.197 이하에서는 /agents 가 목록 · 생성 마법사를 열었고, 그 뒤 버전에서는 안내문만 나옵니다. 2.1.302 에서 claude -p "/agents" 를 실행한 결과입니다.
$ claude -p "/agents"The /agents wizard has been removed. Ask Claude to create or update subagents for you (e.g. "create a code-reviewer subagent that ...").뒤에는 .claude/agents/ · ~/.claude/agents/ 를 직접 고치라는 안내가 이어집니다. 목록은 1단계의 질문이나 3단계의 디버그 로그로 확인합니다.
[3] 파일이 왜 빠졌는지는 디버그 로그에 있습니다. 세션 화면에는 아무것도 안 나옵니다.
$ claude -p "hi" --max-turns 1 --debug-file /tmp/agents.log$ grep -E "Agent file|agents/" /tmp/agents.log# 출력은 관련 줄만 골라 옮겼습니다[DEBUG] Failed to stat directory /home/user/.claude/agents: ENOENT: no such file or directory, stat '/home/user/.claude/agents'[DEBUG] Agent file /srv/app/.claude/agents/nodesc.md is missing required 'description' in frontmatter[WARN] Agent file /srv/app/.claude/agents/typo.md has a frontmatter key Claude Code does not recognize or apply: "descripton" (did you mean "description"?)[ERROR] YAML frontmatter in /srv/app/.claude/agents/rb.md failed to parse and was ignored: YAML Parse error: Unexpected EOF첫 줄은 오류가 아니라 ~/.claude/agents 폴더가 없다는 뜻입니다. 그 아래 세 줄이 건너뛴 파일입니다.
[4] frontmatter 를 고칩니다. 필수 필드는 name 과 description 둘입니다. 시험한 파일별 결과는 다음과 같습니다.
| 파일 내용 | 목록 | 로그 |
|---|---|---|
name · description 정상 | 있음 | — |
name 없음 | 없음 | 아무것도 안 찍힘 |
첫 줄이 빈 줄이고 둘째 줄이 --- | 없음 | 아무것도 안 찍힘 |
name 만 있고 description 없음 | 없음 | missing required 'description' |
descripton 오타 | 없음 | WARN 에 「did you mean」 |
| 닫히지 않은 따옴표 · 탭 들여쓰기 | 없음 | ERROR · YAML Parse error |
name 이 없는 파일은 서브에이전트가 아니라 「에이전트 폴더 옆에 둔 문서」로 취급된다고 문서에 적혀 있습니다. 여는 --- 가 파일 첫 줄이 아닌 경우도 같습니다. 그래서 로그에도 안 남습니다. 이 두 경우는 로그를 봐도 단서가 없으니, 파일 맨 위 세 줄부터 눈으로 확인합니다.
---name: code-reviewerdescription: Reviews a diff for bugs. Use after code changes.---You are a code reviewer. Report only problems you can point to in the diff.[5] 위치를 봅니다. 문서의 위치와 우선순위입니다.
| 위치 | 범위 | 우선순위 |
|---|---|---|
| 관리형 설정 | 조직 전체 | 1 (최고) |
--agents 플래그 | 현재 세션 | 2 |
.claude/agents/ | 현재 프로젝트 | 3 |
~/.claude/agents/ | 내 모든 프로젝트 | 4 |
플러그인의 agents/ | 플러그인을 켠 곳 | 5 (최저) |
폴더는 하위 폴더까지 재귀로 읽습니다. 프로젝트 쪽은 현재 폴더에서 저장소 루트까지 올라가며 각 .claude/agents/ 를 모두 봅니다. 실제로 proj/sub/deep 에서 실행해도 proj/.claude/agents/ 의 에이전트가 목록에 나왔습니다(시험 폴더는 git 저장소가 아니었습니다). 반대로 하위 폴더에만 둔 .claude/agents/ 는 그 폴더에서 실행했을 때만 보입니다. 이 경우는 시험하지 않았습니다.
[6] 같은 이름이 둘이면 우선순위가 높은 쪽이 이깁니다. --agents 로 good-reviewer 를 같은 이름으로 정의하고 설명을 물었더니 파일이 아니라 플래그 쪽 설명이 나왔습니다.
$ claude -p "Quote verbatim the description of the subagent type good-reviewer from your Agent/Task tool, nothing else." --max-turns 2 --agents '{"good-reviewer":{"description":"FROM-FLAG override","prompt":"x"}}'FROM-FLAG override프로젝트와 개인 폴더가 겹치는 경우(3 대 4)는 이 환경에서 개인 폴더를 건드리지 않으려고 시험하지 않았고, 문서 표를 따릅니다. 같은 폴더 안에서 이름이 겹치면 문서상 어느 파일이 쓰일지 정해져 있지 않습니다(파일 시스템 읽기 순서).
[7] 세션을 연 뒤에 만든 파일이면 재시작이 필요한지 봅니다. 문서 기준으로 Claude Code 는 .claude/agents/ 와 ~/.claude/agents/ 를 감시해서 수 초 안에 반영합니다. 다음 세 경우는 재시작해야 합니다.
- 세션이 시작될 때 없던
agents폴더에 첫 파일을 만든 경우 --add-dir·/add-dir로 추가한 폴더 안의.claude/agents/를 만들거나 고친 경우--disable-slash-commands로 시작한 세션
[8] 목록에는 있는데 자동으로 안 불리면 description 문제입니다. Claude 는 설명을 보고 위임을 정하므로 「Use after code changes」처럼 쓰는 시점을 적습니다. 그래도 안 되면 요청에 에이전트 이름을 직접 적습니다.
스킬이 안 뜨는 경우는 별개의 폴더 · 규칙이라 Claude Code 스킬이 안 뜨거나 안 쓰일 때에 따로 정리했습니다.