Claude 스킬이 서브에이전트에서 작동하지 않을 때 확인할 4단계
Claude Code 서브에이전트의 스킬 문제를 검색, 사전 로드, 호출, 실행으로 나누어 진단합니다. 설정 예제와 실패 조건, 다운로드할 수 있는 진단 프로젝트를 제공합니다.
Claude 스킬이 기본 대화에서는 작동하지만 사용자 정의 서브에이전트에서는 작동하지 않는다면 검색, 사전 로드, 호출, 실행을 나누어 확인하세요. 도구 목록에 Skill을 추가한다고 지침이 미리 로드되는 것은 아닙니다. skills:에 이름을 넣는다고 그 지침에 필요한 모든 도구가 허용되는 것도 아닙니다.
현재 Claude Code 문서는 서브에이전트가 시작할 때 스킬을 미리 로드하는 방식과 실행 중 동적으로 호출하는 방식을 모두 설명합니다. “서브에이전트는 스킬을 호출할 수 없다”는 예전 설명은 해당 버전의 정보로 보아야 하며, 현재의 보편적인 규칙으로 받아들이면 안 됩니다. skills 필드 설명(영문)은 시작 시 지침을 로드하는 방법이고, Skill 도구는 실행 중 호출하는 별도의 경로입니다.
이 글은 로컬 Claude Code의 사용자 정의 에이전트와 프로젝트 스킬을 다룹니다. 2026년 11월 18일 공식 문서와 대조했습니다. 다운로드 예제는 편집부가 만든 진단용 테스트 자료입니다. 파일과 예상 결과 검사기는 로컬에서 검증했지만, 모델 추론을 실행하거나 성공률을 측정하지는 않았습니다. 아래의 예상 응답은 판정 기준이며, 실제로 수집한 Claude 출력이 아닙니다.
설정을 바꾸기 전에 실패 단계를 찾기
| 관찰한 증상 | 먼저 확인할 단계 | 확인할 증거 |
|---|---|---|
| 부모 세션에서도 스킬을 사용할 수 없음 | 검색 또는 호출 제어 | 실제로 해석된 스킬 이름, 파일 위치, frontmatter, 정책 |
| 부모는 사용하지만 사용자 정의 에이전트가 지침을 무시함 | 사전 로드 또는 동적 호출 | 실제 선택된 에이전트 정의, 로드 경고 또는 Skill 호출 |
| Skill 호출이 거부됨 | 도구 접근 및 권한 규칙 | 거부된 정확한 도구와 해당 규칙 |
| 지침은 있지만 스크립트나 파일 작업이 실패함 | 실행 | 파일 경로, 작업 디렉터리, 거부된 작업, 스크립트 오류 |
| 특정 폴더에서만 작동함 | 적용 범위 또는 이름 충돌 | 시작 디렉터리, 저장소 루트, 실제 스킬 출처 |
실패하는 입력 하나를 유지하고 실행할 때마다 한 가지 조건만 바꾸세요. 각 변형은 새 부모 세션과 새 서브에이전트에서 실행해 이전 결과가 다음 위임 내용에 섞이지 않게 합니다. 위임할 작업이나 자동으로 로드되는 프로젝트 지침에 마커와 예상 답을 넣지 마세요. 파일 이동, 도구 허용, 설명 수정까지 한꺼번에 하면 어떤 변경이 문제를 해결했는지 알기 어렵습니다. 전체 개념은 Hooks·Subagents·Skills 가이드(영문)를 참고하세요. 이 글은 실패 원인을 분리하는 데 초점을 맞춥니다.
1. 로드 여부를 관찰할 수 있는 작은 스킬 만들기
일회용 로컬 디렉터리를 사용하세요. Claude Code가 설치되어 있고, 사용 권한이 있는 모델 연결이 이미 구성되어 있어야 합니다. 추론을 실행하기 전에 claude --version과 사용할 모델, 공급자를 기록하세요. 모델 요청은 기존 사용 한도나 API 잔액을 소모할 수 있지만, 예제를 다운로드하는 것만으로 요청이 실행되지는 않습니다.
진단 프로젝트를 다운로드하거나 아래 파일을 직접 만드세요. ZIP에는 같은 파일, 프롬프트, 결과 검사기, 사용 설명이 들어 있습니다. 새 폴더에 압축을 풀고 내용을 확인한 뒤 그 폴더에서 Claude Code를 시작합니다. 예제에는 훅, 네트워크 호출, 인증 정보 파일이 없습니다. 코드와 압축 파일의 설명은 영문을 유지했습니다.
skill-diagnostic/
├── .claude/
│ ├── agents/
│ │ ├── audit-preloaded.md
│ │ └── audit-dynamic.md
│ └── skills/
│ └── sample-audit/
│ └── SKILL.md
├── sample.csv
└── check_result.py
다음 내용을 .claude/skills/sample-audit/SKILL.md에 저장하세요. 마커는 스킬의 출력 형식 지침이 적용되었는지 관찰하기 위한 것입니다. 보안 장치도 아니고, 지침이 어떤 경로로 전달되었는지를 증명하는 장치도 아닙니다.
---
name: sample-audit
description: Audit the synthetic sample.csv fixture and report missing amounts.
---
Read sample.csv in the working directory. Do not change any files.
Return exactly four lines, with no Markdown fences:
SKILL_MARKER=sample-audit-v1
ROWS=<number of data rows, excluding the header>
MISSING_AMOUNT_IDS=<comma-separated IDs, or none>
TOTAL_KNOWN_AMOUNT=<sum of nonempty amounts, two decimal places>
Keep IDs as text. A blank amount is missing, not zero.
입력 파일 sample.csv는 의도적으로 작게 만들었습니다.
id,amount
0007,12.50
0008,
0009,7.50
예상 응답 네 줄을 위임 프롬프트에 붙여 넣지 마세요. 그러면 에이전트가 스킬을 사용하지 않고도 답을 재현할 수 있습니다. 스킬 지침과 입력 파일을 함께 사용해야 답할 수 있어야 이 비교가 의미를 갖습니다.
2. 사용자 정의 에이전트의 사전 로드 확인하기
.claude/agents/audit-preloaded.md를 저장하세요.
---
name: audit-preloaded
description: Audit sample.csv using the preloaded sample-audit instructions.
tools: Read
skills:
- sample-audit
---
Follow the preloaded audit instructions on sample.csv.
Do not read SKILL.md yourself. If the audit instructions are absent,
report PRELOAD_MISSING rather than inventing a format.
현재 사전 로드 목록에서는 중복을 제외한 앞의 32개 이름까지 처리합니다. 로드되는 것은 스킬 본문이며, 폴더의 모든 보조 파일이 아닙니다. 스킬이 하나뿐인 이 예제에는 두 제한 모두 영향을 주지 않습니다.
파일을 준비한 뒤 새 세션을 시작하고 다음과 같이 요청하세요.
Use the audit-preloaded subagent to audit sample.csv.
Return its result verbatim. Do not perform the audit in the parent.
실행 기록에서 audit-preloaded가 선택되었는지 확인하세요. 이 에이전트에는 의도적으로 Read만 있습니다. 사전 로드 실험에서는 Skill 도구 호출이 없어도 정상입니다. SKILL.md를 직접 읽거나 부모가 대신 작업했다면 의도한 비교는 성립하지 않습니다. 다른 경로로 답을 얻은 것이며, 시작 시 사전 로드가 성공했다는 증거는 아니기 때문입니다.
예상 응답은 다음과 같습니다.
SKILL_MARKER=sample-audit-v1
ROWS=3
MISSING_AMOUNT_IDS=0008
TOTAL_KNOWN_AMOUNT=20.00
해당 에이전트의 응답만 result.txt에 복사한 후 python3 check_result.py result.txt를 실행하세요. 검사기는 예제의 네 줄을 검증합니다. 로드 경로를 증명할 수는 없으므로 실행 기록과 디버그 자료도 확인해야 합니다.
실패 조건을 비교하려면 에이전트의 skills: 목록에 있는 sample-audit를 sample-audit-missing처럼 존재하지 않는 이름으로 바꾸고 새 세션과 새 에이전트에서 실행하세요. 예상 진단 응답은 PRELOAD_MISSING이지만 정확한 문구까지 보장되는 것은 아닙니다. 현재 문서는 없거나 비활성화된 사전 로드 항목을 건너뛰고 디버그 로그에 경고를 남긴다고 설명합니다. 다음 단계로 넘어가기 전에 원래 이름을 복구하세요. 여전히 정상 결과가 나오면 부모가 지침을 전달했는지, 잘못된 에이전트가 선택되었는지, 다른 파일에 마커가 있는지 확인합니다.

이 글을 위해 캡처한 공식 문서입니다. 추론 실행에 성공한 화면을 캡처한 것이 아닙니다.
3. 사전 로드 없이 동적으로 호출하는 경우와 비교하기
.claude/agents/audit-dynamic.md를 저장하세요.
---
name: audit-dynamic
description: Audit sample.csv by invoking the sample-audit skill.
tools: Read, Skill
---
First invoke the sample-audit skill using the Skill tool.
Then follow it on sample.csv. Do not read SKILL.md directly.
If the skill cannot be invoked, report INVOCATION_FAILED and the reason.
이 정의에는 skills: 필드가 없습니다. 부모에게 audit-dynamic으로 위임하고 응답을 그대로 반환하도록 요청하세요. 동적 경로의 성공을 확인하려면 에이전트 실행 기록에 sample-audit에 대한 Skill 호출이 있어야 하고, 이어서 같은 네 줄의 결과가 나와야 합니다. 마커만으로는 충분하지 않습니다.
이제 나머지 조건을 유지한 채 이 에이전트의 tools: 목록에서 Skill을 제거하세요. 정의에서 요구하는 도구를 더는 사용할 수 없으므로 호출 실패가 예상됩니다. 확인 후 Skill을 복구하세요. 이 실패 조건을 검사할 때 skills:를 추가하면 별도의 사전 로드 경로가 생기므로 추가하지 마세요.
이 명시적 테스트는 호출이 가능한지를 확인하며, Claude가 스스로 스킬을 선택하는지는 확인하지 않습니다. 자동 선택을 별도로 검사하려면 tools: Read, Skill은 유지하되 sample-audit를 직접 호출하라는 지침을 제거한 새 에이전트 정의를 만드세요. 설명도 Audit local CSV files처럼 중립적으로 작성합니다. 스킬 이름 없이 일반적인 감사 작업을 주고 Skill 호출이 발생하는지 확인하세요. 명시적 호출은 되지만 이 자동 선택 검사만 되지 않는다면 스킬 설명과 작업의 관련성을 살펴봅니다. 명시적 호출의 성공이 자동 선택을 증명하지는 않습니다.
4. 호출 제어와 실행 권한 확인하기
일회용 예제에서 아래 변경을 하나씩 적용하고, 매번 원래 설정으로 복구하세요.
| 한 번에 바꿀 항목 | 예상되는 차이 | 해결 방향 |
|---|---|---|
스킬에 disable-model-invocation: true 추가 | 모델의 동적 호출과 사전 로드 모두 이 스킬을 사용하지 않아야 함 | 의도적으로 수동 실행하는 워크플로에서는 이 설정을 유지하고, 실험에는 모델이 호출할 수 있는 적절한 스킬을 사용 |
대신 user-invocable: false 추가 | 수동 명령을 숨기지만, 그 자체로 모델 호출을 금지하지는 않음 | 메뉴에 없다는 사실을 모델도 사용할 수 없다는 뜻으로 해석하지 않기 |
동적 에이전트의 명시적 도구 목록에서 Skill 제거 | 동적 경로를 사용할 수 없음. 사전 로드 에이전트와는 별개 | 동적 호출이 필요한 곳에서만 Skill을 노출 |
| 입력 파일 접근 권한 제거 | 지침은 있어도 데이터 읽기가 실패할 수 있음 | 해당 파일·도구의 권한이나 위치 수정 |
두 호출 플래그의 목적은 다릅니다. 스킬 호출 주체 제어 문서(영문)를 참고하세요. 배포나 파괴적 작업 스킬을 의도적으로 수동으로 제한했다면, 에이전트가 자동으로 사용하게 만들기 위해 그 설정을 제거하지 마세요.
도구가 목록에 있다는 사실은 모든 사용이 허용된다는 뜻이 아닙니다. Claude Code 권한 규칙(영문)에서 거부 규칙, 관리 정책, 정확한 스킬 이름에 적용된 규칙을 확인하세요. 스킬의 allowed-tools는 에이전트 도구 집합에서 제외된 도구를 복구하거나 거부 규칙을 무효화할 수 없습니다. 실제 스킬이 Python 스크립트를 호출한다면 먼저 지침 로드를 확인한 후 Bash와 스크립트 경로를 조사하세요. 이 예제의 감사 작업에는 Read만 필요하므로 그 추가 변수를 없앨 수 있습니다.
진단을 위한 해결책으로 bypassPermissions를 사용하지 마세요. 조사하려는 조건을 바꾸며, 세 줄을 읽기만 하는 예제에는 필요하지 않습니다.
5. 디렉터리와 이름 문제 해결하기
스킬을 전역 개인 디렉터리로 옮기기 전에 프로젝트부터 확인하세요.
pwd
claude --version
ls -l .claude/skills/sample-audit/SKILL.md
ls -l .claude/agents/audit-preloaded.md
ls -l .claude/agents/audit-dynamic.md
에이전트 파일과 스킬 파일은 역할과 디렉터리가 다릅니다. .claude/agents/의 파일은 본문에 “skill”이라는 단어가 있다고 스킬이 되지 않습니다. 이 예제에서는 폴더 이름, frontmatter 이름, 사전 로드 항목을 동일하게 유지하세요. skills: 목록에 파일 시스템 경로나 /sample-audit를 넣으면 안 됩니다.
모노레포의 packages/web/.claude/skills/에 있는 스킬은 루트의 스킬과 같지 않습니다. 중첩 디렉터리의 스킬 검색은 Claude가 어느 영역에 접근하는지에 따라 달라집니다. 먼저 예제를 프로젝트 루트에 두어 이 불확실성을 없앤 후 실제 하위 디렉터리를 다시 적용하세요. 예상과 다른 지침이 실행된다면 개인·프로젝트 스킬의 이름 충돌과 플러그인 네임스페이스를 확인합니다. 공식 스킬 검색 및 이름 규칙(영문)은 어떤 출처가 우선하는지 설명합니다. 모든 스킬을 전역으로 옮기면 기존 문제 대신 새로운 충돌을 만들 수 있습니다.
파일이 ../shared/.claude/skills/sample-audit/SKILL.md에 있다면 claude --add-dir ../shared로 시작하고 새 세션에 스킬이 나타나는지 확인하세요. permissions.additionalDirectories만 설정하면 파일 접근은 허용되지만 해당 폴더의 스킬은 로드되지 않습니다. 중첩 스킬은 그 스킬이 속한 하위 디렉터리에서 시작하거나, 지원 버전에서 /add-dir을 사용한 뒤 이름을 지정해 다시 호출하세요. 버그 보고서에 시작 디렉터리와 --add-dir 인수를 기록합니다. 보조 파일의 상대 경로가 스킬 디렉터리 기준인지 작업 디렉터리 기준인지도 구분하세요. 이 예제의 sample.csv는 명시적으로 후자를 사용합니다.
세션 시작 후 최상위 skills 디렉터리를 만들었다면 스킬이 보이지 않는 다른 원인을 조사하기 전에 세션을 다시 시작하세요. 이 예제는 의도적으로 파일 생성 후 새 세션을 시작합니다.
6. 최소 예제도 실패할 때 증거 수집하기
현재 CLI 레퍼런스(영문)에 따라 비공개 디버그 파일을 사용하는 새 로컬 세션을 시작하세요.
claude --debug-file ./claude-skill-debug.log
한 가지 변형만 재현하세요. 선택된 에이전트, 실제로 해석된 스킬 이름, 스킬 없음·비활성화 경고, 동적 경로의 Skill 호출, 거부된 Read 또는 Bash 작업을 확인합니다. 로그에는 경로, 프롬프트, 다른 세션 데이터가 포함될 수 있으므로 공유 전에 검토하세요. 인증 정보나 관련 없는 대화 기록을 공개하면 안 됩니다.
아래 보고서 템플릿을 사용하세요. 버전과 OS, 모델과 공급자, 작업 위치, 정의, 검사 경로, 예상 결과와 실제 결과를 기록합니다.
Claude Code version / OS:
Model / provider (no secrets):
Working directory / repository root:
Agent name and definition:
Skill name, path and frontmatter:
Route: preload OR dynamic invocation
Exact prompt and synthetic input:
Expected result / actual result:
Selected-agent evidence / relevant tool call or warning:
Single change made / result after restoring baseline:
시작, 인증, TLS, 요청 제한 오류는 이 감사로 스킬 동작을 확인하기 전 단계에서 발생합니다. 해당 증상은 Claude Code TLS 오류 가이드(영문)나 요청 제한 문제 해결 가이드(영문)에서 조사하세요. 거부된 모델 요청을 반복해도 사전 로드 이름의 오타는 수정되지 않으며, 스킬을 편집해도 인증서 오류는 해결되지 않습니다.
context: fork, SDK, Ofox에서는 어떻게 구분할까?
context: fork가 있는 스킬은 스킬의 작업을 수행할 에이전트를 시작합니다. skills:가 있는 에이전트는 자체 지침에서 시작하고 추가 스킬 내용을 전달받습니다. 워크플로에 맞는 방향을 선택하세요. 두 frontmatter 설정을 서로 대체할 수는 없습니다. 서브에이전트에서 스킬 실행하기(영문)를 참고할 수 있습니다.
여기서 사용하는 사용자 정의 에이전트가 부모와 나눈 모든 대화를 전달받는다고 가정하지 마세요. 필요한 작업 입력을 명시적으로 전달해야 합니다. Claude Code 문서는 다른 fork 동작도 설명하므로, 이 예제의 격리 방식을 모든 에이전트나 대화 fork에 일반화하면 안 됩니다.
Claude Agent SDK로 시작한다면 SDK 스킬 문서(영문)에서 파일 시스템 설정과 Skill 도구 설정을 따로 확인하세요. 터미널 세션이 로컬 스킬을 찾았다고 해서 다른 디렉터리에서 시작한 SDK 프로세스도 같은 설정을 로드한다는 뜻은 아닙니다.
이미 Ofox를 통해 Claude Code를 연결했다면 연결 설정은 Claude Code 연동 문서, API 실패는 오류 처리 레퍼런스를 확인하세요. 공급자 연결과 로컬 스킬 로드는 별도로 검사해야 합니다. API 엔드포인트 변경 자체가 Claude 계정 기능을 열어 주거나 로컬 에이전트 정의를 수정해 주지는 않습니다.
완료 기준은 구체적으로 정하세요. 의도한 에이전트가 시작되고, 원하는 로드 경로가 확인되며, 네 줄의 출력이 예제와 일치하고, 대응하는 실패 조건에서는 다른 동작이 나타나야 합니다. 이 기록을 남긴 후 실제 워크플로를 다시 구성하세요.


