Claude Code v2.1.287로 정리하는 Skill, MCP, Mods의 차이점과 첫 Mod 구동 절차

Claude Code에 디렉토리 청소를 요청하면 삭제 명령어 전에 확인 다이얼로그가 나타납니다. 하지만 어떤 파일이 지워지는지는 표시되지 않습니다. 이 '판단 전'에 개입할 수 있도록 하는 것이 2026년 10월 1일에 발표된 Mods입니다. 본고는 공식 발표와 문서를 기반으로 (2026-10 시점, v2.1.287 이상 대상) Skill, MCP, Mods의 역할 차이를 정리하고, 첫 Mod를 구동하는 절차를 요약합니다. 필자는 미검증이므로 실제 동작은 본인의 버전을 우선해 주십시오.

Skill: 모델에게 보여주는 조작 매뉴얼입니다. 방법을 알려주지만, 실행을 멈출 수는 없습니다. -
MCP: 데이터베이스, API, 브라우저를 연결하는 외부 레이어입니다. 도구는 늘어나지만, 판단의 흐름은 변하지 않습니다. -
Mods: Claude Code 내부 이벤트에 걸리는 TypeScript 함수입니다. 툴 호출(tool calling), 프롬프트(prompt), 모델 요청(model request), UI에 대해 관측(observe), 수정(rewrite), 차단(block) 세 가지가 가능합니다.

공식 정의: "Claude Code의 작동 방식을 변경하는 작은 TypeScript 함수". 플러그인으로 배포 및 설치되며, CLI와 데스크톱 앱 모두에서 동작합니다.

세션 1: Claude에게 작성시키기.

요청 문구:
"현재 git 브랜치를 입력 상단에 표시하는 Mod를 만들어줘"
흐름:
...

세션 2: 한 줄 수정하기.

표시 내용을 브랜치 이름에서 '이 세션의 툴 호출 횟수'로 변경하여 저장합니다. 턴 종료 시 반영됩니다. Node.js도, 번들러도 필요 없고, .js / .ts가 직접 로드됩니다.

tool.call: 툴 실행 전에 개입할 수 있습니다. deny를 반환하면 그 이유가 툴 결과로 Claude에게 읽힙니다. 인자 수정이나, 원래 툴을 무시하고 자체 결과를 반환하는 것도 가능합니다. -
prompt 계열: 전송 전 입력 수정, 시스템 프롬프트의 섹션 단위 대체/삭제. -
turn.step: 모델 요청 직전에 model 필드를 변경할 수 있습니다 (문서상의 능력. 태스크별 라우팅의 공식 샘플은 아직 없습니다). -
ui.render: 사이드 패널이나 입력 상단 바, 툴 행 또는 스피너 그려짐을 대체합니다.

핸들러는 on(event, matcher, handler)로 등록하며, ($, e, next)의 미들웨어 체인으로 동작합니다. next(e)로 관측하고, next({...e})로 수정하며 (이벤트는 불변), next를 호출하지 않고 결과를 반환하면 차단합니다.

anthropics/claude-code 리포지토리의 mods/ 디렉토리에는 4개의 내장 Mod가 있습니다: diff(/diff 명령어), agents-md (AGENTS.md 지원, 기본 claude-md-or-agents-md), telemetry, sec-default. 일상적으로 사용하는 기능들이 이 메커니즘으로 구현되어 있습니다.

공식 발표 원문: "Mods run with the same access to your machine as Claude Code itself. They aren’t sandboxed." 로드된 Mod는 사용자의 권한으로 파일이나 환경 변수(API 키 포함)를 읽고, 모든 prompt를 보고, 툴 호출을 대리 승인하며, 할당량을 소모할 수 있습니다. 신뢰할 수 있는 출처에서만 도입하고, 도입 전에 등록 이벤트를 확인합시다 (공식 문서에 절차가 있습니다).

• 모델 라우팅 Mod 직접 제작 (공식 샘플 대기)
• 감사(Audit) Mod의 제로 베이스 구현 (공식 blast-radius 수정부터)
• Mod를 백업 용도로 사용하기