Agent Skills가 작동하지 않는 이유는? 2026년 Claude Code 스킬 트리거 및 권한 문제 해결

작업 요청에 맞는 Skill 파일을 넣었는데도 Claude Code가 아무 반응을 하지 않거나 도구 호출 단계에서 멈춥니다.

가장 빠른 해결책은 Agent Skills가 작동하지 않는 원인을 모델 문제가 아니라 발견, 트리거, 실행 실패로 나누고, 최소 Skill로 각 단계를 따로 확인하는 것입니다. 디렉터리를 먼저 고친 뒤 설명문과 로그를 검증하고, 마지막에 도구 권한과 프로젝트 신뢰 범위를 복원해야 합니다. 처음부터 클라이언트를 다시 설치하거나 플러그인을 모두 바꾸는 방법은 권하지 않습니다.

이 글은 Claude Code 스킬이 호출되지 않는 개발자를 위한 글입니다. 팀 저장소에 사용자 정의 Skill을 넣는 엔지니어는 신뢰 경계와 버전 회귀 부분을, 원격 맥이나 클라우드 개발 환경을 관리하는 담당자는 작업 공간과 권한 부분을 우선 확인하면 됩니다.

먼저 실패 지점을 세 가지로 나눕니다

Agent Skills 문제는 다음처럼 보이는 증상만으로 판단하면 안 됩니다.

• 발견 실패: Skill 목록에 이름이나 설명이 나타나지 않습니다.
• 트리거 실패: 목록에는 보이지만 요청 문맥과 설명이 맞지 않아 호출되지 않습니다.
• 실행 실패: Skill 본문은 읽었지만 파일 읽기, 파일 수정, 셸 명령 또는 MCP 도구 호출에서 중단됩니다.

이 구분은 복구 순서를 바꿉니다. 발견 실패라면 모델의 추론 능력이나 프롬프트를 고칠 일이 아닙니다. 프로젝트 위치와 파일 형식을 먼저 봐야 합니다. 실행 실패라면 Skill이 설치되지 않은 것이 아니라 현재 세션의 권한이나 작업 공간이 제한된 것일 수 있습니다.

공식 Agent Skills 규격은 Skill의 기본 구조와 메타데이터 규칙을 정의합니다. Claude Code의 공식 Skills 문서도 지원되는 로딩 위치와 사용 방식을 별도로 설명하므로, 커뮤니티 글의 경로를 그대로 복사하기보다 현재 문서를 기준으로 확인해야 합니다.

Claude Code가 Agent Skills를 인식하지 못하는 가장 흔한 이유는 무엇인가요?

대부분은 지원되는 프로젝트 위치 밖에 파일을 두었거나, SKILL.md의 이름과 앞부분 형식이 규격과 다르거나, 실행 중인 프로젝트 루트와 Skill이 들어 있는 저장소 루트가 서로 다른 경우입니다. 이 단계에서는 설명문을 길게 고치거나 모델을 바꾸지 말고, 파일이 실제로 현재 작업 공간에 전달되었는지부터 확인합니다.

첫 단계: 최소 Skill로 발견 여부를 확인합니다

복잡한 자동화 Skill은 권한과 외부 도구를 함께 사용하므로 최초 진단에 적합하지 않습니다. 테스트용 Skill은 설명문을 짧게 만들고, 본문에서는 특정 문구를 반환하는 정도로 제한합니다. 파일 수정, 셸 실행, 네트워크 접근을 넣지 않는 편이 좋습니다.

점검 순서는 다음과 같습니다.

• [ ] 프로젝트 루트에서 지원되는 Skill 디렉터리 위치를 확인합니다.
• [ ] 디렉터리 안에 SKILL.md가 정확한 대소문자로 존재하는지 확인합니다.
• [ ] 하위 폴더를 여러 겹 만들지 않고, 규격에 맞는 한 단계 구조로 배치합니다.
• [ ] YAML 앞부분의 구분선과 필드 형식을 확인합니다.
• [ ] 설명문과 본문을 분리하고, 설명문에 Skill이 처리할 작업을 구체적으로 적습니다.
• [ ] Claude Code를 다른 폴더에서 실행하고 있지 않은지 확인합니다.
• [ ] Skill 목록에 이름과 설명이 표시되는지 기록합니다.

Skill 파일이 보이지 않는다면 본문을 읽었는지 시험할 수 없습니다. 이때는 발견 계층에서 멈추고, 권한 설정으로 넘어가지 않는 것이 효율적입니다. 반대로 목록에 표시된다면 다음 단계에서 트리거를 분리해 확인해야 합니다.

Agent Skills의 SKILL.md는 어디에 두어야 하나요?

현재 프로젝트와 실행 방식에서 지원되는 Skill 위치에 두어야 합니다. 일반적인 예시를 무조건 정답으로 사용하면 안 됩니다. 공식 문서가 안내하는 프로젝트 범위와 사용자 범위를 확인한 뒤, 실제로 에이전트가 열어 보는 작업 공간 안에 파일이 있는지 검증해야 합니다. 원격 저장소에서는 로컬 파일이 아니라 원격 작업 공간에 전달된 파일을 기준으로 판단합니다.

다음 단계: 설명문과 실제 호출을 분리해 시험합니다

설명문이 너무 넓으면 거의 모든 요청에 후보로 잡힐 수 있습니다. 반대로 특정 단어 하나에만 의존하면 자연스러운 요청에서 선택되지 않을 수 있습니다. 여러 Skill이 비슷한 설명을 갖고 있으면 서로 충돌해 원하는 Skill이 선택되지 않는 상황도 생깁니다.

재현 가능한 테스트 문장을 준비하면 트리거 실패를 빠르게 좁힐 수 있습니다.

• Skill의 핵심 작업을 직접 말하는 문장
• 같은 작업을 다른 표현으로 말하는 문장
• 관련은 있지만 Skill 범위 밖인 문장
• 두 Skill의 설명이 겹치는 문장

각 문장에서 먼저 Skill 이름과 설명이 후보로 나타나는지 기록합니다. 그다음 Skill 본문에 넣은 고유한 확인 문구가 실제 응답에 반영되는지 확인합니다. 후보로 보였다는 사실과 본문을 읽었다는 사실은 다릅니다. 전자는 발견 또는 선택 단계의 신호이고, 후자는 실제 로딩 신호입니다.

설명문에는 “모든 코딩 작업을 처리함”처럼 넓은 표현보다 입력, 대상 파일, 기대 결과를 적는 편이 낫습니다. 예를 들어 보안 점검 Skill이라면 코드 수정 자체가 아니라 특정 점검 보고서를 생성하는 작업이라고 범위를 제한해야 합니다. 단, 설명문을 정확히 썼다고 해서 Skill이 항상 자동 호출된다고 단정해서는 안 됩니다. 선택 여부는 현재 에이전트의 정책과 문맥 판단에 영향을 받습니다.

실행 단계: 도구 권한과 작업 공간을 따로 복원합니다

Skill이 호출된 뒤 실패한다면 Read, Write, Bash, MCP 도구를 한꺼번에 열지 말고 필요한 권한만 단계적으로 추가합니다.

• 파일 목록과 본문을 확인하는 데 실패하면 Read 범위를 봅니다.
• 결과 파일을 만들 때 멈추면 Write 대상 경로와 승인 절차를 확인합니다.
• 테스트 명령이 실행되지 않으면 Bash 허용 범위와 현재 셸을 확인합니다.
• MCP 서버가 응답하지 않으면 서버 연결, 도구 이름, 세션 권한을 분리해 확인합니다.

권한은 단순한 설정 문제가 아니라 신뢰 경계입니다. 공식 Claude Code 권한 문서는 도구 사용 승인과 제한을 다루므로, 작업 환경에 맞는 허용 범위를 문서와 대조해야 합니다. MCP를 함께 사용한다면 MCP 개발 문서에서 현재 SDK의 도구 호출 방식을 확인해야 합니다.

로컬 프로젝트에서는 현재 폴더와 버전 관리 상태가 핵심입니다. 원격 저장소에서는 클론 뒤의 실제 루트, 인증된 계정, 생성된 환경 변수, 무시된 파일을 확인해야 합니다. 클라우드 작업 공간에서는 초기화 스크립트가 .claude 디렉터리를 덮어쓰거나, 보안 정책이 셸과 외부 연결을 막을 수 있습니다.

주의: 제삼자 저장소의 Skill은 설명문만 읽고 신뢰하면 안 됩니다. 파일 삭제, 비밀값 접근, 외부 전송, 광범위한 셸 명령이 포함될 수 있으므로 출처와 변경 이력을 먼저 검토하고 별도 테스트 프로젝트에서 실행해야 합니다.

공식 도구 설명과 안전한 에이전트 운영 기준은 관리형 Agent 도구 안내에서도 확인할 수 있습니다. 저장소에 Skill을 배포할 때는 실행 권한보다 먼저 읽기 범위와 민감한 파일 제외 규칙을 정하는 편이 안전합니다.

Agent Skills가 트리거되었지만 도구를 읽지 못할 때는 어떻게 하나요?

먼저 Skill 본문이 요구하는 도구 이름과 실제 세션에서 허용된 도구 이름이 같은지 확인합니다. 그다음 동일 요청을 읽기 전용 테스트로 실행합니다. 읽기는 되지만 쓰기나 셸만 실패한다면 설치 문제가 아니라 권한 차이입니다. 원격 환경에서는 프로젝트가 올바르게 마운트되었는지, 심볼릭 링크가 끊기지 않았는지, 작업 디렉터리가 예상 경로인지도 확인해야 합니다.

팀 배포 전에는 승인과 되돌리기를 함께 설계합니다

팀 저장소에 Skill을 넣을 때는 “목록에 보인다”만으로 승인하지 않습니다. 다음 항목을 통과해야 운영 저장소에 배포할 수 있습니다.

• [ ] 최소 테스트 프로젝트에서 Skill이 발견됩니다.
• [ ] 대표 요청과 표현을 바꾼 요청에서 트리거 결과를 기록합니다.
• [ ] 본문 로딩과 도구 호출을 서로 다른 로그로 확인합니다.
• [ ] 읽기, 쓰기, 셸, MCP 권한을 필요한 범위로 제한합니다.
• [ ] 민감한 파일과 비밀값에 접근하지 않는지 검토합니다.
• [ ] 승인 없이 실행되면 안 되는 작업을 별도로 표시합니다.
• [ ] 변경 전 버전을 저장하고 즉시 되돌릴 경로를 마련합니다.
• [ ] 원격 맥이나 클라우드 작업 공간에서 같은 테스트를 다시 실행합니다.

Codex나 OpenCode에서도 같은 분류법을 적용할 수 있지만, Skill 발견 위치와 플러그인 동작은 각 Agent의 공식 문서와 현재 버전에 따라 달라질 수 있습니다. 따라서 Claude Code에서 확인한 경로를 다른 Agent에 그대로 복사하지 말고, 해당 환경의 로딩 규칙과 권한 모델을 별도로 검증해야 합니다.

장기 운영에서는 운영 코드 저장소와 Skill 검증용 저장소를 분리하는 편이 안전합니다. Skill을 갱신할 때마다 운영 브랜치에서 바로 실행하지 말고, 고정된 테스트 프로젝트에서 발견, 트리거, 실행, 되돌리기를 확인한 뒤 배포합니다. 원격 맥을 임시 검증 환경으로 쓰는 경우에는 맥 미니 원격 사용 안내처럼 접속 방식과 작업 공간을 먼저 정리하고, 여러 사용자가 접근하는 환경이라면 도움말 센터의 운영 절차도 함께 확인하는 것이 좋습니다.

마지막 점검: 어떤 환경을 선택할지 비교합니다

선택지	발견 문제를 찾기 좋은 조건	권한과 신뢰 경계	운영상 판단
개인 맥	프로젝트 루트와 파일을 직접 확인할 수 있음	사용자가 대부분의 권한을 통제함	단일 개발자와 초기 재현에 적합합니다
원격 맥	깨끗한 테스트 프로젝트를 반복 생성할 수 있음	접속 계정, 마운트, 셸 권한을 함께 확인해야 함	로컬 환경과 다른 실패를 재현하기 좋습니다
클라우드 작업 공간	팀별 환경을 일정하게 만들 수 있음	정책, 비밀값, 네트워크, 도구 승인이 복합적으로 작동함	다중 사용자 운영과 회귀 관리에 적합합니다
운영 저장소에 즉시 배포	별도 검증 없이 바로 사용함	고권한 Skill이 코드와 비밀값에 접근할 위험이 큼	검증 전에는 피해야 합니다

Agent Skills가 작동하지 않는 상황에서 가장 효율적인 순서는 파일 위치 확인, 최소 Skill 발견 확인, 설명문 기반 트리거 시험, 본문 로딩 기록, 도구 권한 복원, 원격 환경 회귀 시험입니다. 이 순서를 지키면 모델을 교체하거나 전체 플러그인을 재설치하지 않고도 어느 계층에서 문제가 생겼는지 좁힐 수 있습니다.

현재 로컬 맥은 빠르게 확인할 수 있지만 사용자별 설정과 설치 상태가 달라 팀 재현성이 약할 수 있습니다. 반대로 클라우드 작업 공간은 권한 정책과 마운트 문제가 늘어나 초기 설정이 복잡하고, 운영 코드에 바로 연결하면 실패 범위가 커집니다. 원격 맥은 실제 개발 도구와 파일 구조를 유지하면서 깨끗한 검증 환경을 반복하기 쉬우므로, 임시 테스트나 원격 AI 코딩 에이전트 검증에는 균형 잡힌 선택이 될 수 있습니다. 여러 사용자가 같은 권한 정책과 회귀 절차를 장기간 운영해야 할 때만 클라우드 환경으로 확장하는 판단이 적절합니다. 필요하다면 Zutcloud의 원격 맥 이용 환경에서 최소 Skill을 재현한 뒤 팀 배포 여부를 결정하는 편이 안전합니다.