Field Log · Entry

[Claude Code] AI 에이전트 도구 설계 — Tool, Skill, Plugin, MCP의 차이와 SKILL.md 작성법 (4/8)

AI는 생각만 할 수 있습니다. 파일을 열거나, 코드를 실행하거나, GitHub 이슈를 가져오려면 도구라는 손발이 필요합니다. 그런데 도구 종류가 늘어나면서 헷갈리는 용어들도 같이 늘어납니다. Tool, Skill, Plugin, MCP. 무엇이 무엇이고, 어떤 순서로 도입해야 할까요?

결론부터 말하면, Tool → Skill → Plugin의 3계층으로 이해하고 외부 서비스는 **MCP(Model Context Protocol)**로 연결하면 됩니다. 실전에서는 SKILL.md에 레시피를 문서화하는 패턴이 가장 재사용성이 좋았습니다.

이 글이 답하는 질문

Tool, Skill, Plugin은 각각 뭐고 어떻게 다른가?
MCP로 외부 서비스를 도구로 연결하려면 어떻게 설정하나?
SKILL.md는 어떤 구조로 써야 에이전트가 자동으로 호출하나?

머리만 있으면 아무것도 못 한다

AI는 생각만 할 수 있습니다. 파일을 읽거나, 코드를 실행하거나, 검색하거나, API를 호출하려면 **도구(tool)**라는 손발이 필요합니다.

OpenAI는 에이전트가 초기에 막혔던 이유를 “환경이 충분히 명세되지 않았기 때문”이라고 설명합니다(Practices for Governing Agentic AI Systems). 필요한 도구와 추상화가 있어야 고수준 목표를 향해 전진할 수 있다는 뜻입니다.

도구의 3계층

계층	정의	예시	누가 만드나
Tool	원자적 행동 하나	파일 읽기, Bash 실행	Claude Code 내장
Skill	도구 여러 개를 조합한 작업 템플릿	”배포 스킬” = test → build → deploy	사용자 (`SKILL.md`)
Plugin	스킬 + 훅 + MCP를 패키징	`deploy-plugin`, 팀 공용 툴셋	커뮤니티 또는 조직

예를 들어, “배포”라는 스킬은 내부적으로 “테스트 실행(Bash 도구) → 빌드(Bash 도구) → git 상태 확인(Bash 도구) → 배포 스크립트 실행(Bash 도구)“의 조합입니다.

MCP — 외부 서비스를 도구로 연결하는 표준

MCP(Model Context Protocol)는 외부 서비스를 에이전트의 도구로 연결하는 프로토콜입니다(Model Context Protocol 공식 사이트). GitHub, Slack, DB 같은 서비스를 MCP 서버로 띄우면 에이전트가 직접 접근할 수 있습니다.

MCP 아키텍처: AI 에이전트 ↔ MCP 클라이언트 ↔ MCP 서버 ↔ GitHub/Postgres/Slack 등 외부 서비스

Claude Code에서 MCP 서버 설정하기:

// .claude/settings.json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "ghp_xxxx" }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": { "DATABASE_URL": "postgresql://..." }
    }
  }
}

이렇게 설정하면 에이전트가 GitHub 이슈를 읽거나, DB를 직접 쿼리할 수 있습니다.

SKILL.md — 재사용 가능한 작업 레시피

스킬은 “이 상황에서 이 순서로 이 도구들을 써라”는 레시피입니다.

# SKILL.md — 배포 스킬

## 언제 사용하는가
사용자가 "배포해줘", "deploy" 같은 요청을 할 때.

## 실행 순서
1. pnpm test로 테스트 전체 통과 확인
2. pnpm build로 빌드 성공 확인
3. git status로 커밋 안 된 변경사항 확인
4. 변경사항이 있으면 사용자에게 커밋 여부 물어보기
5. ./scripts/deploy.sh production 실행

## 주의사항
- 테스트가 실패하면 절대 배포하지 않는다
- staging 먼저 확인했는지 물어본다

에이전트가 “배포해줘”라고 요청받으면 이 스킬을 찾아서 순서대로 실행합니다. SKILL.md 자동 디스커버리 원리는 (7/8) 역할 분리 편의 subagent description과 동일한 매칭 메커니즘을 씁니다.

도구 설계 시 질문해야 할 것

새 도구를 추가할 때 아래를 먼저 답합니다:

이 도구가 없으면 에이전트가 뭘 못 하는가? — 필요 없으면 안 만듦
이 도구의 입력/출력은? — 명확해야 에이전트가 올바르게 호출
실패하면 어떻게 되는가? — 에러 핸들링 필요
위험한 부작용이 있는가? — 있으면 권한 설정 필요 (다음 편: (5/8) 권한 설정)
기존 도구 조합으로 대체 가능한가? — 가능하면 안 만듦

예시 — “슬랙에 자동 보고” MCP를 검토했다가 안 만들기로 결정한 사례:

Q1 “없으면 뭘 못 하나?”: 사람이 Slack 열어서 복붙하면 됨 → 필수 아님
Q5 “기존 조합으로 대체?”: curl + 웹훅 URL로 10줄 스크립트 가능
결론: Plugin 불필요, Bash 스크립트로 충분

이 5가지 질문은 “습관적으로 도구를 늘리는” 패턴을 막는 가장 단순한 가드레일입니다.

주의: 도구는 많을수록 좋은 게 아니다

OpenCode 문서는 MCP 서버가 많아질수록 컨텍스트를 많이 차지하므로 신중히 켜라고 경고합니다. 각 도구의 설명 자체가 컨텍스트 윈도우를 차지하기 때문입니다.

원칙: 필요한 만큼만. 처음에는 내장 도구(파일 읽기/쓰기, 셸 실행, 검색)만 쓰고, “이 도구가 없어서 막혔다”는 증상이 나올 때 MCP를 추가합니다.

내가 실제로 부딪힌 문제와 해결 (1인칭 경험)

도구를 붙일 때도 비슷한 실수를 했습니다. 처음에는 외부 도구와 스킬을 많이 연결할수록 더 똑똑해질 거라고 생각했는데, 실제로는 설명만 길어지고 판단이 느려지는 경우가 더 많았습니다. 특히 블로그 레포처럼 구조가 비교적 단순한 곳에서는, 기본 읽기/쓰기 도구만으로도 해결할 수 있는 일을 굳이 더 많은 레이어로 감싸면 오히려 컨텍스트만 낭비했습니다.

지금은 “정말 반복되는 작업만 스킬로 승격하고, 외부 시스템이 꼭 필요할 때만 MCP를 연다”는 쪽으로 기준이 바뀌었습니다. 필요한 도구만 남기고 나니 에이전트가 어떤 길을 선택해야 하는지 명확해졌고, 같은 작업을 다시 시켜도 결과가 더 일관됐습니다. 제 경험상 도구 설계의 핵심은 많이 붙이는 것이 아니라, 무엇을 일부러 노출하지 않을지 결정하는 것이었습니다.

자주 묻는 질문 (FAQ)

Q1. Tool, Skill, Plugin, MCP — 뭐부터 써야 하나요? Claude Code·OpenCode의 내장 Tool(Read, Write, Bash, Grep 등)만으로도 90%의 작업은 가능합니다. “이 작업이 반복되는데 매번 5개 Tool을 조합해야 한다”는 증상이 나오면 SKILL.md를 만들고, 외부 서비스(GitHub/DB/Slack) 접근이 필요해지면 MCP를 붙이세요. Plugin은 이 전부를 재사용 패키지로 묶을 때만.

Q2. MCP 서버는 몇 개까지 켜도 되나요? OpenCode 문서는 “신중히”를 강조합니다. 각 MCP 서버의 도구 설명이 모두 컨텍스트 윈도우에 로드되기 때문입니다. 경험상 3~5개가 실용적이고, 10개 이상이면 설명만으로 컨텍스트 10~15%를 잡아먹는 경우가 있었습니다.

Q3. SKILL.md와 CLAUDE.md는 어떻게 다른가요? CLAUDE.md는 프로젝트 전역 맵((3/8) 지식 구조화)이고, SKILL.md는 특정 작업의 실행 레시피입니다. SKILL.md는 .claude/skills/<skill-name>/SKILL.md 형태로 두면 에이전트가 요청을 분석해 매칭되는 스킬을 자동 발견합니다.

마무리

도구는 Tool → Skill → Plugin 3계층으로 이해하고, 외부 서비스는 MCP로 연결합니다.
SKILL.md는 “언제 사용하는가 + 실행 순서 + 주의사항” 3블록이 기본 구조입니다.
도구는 많을수록 좋은 게 아니라 꼭 필요할 때 하나씩 늘리는 게 효율적입니다.

다음에 읽으면 좋은 글

(5/8) Claude Code 권한 설정 — 위험한 도구는 어떻게 통제할까
(7/8) Subagent 역할 분리 — 스킬과 subagent 중 뭘 쓸지
(3/8) CLAUDE.md 작성 가이드 — 프로젝트 전역 맵