Hook을 사용하여 Claude Skills를 Auto Trigger 구현하기

블로그에 정말 오래간만에 글을 쓴다. AI 시대에 접어들면서 블로그에 진부한 코드 레퍼런스를 작성하는 것은 무의미하다는 것을 느끼기에 한동안 게을러진건 사실이다. 하지만 이 글 또한 언젠가 AI가 수집할 정보의 일부분이라 생각하며 다른 사람에게 도움이 될꺼라 생각하여 글을 작성한다. 각설하고 내용은 이렇다.

 

도입 발단

Skills 이름과 설명에 작성한 키워드를 Claude Code에 입력해도 반응이 없었으며,  Trigger 대상 파일을 수정해도 자동으로 실행되지 않는 문제가 빈번히 발생한다. 왜일까?

이 문제를 해결하기 위해 특정 블로그 로그 저자가 개발한 일부 문서들을 참고하여 내 업무 방식에 맞게 빠르게 도입해보기로 했다.

 

Auto Trigger 작동 메커니즘

내가 이렇게 먼저 생각했다는건 아니다. 어떤 메커니즘으로 Skills을 잘 실행할 수 있었는지 조사해보고 검토한 내용이다. Skills의 description만으로는 Claude가 100% 자동 실행을 보장하지 못하기 때문에,  저자는 Hook이라는 명시적 강제 메커니즘을 활용한다.

주요 핵심 포인트는 Hook 처리시 입력된 프롬프트에서 키워드와 패턴을 추출하여 조건을 매칭하고,  이를 통해 조건을 만족하는 Skill을 자동으로 활성화하는 방식으로 문제를 해결하는 것으로 파악할 수 있었다.

 

Auto Trigger를 .claude 환경에 적용하기 전 고민 사항

Auto Trigger (skill-developer) 원본 소스 문서를 커스터마이징하지 않고 ~/.claude/skills에 그대로 추가하기로 결정했다. Why?

• 스킬에 관한 사양서 (skill-rules.json 등)에 대한 정형화 파일의 사양서가 이미 잘 정의되어 있었음.
• hook 관련 실행 파일은 TypeScript로 구현되어 있었지만 내게 익숙한 Python 언어로 컨버팅 하는 처리는 기본 레이어 위에 덮어 씌우기만하면 되는것이였음.
• 새로운 skills를 추가하면 skill-rules.json에 업데이트해야 하는 부분이 상호 간의 처리와 함께 모두 이미 포함되어 있었음.
• 기존에 만들었던 skills 내용 변경없이 skills trigger 하는 처리 부분만 적용하고 싶었음. 최소한의 변경으로 최대의 효율성 달성하고 싶었음.

→ 이미 잘 설계된 Auto Trigger (skill-developer)를 재구성하지 않고  ~/.claude/skills에 그대로 통합하고 기존 메커니즘을 활용하는 것이 더 효율적이라고 판단되었음.

 

 

.claude 환경에 적용한 구현 과정

1. skill-developer 스킬 복사

skill-developer (skill 생성 및 환경 구성 스킬)의 해당 소스만 .claude/skills 내 디렉토리에 복사한다. 

.claude
├── skills
│   ├── <생략>
│   └── skill-developer

 

2. commands 내 build-skill-env.md 파일 생성

Skills로 구현할지, Commands로 구현할지 고민하였지만 환경 구성 자체는 skill-developer에 이미 잘 정의되어 있었고,  그 위에 추가 기능만 필요한 상황이었음. 
특히 환경 구성은 선택이 아닌 필수 작업으로 명시적으로 반드시 실행되어야 하기때문에. 환경 구성의 필수성을 고려하여 Commands로 구현하기로 결정함.

.claude
├── commands
│   ├── <생략>
│   └── build-skill-env.md

당신은 사용자가 생성한 Claude Skill가 잘 발동되도록 환경을 구성해주는 AI 비서입니다.
 
# Skill Developer 문서 확인
[Skill Developer 문서](./../skills/skill-developer): 디렉토리 안의 md 확장자 파일을 전부 참고하여 사양서를 확인해주세요.
 
# 프로세스
## 다음 경로로 이동해서 작업을 진행해주세요.
```bash
$ cd ~/.claude
```
## 현재 구성되어 있는 파일 및 디렉토리를 정확하게 경로까지 확인해야합니다. 
```bash
$ ls -al ~/.claude/skills/skill-rules.json
```
## hook 실행 언어
- hook을 실행할 파일은 *.ts 파일이 아닌 *.py 파이썬으로 생성해야합니다.
## 환경 구성 확인사항:
- [ ] ~/.claude/skills/skill-rules.json 생성 확인
- [ ] ~/.claude/settings.json 에 hook 설정 확인
- [ ] ~/.claude/hook/*.sh 쉘 실행 파일 확인
- [ ] ~/.claude/hook/*.py 트리거 실행 파일 확인

 

3. build-skill-env 명령어 실행

claude code를 실행하고 /build-skill-env 명령어로 실행하여 Skills Auto Trigger환경을 구성하도록 실행함.

▐▛███▜▌   Claude Code v2.0.32
▝▜█████▛▘  Sonnet 4.5 · Claude Max
  ▘▘ ▝▝    /Users/yscho02
 
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
> /build-skill-env
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  /build-skill-env     당신은 사용자가 생성한 Claude Skill가 잘 발동되도록 환경을 구성해주는 AI 비서입니다. (project, gitignored)

 

Auto Trigger 환경 구성  완료함.

⏺ 완벽합니다! Claude Skill 환경 구성이 성공적으로 완료되었습니다.
 
  환경 구성 완료 요약
 
  다음 항목들이 모두 성공적으로 완료되었습니다:
 
  1. skill-rules.json 파일 생성
 
  - 위치: ~/.claude/skills/skill-rules.json
  - 8개의 skill 정의 포함:
    <생략>
  - 각 skill에 대한 trigger 패턴 (keywords, intentPatterns) 설정 완료
 
  2. Hook 디렉토리 구조 및 파일 생성
 
  - 디렉토리: ~/.claude/hook/
  - Python 실행 파일: skill-activation-prompt.py (실행 권한 부여됨)
  - Shell wrapper 파일: skill-activation-prompt.sh (실행 권한 부여됨)
 
  3. settings.json에 Hook 설정 추가
 
  - UserPromptSubmit hook이 정상적으로 등록됨
  - Python 기반 hook 실행 설정 완료
 
  4. 환경 구성 테스트
 
  - 다양한 키워드로 테스트 완료:
    - <생략>
  - skill-rules.json JSON 유효성 검증 완료
 
  모든 환경 구성이 완료되었으며, Claude Skill 시스템이 정상적으로 작동할 준비가 되었습니다.

 

4. 생성된 Auto Trigger 구성 파일 확인

.
├── CLAUDE.md
├── commands
│   └── build-skill-env.md
├── hook
│   ├── skill-activation-prompt.py
│   └── skill-activation-prompt.sh
├── skills
│   ├── # ...<생략>
│   ├── skill-developer
│   └── sskill-rules.json
└── settings.json

 

5. Auto Trigger 환경 구성 완료 후 skills 테스트

Hook이 제대로 실행되는지 확인하기 위해 hook.log를 남기도록 아래와 같이 settings.json을 설정한다.

# .claude/settings.json
{
  /* <생략>
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",            
             "command": "bash /Users/yscho02/.claude/hook/skill-activation-prompt.sh >> /Users/yscho02/.claude/logs/hook.log 2>&1"          
          }
        ]
      }
    ]
  }
}

 

 skills이 잘 발동하는지 실행해보기

▐▛███▜▌   Claude Code v2.0.32
▝▜█████▛▘  Sonnet 4.5 · Claude Max
  ▘▘ ▝▝    /Users/yscho02/workspace/test-api
 
> 해당 프로젝트에서 변경된 파일의 python import 구문을 체크해줘
 
⏺ 프로젝트에서 변경된 파일의 Python import 구문을 체크하겠습니다.
 
> The "checking-import-packages" skill is running

 

/.claude/logs/hook.log 파일 확인

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
SKILL ACTIVATION CHECK
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
RECOMMENDED SKILLS:
  → checking-import-packages (priority: high)
 
ACTION: Use Skill tool BEFORE responding
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

 

이렇게 구현함으로써 이전에 자연어로 CLAUDE.md에 정의해서 사용했던 방법보다 skills가 잘 동작하였으며, skills를 올바른 사용법이나 자동화 방안에 대해 더 고민하는 계기가 되었다.