Codex 검증 스크립트를 Claude Code Skill로 전환하기

지난 글에서 Claude Code의 Stop 훅 + Codex CLI로 자동 코드 검증 파이프라인을 만들었는데,
다 해놓고 보니 한 가지 문제가 남았다.

이 세팅을 다른 프로젝트에서도 쓰고 싶은데, 프로젝트마다 .claude/hooks/codex-verify.sh를 복붙해야 하나 싶은 것.

Skills가 뭔데

Claude Code에는 Skill이라는 기능이 있다.
간단히 말하면 SKILL.md 파일 하나로 Claude에게 새로운 능력을 가르치는 것.
~/.claude/skills/에 넣어두면 어떤 프로젝트에서든 자동으로 인식한다.

원래는 "브랜드 가이드라인을 적용해줘" 같은 프롬프트 템플릿 용도가 많은데, 스크립트도 포함할 수 있어서 검증 자동화에도 딱이었다.

왜 전환했나

프로젝트 로컬 방식의 문제:

• 새 프로젝트를 만들 때마다 .claude/hooks/codex-verify.sh를 복사해야 함
• docs/PROJECT_RULES.md, AGENTS.md도 매번 새로 작성
• 스크립트를 개선하면 기존 프로젝트들도 다 수정해야 함

글로벌 Skill로 바꾸면:

• 스크립트가 ~/.claude/skills/에 하나만 있으면 됨
• 프로젝트에 docs/PROJECT_RULES.md가 있으면 그걸 쓰고, 없으면 기본 규칙으로 동작
• 스크립트 개선하면 모든 프로젝트에 즉시 반영

Skill 구조

~/.claude/skills/codex-reviewer/
├── SKILL.md                    # 스킬 설명 + 세팅 가이드
├── scripts/
│   └── codex-verify.sh         # 검증 스크립트 (글로벌)
└── references/
    └── review-rules.md         # 기본 검증 규칙 (폴백용)

핵심은 codex-verify.sh의 규칙 로딩 부분:

# Load project rules (project > skill default)
if [ -f "docs/PROJECT_RULES.md" ]; then
  RULES=$(cat docs/PROJECT_RULES.md)
elif [ -f "$SKILL_DIR/references/review-rules.md" ]; then
  RULES=$(cat "$SKILL_DIR/references/review-rules.md")
fi

프로젝트 규칙이 있으면 우선, 없으면 Skill 내장 기본 규칙으로 폴백.
AGENTS.md도 마찬가지로 있으면 읽고 없으면 넘어간다.

전환 과정

매우 간단하다.

Skill 디렉토리를 ~/.claude/skills/codex-reviewer/에 배치하고,
프로젝트의 .claude/settings.local.json에서 훅 경로를 글로벌 경로로 바꾸고,
기존 프로젝트 안에 있던 스크립트를 삭제.
이 세 단계가 전부다.

기존 docs/PROJECT_RULES.md, CLAUDE.md, AGENTS.md는 건드릴 필요 없다.
스크립트 위치만 프로젝트 안에서 글로벌로 옮긴 것뿐이니까.

새 프로젝트에서는?

Skill은 스크립트를 글로벌로 관리해주는 것이고, Stop 이벤트에서 실행되게 하려면 훅 등록은 별도로 필요하다.

프로젝트마다 .claude/settings.local.json에 이걸 추가하는 방법이 있다:

json{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/skills/codex-reviewer/scripts/codex-verify.sh"
          }
        ]
      }
    ]
  }
}

근데 이것도 프로젝트 만들 때마다 넣어야 하니까 귀찮다.
나는 그냥 글로벌 설정(~/.claude/settings.json)에 훅을 걸어버렸다.
어차피 스크립트가 git diff에 실패하면 exit 0으로 스킵하니까, git 레포가 아닌 곳에서 돌아가도 문제없다.

이렇게 하면 새 프로젝트를 만들어도 훅 설정을 건드릴 필요가 없다.
docs/PROJECT_RULES.md를 만들면 프로젝트 맞춤 검증, 안 만들면 기본 규칙으로 검증이 돌아간다.

---

Skill이라는 게 생각보다 확장성이 넓어보여 다양한 시도를 해보려고 한다.
코드 검증 말고도 커밋 메시지 자동 생성이라든지, 프로젝트 초기 세팅 자동화라든지, 활용할 수 있는 영역이 꽤 많아 보인다.
다음엔 좀 더 다양한 Skill들을 만들어봐야겠다.