Claude CLI 를 사용하다가 MCP 는 뭐고 Skills 는 뭐고 하네스는 뭐고,, 아는 것 없이 클로드가 뭔가 진행할 때 마다 Skills 를 사용한다고는 하는데 뭐가 되고있는건지 , 어떻게 되고있는 건지 , 왜 되는 건지 아무것도 아는게 없어서 정리하기로 결심했다.

자세한 얘기를 Claude 공식문서를 보며 공부해보자

먼저 Skills 를 이해하기 위해선 AI Agent 에 대해서 알아야 한다.

Agent란?

목표를 받으면 스스로 계획을 세우고, 툴을 사용하고, 결과를 보고 다음 행동을 결정하는 시스템

EX ) "자율적으로 여러 스텝을 실행하는 Claude"

Skills란?

Agent가 특정 작업을 잘 수행하기 위해 읽는 지식/지침 파일

EX ) "Agent의 전문 매뉴얼"

정리

• Skills는 Agent를 더 잘 작동하게 만드는 보조 장치다.

• Agent가 없으면 Skills도 의미 없음 (읽어줄 주체가 없으니까)

• Skills가 없어도 Agent는 동작하지만, 환경 특화 작업의 품질이

즉, Skills ⊂ Agent 시스템 — Skills는 Agent 아키텍처의 한 구성요소

Claude의 Skills 실행 원리

Claude Code skills는 Agent Skills 개방형 표준을 따르며, 이는 여러 AI 도구에서 작동합니다. Claude Code는 호출 제어, subagent 실행, 동적 컨텍스트 주입과 같은 추가 기능으로 표준을 확장합니다.

Skills는 쉽게 말하면 Claude에게 전달되는 지침 Markdown 파일이다.
프롬프트(일회성 작업을 위한 대화 수준의 지침)와 달리, 스킬은 온디맨드(필요할 때만)로 로드되며 여러 대화에서 동일한 지침을 반복적으로 제공할 필요가 없게 된다.

이로 인해

한 번 생성하고 자동으로 사용으로 반복 횟수를 줄여 토큰을 아끼고,
복잡한 워크플로우를 구축하기 위한 기술을 결합해 역량을 구성한 AI Agent 를 만들어낼수 있다.

동작 흐름

시스템 프롬프트 (본인이 설정)
    ↓
"파일 만들기 전에 반드시 관련 SKILL.md를 먼저 읽어라"
+ available_skills 목록과 각 설명이 포함되어 있음
    ↓
Claude가 요청 분석 → "아, 이건 docx 작업이네"
    ↓
스스로 판단해서 view/bash로 SKILL.md 읽기

이런 식으로 AI는 스스로 어떤 작업인지 파악한다.

두 가지 판단이 필요함

1. "이 요청이 어떤 작업인가?" → 작업 분류
2. "어떤 SKILL.md를 읽어야 하나?" → 파일 선택

이는 결국 LLM의 추론 능력에 달려 있다.

AI 자체의 성능도 있으나 , 좋은 모델이라도 Description 을 엉망으로 적으면 제대로 사용할 수 없고, 안 좋은 모델이라도 제대로 된 Description 을 적으면 그 성능 100% 활용할 수 있다.

① Skill 설명문의 품질

available_skills 목록에 있는 각 Skill의 description이 핵심이다.

Claude가 이 설명을 보고 "아, 이 상황엔 이 Skill이다" 판단하니까
description이 모호하면 → 잘못된 Skill 선택하거나 아예 안 읽음

<skill>
  <name>docx</name>
  <description>
    'Word doc', '.docx' 언급되면 사용.
    표, 목차, 페이지 번호 등 포함된 문서 요청 시 사용.
    PDF, 스프레드시트엔 사용하지 말 것.   ← 이런 경계 설명이 중요
  </description>
</skill>

③ 시스템 프롬프트의 지시 강도

"반드시 읽어라 (mandatory)" vs "읽는 걸 고려해라"
강제성이 높을수록 누락 가능성이 줄어듦

핵심 원리

1. SKILL.md는 단순한 텍스트 파일

/mnt/skills/ 경로에 마운트된 파일들
특정 작업(docx, pdf, pptx 등)에 대한 상세한 지침이 담겨 있음
어떤 라이브러리를 써야 하는지, 어떤 패턴으로 코드를 짜야 하는지 등이 명시됨

2. Claude가 스스로 판단해서 읽음

시스템 프롬프트에 "파일 만들기 전에 반드시 SKILL.md를 먼저 읽어라"는 규칙이 있음
Claude가 어떤 작업이 필요한지 판단 → 맞는 SKILL.md를 view 툴로 열어서 읽음
읽은 내용을 컨텍스트에 반영해서 작업 수행

3. 환경 특화 지식을 주입하는 방식

Claude의 학습 데이터만으로는 "이 특정 환경에서 어떤 라이브러리가 설치되어 있는지", "어떤 경로에 파일을 저장해야 하는지" 같은 걸 알 수 없음
SKILL.md가 그 환경별 정보를 실시간으로 제공하는 역할을 함

RAG(Retrieval-Augmented Generation)의 단순화 버전이라고 볼 수 있음. 모델 자체를 바꾸는 게 아니라, 작업 직전에 필요한 지식을 파일에서 읽어와서 컨텍스트에 넣는 방식.

예: PDF 처리 기술 로드

시작: 시스템 프롬프트에는 다음이 포함됩니다:

PDF Processing - Extract text and tables from PDF files, 
fill forms, merge documents

사용자 요청: "이 PDF에서 텍스트를 추출하여 요약하세요."
↓
클로드가 호출: bash: read pdf-skill/SKILL.md 
→ 컨텍스트에 로드된 지침-> 배쉬를 통해 SKILL.md 을 읽음으로써 기술을 트리거한다
↓
클로드가 결정: 양식 작성이 필요 없으므로 FORMS.md 을 읽을 수 없습니다
-> 필요없는 파일에 대한 읽음을 제한함으로써 토큰 절약
↓
클로드가 실행: SKILL.md 의 지침을 사용하여 작업을 완료합니다