블로그로 돌아가기

AI 입문가이드

에이전트 스킬(SKILL.md)이란 무엇이며 검증하는 방법

스킬은 에이전트가 필요할 때만 로드하는 SKILL.md 파일이 있는 폴더입니다. 프롬프트와 어떻게 다른지, 토큰 비용은 얼마인지, 검증하는 방법을 다룹니다.

작성자: CheapTokens Team 게시됨읽는 시간 7분

이름과 설명 필드가 있는 SKILL.md 파일의 헤더
이 페이지의 내용
  1. 스킬이란 무엇이며 프롬프트와 어떻게 다른가
  2. 스킬이 컨텍스트 윈도우에 들어가는 방식
  3. 2분 만에 최소 스킬 작성하기
  4. 스킬, AGENTS.md, MCP: 각각 무엇인가
  5. 설치 전에 타사 스킬 검증하기

스킬은 코딩 에이전트가 찾는 위치에 있는 SKILL.md 파일이 들어 있는 폴더입니다. 에이전트는 요청이 그것과 일치할 때만 파일을 읽습니다. 그때까지 스킬은 약 100토큰의 비용만 차지하는 반면, 프롬프트는 붙여넣은 모든 메시지와 함께 이동합니다.

README에서 이 단어를 본 적이 있을 겁니다: "스킬을 설치한 다음 에이전트에게 ...를 요청하세요". 신비로운 일은 없습니다. 아래에서: 내부에 무엇이 있는지, 언제 컨텍스트 윈도우에 들어가는지, 그리고 내 머신에 들이기 전에 어떻게 살펴볼지 다룹니다.

스킬이란 무엇이며 프롬프트와 어떻게 다른가#

Anthropic의 Agent Skills 문서(2026년 10월 30일 확인)는 스킬을 재사용 가능한 파일시스템 기반 리소스로 설명합니다: SKILL.md 파일이 있는 디렉터리와 선택적 스크립트, 템플릿, 참조 파일입니다. SKILL.md는 작은 YAML 헤더(이름과 설명)로 시작하고 평문 지침으로 이어집니다.

새 동료를 떠올려 보세요. 프롬프트는 매일 아침 그들의 의자 뒤에 서서 규칙을 반복하는 것입니다. 스킬은 책등에 라벨이 붙은 선반 위의 바인더입니다: "커밋 메시지 스타일. 누군가 커밋을 요청하면 읽어라." 필요할 때만 꺼냅니다.

플래시카드

모든 스킬 README에서 만나게 될 단어들

두 개의 헤더 필드가 필수이며 형식에 규칙이 있습니다. Claude의 Skills 형식에서 name는 최대 64자입니다: 소문자, 숫자, 하이픈이며 "anthropic" 또는 "claude"라는 단어를 포함할 수 없습니다. description는 비어 있을 수 없고 최대 1,024자이며, 스킬이 무엇을 하는지와 언제 사용하는지를 모두 말해야 합니다.

스킬 폴더: SKILL.md와 선택적 템플릿 및 스크립트
스킬의 형태: 필수 파일 하나, 나머지는 모두 선택.

스킬이 컨텍스트 윈도우에 들어가는 방식#

문서는 이를 점진적 공개(progressive disclosure)라고 부릅니다: 에이전트는 세 단계로 스킬을 읽고, 각 단계는 도달했을 때만 비용을 지불합니다.

  • 1단계, 항상 로드됨. 설치된 모든 스킬의 이름과 설명, 스킬당 약 100토큰.
  • 2단계, 트리거될 때. SKILL.md의 본문, 5,000토큰 미만.
  • 3단계, 필요할 때만. 번들 파일과 스크립트. 에이전트가 스크립트를 실행할 때 스크립트의 코드는 컨텍스트에 들어가지 않고 출력만 들어갑니다.

토큰 수치는 문서의 근사치이며 정확한 개수가 아닙니다.

순서대로 배열하기

세 단계를 에이전트가 만나는 순서대로 배열하세요

  1. 에이전트가 시작하고 설치된 모든 스킬의 이름과 설명을 읽음
  2. 요청이 하나의 설명과 일치하여 SKILL.md 본문이 읽힘
  3. 지침이 스크립트나 템플릿을 언급하여 해당 파일이 사용됨
세 가지 로딩 단계: 이름과 설명, SKILL.md 본문, 번들 파일
각 단계는 이전 단계가 필요하다고 판단했을 때만 읽힘.

이것이 청구서에 중요한 이유입니다. 20개의 스킬을 설치했다고 가정해 봅시다. 20 × 100 = 2,000토큰이 첫 메시지부터 함께 이동합니다. 에이전트는 매 단계마다 컨텍스트를 다시 보내므로(20단계 예시가 그 이유를 보여줍니다), 50단계 세션은 50 × 2,000 = 100,000 입력 토큰의 스킬 라벨을 운반합니다. DeepSeek-V4-Flash에서 현재 가격으로 $0.0015입니다.

이제 반대의 경우입니다. 그 20개의 스킬이 하나의 큰 프롬프트로 붙여넣어졌다면, 각 본문이 모든 요청에 들어갔을 것입니다: 세션당이 아니라 요청당 최대 20 × 5,000 = 100,000토큰입니다. 그 차이가 바로 필요할 때 로드하는 것의 핵심입니다. "컨텍스트 윈도우"라는 용어가 아직 모호하다면, 이 설명글이 무엇이 그것을 채우는지 다룹니다.

스킬은 컨텍스트에 존재하므로, 에이전트 뒤의 모델은 그것을 위한 공간이 필요합니다. CheapTokens의 DeepSeek-V4-Flash(id deepseek-ai/DeepSeek-V4-Flash-0731)는 380K 컨텍스트 윈도우와 답변당 최대 32,768 출력 토큰을 가지며, 하루 중 언제든 하나의 가격이고, OpenAI 및 Anthropic 호환 API를 제공합니다. 터미널 에이전트의 경우 Claude Code를 CheapTokens에 연결하는 방법을 따르고, 다른 도구의 경우 문서에서 시작하세요. 모델 자체의 페이지는 여기입니다.

2분 만에 최소 스킬 작성하기#

하나를 작성한 후에 읽는 것이 더 쉽습니다. 이 스킬은 에이전트가 고정 형식으로 커밋 메시지를 작성하게 합니다. Claude Code에서 개인 스킬은 ~/.claude/skills/에, 프로젝트 스킬은 .claude/skills/에 있으므로 프로젝트 스킬은 저장소와 함께 이동할 수 있습니다.

bash
mkdir -p ~/.claude/skills/commit-message-style
nano ~/.claude/skills/commit-message-style/SKILL.md   # or any editor

이것을 파일에 붙여넣으세요:

markdown
---
name: commit-message-style
description: Writes git commit messages in this project's format. Use when the user asks to commit, to write a commit message, or to summarize staged changes.
---

# Commit message style

1. Run `git diff --staged` and read it.
2. First line: `type(scope): summary`, at most 72 characters. Types: feat, fix, docs, refactor, test.
3. Blank line, then up to three bullets that say why the change was made, not what changed.
4. Do not put file names in the first line.

이제 스테이징된 변경이 있는 저장소에서 에이전트를 열고 물어보세요: "내가 스테이징한 것에 대한 커밋 메시지를 작성해줘". 에이전트는 설명을 보고, 일치한다고 판단하고, 네 가지 규칙을 읽고 따릅니다. 스킬을 무시한다면 먼저 description를 보세요: 실제로 사용할 단어로 상황을 명시해야 합니다, 여기서는 "commit"입니다.

한 가지 주의: 스킬은 claude.ai, API, Claude Code 간에 동기화되지 않습니다. 한 곳에서 만든 스킬은 다른 곳에 별도로 추가해야 합니다.

스킬, AGENTS.md, MCP: 각각 무엇인가#

이 세 가지는 항상 혼동됩니다. AGENTS.md 또는 CLAUDE.md 같은 규칙 파일은 세션 시작 시 읽히며 프로젝트에 대한 사실을 담습니다(Downloads 폴더에서 그 파일이 잘못될 수 있는 방법). MCP 서버는 에이전트에게 도달할 새로운 도구와 데이터를 제공합니다(평범한 영어로 설명한 MCP). 스킬은 절차입니다: 한 종류의 작업을 수행하는 방법으로, 그 작업이 나올 때 로드됩니다.

빠른 확인

20개의 스킬을 설치했지만 오늘 아무것도 사용하지 않았습니다. 컨텍스트에서 비용은 얼마입니까?

정답 보기

정답: 각각 약 100토큰, 이름과 설명에 대해

이름과 설명은 항상 로드됩니다(문서에 따르면 스킬당 약 100토큰). 본문은 스킬이 트리거될 때만 로드되고, 스크립트 코드는 컨텍스트에 들어가지 않고 출력만 들어갑니다.

설치 전에 타사 스킬 검증하기#

스킬은 에이전트가 따르는 텍스트이며, 때로는 에이전트가 실행하는 코드입니다. 문서는 신뢰할 수 있는 출처의 스킬만 사용하고, 모든 번들 파일(SKILL.md, 스크립트, 리소스)을 감사하고, 예상치 못한 네트워크 호출이나 파일 접근을 찾으라고 말합니다. 외부 URL을 가져오는 스킬은 더 위험합니다. Claude Code에서 스킬은 컴퓨터의 다른 프로그램과 동일한 네트워크 접근 권한을 가지므로, 설치를 소프트웨어 설치처럼 취급하세요.

좋은 예시는 universal-modder라는 게임 모딩 툴킷입니다. 그 README(2026년 10월 30일 확인)는 Agent Skills 형식의 MIT 라이선스 스킬 세트, um라는 Python CLI, fal을 통한 에셋 생성을 위한 MCP 서버, 그리고 현장 노트의 공유 지식 베이스를 설명합니다. 주요 스킬인 mod-any-game은 정찰, 리버스 엔지니어링, 에셋 생성, 게임 내 테스트, 패키징을 다룹니다. README는 Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode를 지원 도구로 나열하며, 툴킷이 안티치트나 DRM 우회를 거부한다고 말합니다. Claude Code에서는 /plugin marketplace add rehan-remade/universal-modder로 설치하며, 에셋 생성에는 별도의 fal API 키가 필요합니다.

그 목록에 무엇이 들어 있는지 주목하세요: 스킬, 명령줄 프로그램, 서버입니다. SKILL.md 하나를 읽는 것은 설치하는 것의 일부만 다룰 것입니다. 그래서 조각들을 살펴보세요:

체크리스트

다른 사람의 스킬을 설치하기 전에

핵심 규칙은 API 키를 안전하게 저장하는 방법에 있습니다. 저장소 페이지에는 마지막 커밋 날짜가 표시되지 않으므로, 의존하기 전에 프로젝트가 얼마나 최근에 업데이트되었는지 확인하세요.

태그: