공식 스킬이 안 돌아간다
Claude Code에는 /security-review라는 공식 스킬이 있다.
코드 변경 사항을 분석해서 보안 취약점을 찾아주는 기능인데, 실행하면 이런 에러가 나온다.
fatal: ambiguous argument 'origin/HEAD...': unknown revision or path not in the working tree.이유는 단순하다. /security-review는 git diff origin/HEAD...로 변경된 파일을 비교하는 구조라서, git repo + remote가 설정된 환경에서만 동작한다.
문제는 내 워크스페이스 5개 중 4개가 git repo가 아니라는 거다.
로컬에서만 쓰는 폴더라 git을 안 붙였고, 그러다 보니 공식 보안 점검을 쓸 수가 없었다.
그래서 직접 만들었다
git 없이도 돌아가는 보안 점검 스킬을 만들기로 했다.
초점은 코드 취약점이 아니라 인프라 보안 — API 키 유출, gitignore 누락, MCP 서버 설정 같은 것들이다.
파일 하나 만들면 끝이다.
~/.claude/commands/security.md전역 경로에 넣었기 때문에 어떤 워크스페이스에서든 /security로 실행할 수 있다.
스킬이 점검하는 6가지
1. 민감 파일 탐색
.env, credentials.json, *.pem, *.key 같은 패턴을 워크스페이스에서 찾는다.
파일이 있으면 종류만 표시한다. 키 값은 절대 출력하지 않는다.
2. gitignore 점검
찾은 민감 파일이 .gitignore에 포함되어 있는지 확인한다. 워크스페이스 단위, 상위 폴더, 글로벌 세 곳을 다 본다.
3. git 추적 여부
이미 git에 올라간 민감 파일이 있으면 🔴 즉시 경고한다. .gitignore에 추가해도 이미 추적 중이면 소용없으니까.
4. MCP 서버 점검
.mcp.json에서 API 키가 직접 하드코딩되어 있는지, 아니면 외부 파일(.env)을 참조하는지 확인한다.
MCP 서버 index.js가 있으면 코드도 읽는다:
sanitizeError()— 에러 메시지에서 키가 새는지- 입력값 검증 — 길이 제한, 도메인 제한, 날짜 형식
- 시작 시 검증 — 환경변수 누락 시 안전 종료
5. 권한 범위
서비스 계정이 뷰어인지, 편집자인지 추론한다. 과잉 권한이면 경고.
6. npm 취약점
package.json이 있으면 npm audit으로 critical/high만 빠르게 확인한다.
실행하면 이렇게 나온다
## 보안 점검 결과 (2026-03-14)
### 민감 파일
| 파일 | 종류 | gitignore | git 추적 | 위험도 |
|---|---|---|---|---|
| .env | API Secret | ✅ | ❌ 미추적 | 🟢 |
| credentials.json | 서비스 계정 키 | ✅ | ❌ 미추적 | 🟢 |
### MCP 서버
| 서버 | 키 관리 | 위험도 |
|---|---|---|
| mcp-server-a | 외부 파일 참조 | 🟢 |
| mcp-server-b | 외부 파일 참조 | 🟢 |
| mcp-server-c | .env 참조 + sanitizeError | 🟢 |
### 전체 등급: 🟢 양호결과가 표로 나온다. 문제 있으면 🟡이나 🔴로 바뀌고, 조치 방법도 같이 나온다.
공식 vs 커스텀 — 역할이 다르다
| /security-review (공식) | /security (커스텀) | |
|---|---|---|
| 필요 환경 | git repo + remote | 아무 데서나 |
| 점검 대상 | 코드 변경 (XSS, 인젝션 등) | 인프라 (키, gitignore, MCP) |
| 실행 시점 | 커밋 후 | 언제든 |
| 용도 | PR 리뷰 | 환경 점검 |
둘 다 필요하다. 코드는 공식 스킬이 보고, 환경은 커스텀이 본다.
git repo인 워크스페이스에서는 둘 다 돌리면 된다.
만들면서 배운 것
스킬은 프롬프트다. 코드를 짜는 게 아니라 "이 순서로 이걸 확인해줘"를 마크다운으로 적는 거다.
frontmatter에서 쓸 수 있는 도구를 제한할 수 있다:
allowed-tools: Read, Grep, Glob, Bash이러면 스킬이 파일을 수정하거나 외부 API를 호출하는 건 막히고, 읽기 + 검색만 가능하다. 보안 점검 스킬이 파일을 고쳐버리면 곤란하니까.
전역 경로(~/.claude/commands/)에 넣으면 모든 워크스페이스에서 쓸 수 있고, 프로젝트 폴더(.claude/commands/)에 넣으면 해당 프로젝트에서만 쓸 수 있다.
실제로 잡아낸 것
5개 워크스페이스를 점검했더니:
.mcp.json이.gitignore에 빠진 워크스페이스 3개 발견- API Secret이
.env에 있는데 gitignore 미등록 → 즉시 추가 - MCP 서버 코드에
sanitizeError()미적용 → 보강
전부 10분 안에 조치 완료했다. 스킬 없이 이걸 하나하나 확인했으면 빠뜨렸을 거다.
핵심 정리
- 공식
/security-review는 git repo 전용 — 로컬 워크스페이스는 커버 못 한다 - 커스텀 스킬은 마크다운 파일 하나 — 코딩 아니고 지시문 작성이다
allowed-tools로 도구를 제한하면 안전하게 읽기 전용으로 만들 수 있다- 전역 경로에 넣으면 모든 워크스페이스에서
/security한 줄로 실행 가능
도구가 안 되면, 만들면 된다.
이 글은 Claude Code 플레이북을 만들면서 배운 것을 비개발자 시점으로 정리한 시리즈입니다.
