Claude 에이전트 입문 3: 설명서와 도구, 권한을 주는 법
Claude 에이전트 입문 · 3/5 · 공식 문서 확인: 2026년 9월 20일
Skill은 반복할 절차를 담고, 도구는 행동을 실행하며, 권한은 허용 범위를 정합니다. 세 가지를 구분하면 ‘지시를 잘 썼는데 왜 안 될까’를 진단할 수 있습니다. 이번 편에서는 안내문을 검사하는 Skill 파일을 직접 구성합니다.
Skill을 추가하면 무엇이 달라질까
Claude Code의 Skill은 이름과 설명이 붙은 재사용 지침입니다. 관련 자료와 스크립트를 함께 둘 수도 있습니다. 기본적으로 Claude가 상황에 맞는 Skill을 선택하거나 사용자가 이름으로 호출할 수 있습니다. 절차를 반복해서 설명할 필요가 줄어듭니다. 공식 문서: Skills
| 요소 | 안내문 검사에서 하는 일 |
|---|---|
| Skill | 원본과 비교할 항목·판정 방식 지정 |
| 파일 읽기 도구 | event.txt와 announcement.md 내용 읽기 |
| 권한 | 해당 파일 읽기·수정 등을 허용할지 결정 |
검사 Skill이 있어도 파일 읽기에 실패하면 검사를 마칠 수 없습니다. 반대로 파일을 읽을 수 있어도 검사 기준이 모호하면 ‘좋아 보입니다’ 정도의 평가만 나올 수 있습니다.
직접 만드는 안내문 검사 Skill
작업 폴더 안에 .claude/skills/check-announcement/SKILL.md를 만들고 아래 내용을 넣습니다. 처음의 --- 사이에는 이름과 설정을, 그 아래에는 수행할 절차를 적습니다.
---
name: check-announcement
description: 행사 원본과 안내문 초안을 대조한다.
disable-model-invocation: true
---
1. event.txt와 announcement.md를 읽는다.
2. 행사명, 일시, 장소, 정원을 각각 대조한다.
3. 원본에서 미정인 값이 초안에서 확정됐는지 확인한다.
4. 항목 | 원본 | 초안 | 판정 순서의 표로 보고한다.
5. 판정은 일치, 불일치, 확인 필요 중 하나로 표시한다.
6. 파일을 수정하거나 외부로 발송하지 않는다.name은 호출 이름, description은 용도 설명입니다. disable-model-invocation: true는 이 Skill을 사용자가 직접 호출할 때 실행하도록 정합니다. 파일을 준비한 뒤 Claude Code에서 /check-announcement를 입력합니다. 공식 문서: 호출 방식 제어
시험 방법: 연습용 초안의 정원만 20명에서 30명으로 바꿔 호출해보세요. 원본이 20명이면 ‘정원 | 20명 | 30명 | 불일치’가 나와야 합니다. 이 지침은 모델에게 검사를 시키는 방식이므로 매번 정확한 판정을 보장하는 검사 프로그램과는 다릅니다. 수치처럼 기계적으로 대조할 항목은 5편의 자동 검사로 연결할 수 있습니다.
마지막의 ‘수정하지 않는다’는 작업 지시입니다. 읽기만 가능하도록 실제 도구 목록을 제한하는 방법은 4편의 Subagent 예제에서 다룹니다.
MCP는 외부 도구를 연결할 때 사용한다
MCP는 AI 프로그램과 외부 도구·자료가 요청과 결과를 주고받는 규약입니다. 외부 일정 서비스의 자료를 읽으려면 해당 연결과 계정 인증이 필요합니다. MCP 연결을 추가했다고 모든 서비스에 접근할 수 있는 것은 아닙니다. 공식 문서: MCP
이번 실습의 두 파일은 Claude Code의 기본 파일 도구로 읽을 수 있어 MCP가 필요하지 않습니다. 일정이 외부 서비스에 있을 때 연결을 검토하면 됩니다. 외부 작업이 막혔다면 도구가 등록돼 있는지 → 인증이 유효한지 → 요청한 자료의 접근 권한이 있는지 순서로 확인하세요.
어디까지 자동으로 실행할지 정한다
권한은 작업의 결과에 맞춰 정합니다. 초안 검사는 파일 읽기, 초안 작성은 파일 저장, 참가자에게 보내기는 발송 도구가 필요합니다. 쓰지 않는 발송 기능까지 처음부터 연결할 필요는 없습니다.
Claude Code의 권한 규칙은 실행 환경이 적용합니다. Skill이나 대화에 ‘물어보고 보내라’고 적는 것과, 실제 도구 호출을 승인 대상으로 설정하는 것은 각각 확인해야 합니다. 공식 문서: 실행 권한
작업을 마친 뒤 확인할 세 가지: 호출한 Skill 이름, 실제로 읽은 두 파일, 불일치 항목이 포함된 결과 표입니다. 절차 이름만 추가한 상태와 그 절차가 실제 자료에 적용된 상태를 구분할 수 있어야 합니다.
시리즈 이어 읽기
- AI가 일을 끝내는 과정
- 기억과 작업 맥락
- 설명서·도구·권한 · 현재 글
- 보조 작업자와 협업팀
- 검증과 다음 작업의 개선