에이전트 스킬이란 무엇인가? SKILL.md 구조와 동작 원리

에이전트 스킬의 실제 의미

에이전트 스킬은 디스크 상의 폴더이며, 그 안에는 SKILL.md라는 파일이 들어 있습니다. 이 파일에는 이름, 짧은 설명, 그리고 일반 마크다운으로 작성된 지침이 포함됩니다. 에이전트는 시작 시 설명을 불러오며, 사용자의 요청이 해당 설명과 일치할 때만 지침을 읽습니다. 스킬에 관한 거의 모든 사항은 이 두 문장에서 비롯됩니다.

폴더에는 해당 파일 외에 다른 항목이 포함될 수 있습니다. Agent Skills 사양은 세 가지 선택적 디렉터리를 정의합니다. 에이전트가 실행하는 코드를 위한 scripts/, 필요할 때 읽어 들이는 문서를 위한 references/, 그리고 템플릿과 데이터를 위한 assets/입니다. 이들 중 필수는 없습니다. SKILL.md만 들어 있는 폴더도 완전한 스킬로 간주합니다.

restore-drill/
  SKILL.md
  references/retention-policy.md
  scripts/verify_snapshot.sh

설명은 사람들이 과소평가하는 부분입니다. 이는 에이전트가 스킬을 열지 여부를 결정하기 전에 확인하는 유일한 텍스트이므로, 스킬이 무엇을 수행하는지, 언제 사용해야 하는지를 실제 사용자가 입력할 법한 단어로 명시해야 합니다.

기술이 사용되기 전까지 거의 비용이 들지 않는 이유

이 논점은 해당 형식을 이해할 가치가 있는 이유를 설명하며, 기능이 아닌 맥락에 관한 것입니다. 로딩은 단계적으로 발생하며, 사양에서는 이를 점진적 공개(progressive disclosure)라고 부릅니다.

시작 시점에 에이전트는 설치된 모든 기술의 name 및 description만 로드합니다. Agent Skills 사양에 따르면 기술당 약 100 토큰이 소요됩니다(2026년 8월 기준 가이드라인). 12개의 기술을 설치해도 긴 문단 하나 정도의 맥락만 소비하게 됩니다.

요청이 설명과 일치하면 에이전트는 해당 SKILL.md의 본문을 읽습니다. 사양에서는 본문을 5,000 토큰 미만으로, 파일은 500 라인 미만으로 유지할 것을 권장합니다. references/ 및 scripts/에 있는 파일은 이 시점까지는 비용이 발생하지 않습니다. 참조 파일은 지침에 따라 에이전트가 해당 파일을 호출할 때만 로드됩니다. 번들 스크립트는 이와 다릅니다. 에이전트가 셸을 통해 스크립트를 실행하므로 스크립트의 소스 코드는 맥락 창에 들어오지 않고 출력 결과만 반영됩니다.

이제 사람들이 가장 먼저 선택하는 거대한 프롬프트와 비교해 보십시오. 시스템 프롬프트나 상시 활성화된 지침 파일의 모든 라인은 작업의 필요 여부와 관계없이 모든 세션의 모든 요청마다 비용이 발생하며, 실제 질문과 주의력을 두고 경쟁합니다. 10,000 토큰의 상시 지침은 단순히 시간을 묻는 질문에도 지불해야 하는 비용입니다. 12개의 기술은 대기 상태에서 약 1,200 토큰을 차지하며, 필요한 작업이 있을 때만 확장됩니다. 이것이 기술을 사용하는 핵심 이유이며, 작은 라이브러리가 긴 프롬프트보다 효율적인 이유입니다.

한 가지 주의할 점이 있습니다. 기술이 로드되면 해당 본문은 세션이 끝날 때까지 맥락에 유지되므로, 긴 SKILL.md은 일회성 비용이 아니라 반복적인 비용이 됩니다. 세부 사항을 references/로 옮기는 것은 단순히 정리하는 작업이 아닙니다. 이는 설계된 대로 작동하는 메커니즘입니다.

에이전트 스킬은 도구 호출이 아닙니다

도구(함수 호출이라고도 함)는 모델이 직접 실행할 수 있는 기능입니다. 하네스는 모델에 이름, 설명, 인자 형태가 포함된 스키마를 전달합니다. 모델이 호출을 생성하면 코드가 이를 실행하고, 그 결과가 메시지 형태로 반환됩니다. 도구는 실제로 작업을 수행합니다.

스킬은 그 자체로 아무것도 실행하지 않습니다. 에이전트가 스킬을 읽고, 이미 보유한 도구를 사용하여 행동합니다. 모델은 도구에 인자를 전달하는 방식처럼 스킬에 인자를 전달할 수 없습니다. 스킬이 할 수 있는 일은 어떤 도구를 어떤 순서로 사용해야 하는지, 그리고 작업 후 무엇을 확인해야 하는지 모델에게 알려주는 것입니다.

요약하자면, 도구는 에이전트에게 새로운 능력을 부여하고, 스킬은 에이전트가 이미 가진 능력에 대한 판단력을 제공합니다. 매번 정확하고 검증된 결과가 필요한 단계라면 도구나 스크립트가 적합합니다. 동일한 사고 과정을 일관되게 적용해야 하는 단계라면 스킬이 필요합니다.

에이전트 스킬은 MCP 서버가 아닙니다

MCP(model context protocol)는 에이전트를 외부 시스템에 연결하기 위한 프로토콜입니다. MCP 서버는 프로토콜을 사용하여 실행되는 프로세스이며, 에이전트에게 도구를 노출합니다. 일반적으로 설정, 자격 증명, 로컬 명령어 또는 네트워크 엔드포인트가 필요합니다. 반면 스킬은 마크다운 파일이 포함된 폴더일 뿐입니다. 프로세스, 포트, 프로토콜이 존재하지 않습니다.

컨텍스트 비용도 같은 방식으로 차이가 납니다. MCP 서버가 노출하는 모든 도구는 이름, 설명, 인수 스키마를 가지며, 기본적으로 사용 여부와 관계없이 전체 세션 요청에 포함됩니다. 일부 클라이언트는 도구 스키마를 필요할 때 가져오기 시작했지만, 여전히 미리 로드하는 것이 일반적입니다. 반면 저장된 상태의 스킬은 한 줄의 텍스트에 불과합니다.

이 둘은 상호 보완적인 관계이며, 가장 강력한 설정은 두 가지를 모두 실행합니다. MCP 서버는 접근 권한을 제공하고, 스킬은 절차를 제공합니다. 즉, 팀의 실제 워크플로우를 위해 어떤 도구를 호출할지, 어떤 순서로 진행할지, 무엇이 좋은 결과물인지 정의합니다. 직접 호스팅하는 경우 VPS에서 MCP 서버 실행하기에서 해당 내용을 다룹니다.

에이전트 스킬은 시스템 프롬프트나 AGENTS.md가 아닙니다

둘 다 마르크다운 형식의 지침이기에 혼동하기 쉽습니다. 차이점은 로드되는 시점에 있습니다. AGENTS.md, CLAUDE.md 및 시스템 프롬프트는 항상 활성화되어 있습니다. 반면 스킬은 필요할 때만 호출됩니다.

판단 기준은 간단합니다. 해당 작업과 무관한 상황에서 이 단락을 무시해도 문제가 없는가 하는 점입니다. 하우스 스타일, 빌드 명령어, 브랜치 명명 규칙은 모든 작업에 적용되므로 항상 활성화된 파일에 두어야 하며, 매번 로드되는 것이 목적입니다. 한 달에 두 번 실행하는 릴리스 체크리스트는 모든 작업에 적용되지 않으므로 스킬에 두는 것이 적절합니다. 항상 활성화된 파일의 특정 섹션이 번호가 매겨진 절차로 길어졌다면, 그것이 바로 스킬로 옮겨야 한다는 신호입니다.

이 파일들에는 올바르게 작성할 가치가 있는 고유한 관례가 있습니다. 우리가 사용하는 두 가지 관례에 대해서는 AGENTS.md에 포함할 내용과 사람이 읽는 파일에 포함할 내용 및 코드베이스의 구조를 설명하는 design.md를 참조하십시오.

최소한의 스킬 구성

Claude Code에서 개인 스킬은 ~/.claude/skills/<name>/SKILL.md에 저장되며 모든 프로젝트에 적용됩니다. 프로젝트 스킬은 .claude/skills/<name>/SKILL.md에 저장되고 git에 커밋되므로, 해당 저장소에서 작업하는 모든 사람과 에이전트가 이를 공유합니다. GitHub Copilot과 VS Code는 대신 .github/skills/에서 워크스페이스 스킬을 읽어 들입니다. 내부 파일은 동일한 파일입니다.

mkdir -p ~/.claude/skills/restore-drill

---
name: restore-drill
description: Run a restic restore drill and report what was recovered. Use when the user asks to test backups, verify a restore, or check that a snapshot is readable.
---

# Restore drill

1. Run `restic snapshots` and pick the newest snapshot for the host in question.
2. Restore it into a scratch directory under `/tmp`, never over live data.
3. Compare the restored file count and total size against the snapshot summary.
4. Report the snapshot ID and anything that failed to restore.

If `restic snapshots` prints `Fatal: unable to open config file`, the repository path or the password is wrong. Stop and report that instead of guessing.

이것이 완전한 스킬입니다. 디렉터리 이름이 사용자가 입력하는 명령어가 되므로, 이 예시의 경우 /restore-drill이 됩니다. Claude Code의 /skills 메뉴에는 설치된 항목이 나열되며, 파일이 정상적으로 인식되었는지 확인하는 가장 빠른 방법입니다. 해당 메뉴에 나타나지 않는다면 이름이 잘못된 것입니다. 파일명은 반드시 SKILL.md여야 하며, 디렉터리 이름은 소문자, 숫자, 단일 하이픈으로만 구성해야 합니다. 에이전트가 다시 실행할 수 있는 절차로 작성된 동일한 작업은 VPS에서의 restic 예약 백업과 자연스럽게 연결됩니다. 이때 백업을 실행하는 것과 백업을 복원하는 것은 서로 다른 작업입니다.

기술을 스크립트로 구현해야 하는 경우

매번 동일한 정답을 도출하는 모든 단계는 스크립트로 작성해야 합니다. 해당 기술은 언제 실행하고 출력 결과를 어떻게 해석할지만 명시하는 몇 줄의 코드로 축소하십시오. 여기에는 두 가지 실용적인 이유가 있습니다.

첫째, 스크립트의 소스 코드는 컨텍스트 윈도우에 포함되지 않습니다. 300줄짜리 파서는 결과값만 반환하면 되지만, 동일한 로직을 마크다운 지침으로 작성하면 기술이 로드될 때마다 전체 길이를 소비하게 됩니다.

둘째, 스크립트는 항상 동일한 결과를 보장합니다. 모델에게 매번 동일한 로그 파싱 규칙을 다시 도출하도록 요청하면, 모델의 상태가 좋지 않을 때 결과가 미세하게 달라질 수 있습니다. 두 수치가 일치하지 않기 전까지는 이를 알아차리기 어렵습니다.

따라서 작업의 성격에 따라 업무를 분리하십시오. "CSV를 파싱하고 합계가 항목과 일치하지 않는 모든 행을 출력하라"는 스크립트의 영역입니다. "스크립트가 출력한 행을 살펴보고 어떤 것이 데이터 입력 실수로 보이는지 설명하라"는 기술 지침의 영역입니다. 판단은 마크다운에, 결정론적 작업은 코드에 두는 것은 사용자가 지켜보지 않아도 에이전트가 실행할 수 있는 루프를 구축하는 것과 동일한 원칙입니다.

왜 스킬이 실행되지 않습니까?

description에 스킬의 기능만 설명하고 언제 사용해야 하는지는 명시하지 않았기 때문입니다. 에이전트는 오직 그 한 줄의 설명만을 기준으로 사용자의 요청과 스킬을 매칭합니다. "데이터베이스 작업을 돕는다"는 설명은 구체적인 상황과 일치하지 않습니다. 반면 "스테이징 데이터베이스에서 스키마 마이그레이션을 실행한다. 사용자가 테이블 마이그레이션, 컬럼 추가, 스키마 변경을 요청할 때 사용한다"와 같이 작성하면 사용자가 실제로 입력하는 단어가 포함되어 스킬이 정상적으로 실행됩니다.

반대로 스킬이 너무 자주 실행되는 경우도 있습니다. "이 저장소의 모든 코드 변경에 사용"과 같은 설명은 모든 상황과 일치하므로, 모든 작업마다 스킬 본문이 로드되어 세션 내내 컨텍스트를 차지하게 됩니다. 의도한 상황에 맞게 설명을 구체적으로 좁히십시오. Claude Code에서는 프론트매터에 disable-model-invocation: true를 설정할 수 있습니다. 이를 사용하면 자동 로드를 방지하고 스킬 이름을 직접 입력할 때만 스킬을 사용할 수 있습니다.

세 번째 실패 사례는 도구의 기능을 중복해서 구현하는 경우입니다. MCP 서버가 이미 제공하는 API를 curl하라고 에이전트에게 지시하거나, 이미 검색 도구가 있는데도 파일을 grep하도록 지시하면 처리 속도가 느려질 뿐만 아니라 서로 충돌하는 두 가지 지침이 생기게 됩니다. 중복된 지침을 삭제하고 스킬의 목적을 명확히 설명하십시오.

어떤 문제인지 추측하지 마십시오. 새로운 세션에서 동일한 프롬프트를 두 번 실행하십시오. 한 번은 스킬을 활성화하고, 다른 한 번은 비활성화한 뒤 답변을 비교하십시오. 스킬을 작성한 세션에서는 이미 스킬의 모든 내용이 컨텍스트에 포함되어 있어 작성된 설명의 결함을 발견하기 어렵기 때문에 반드시 새로운 세션에서 테스트해야 합니다. Anthropic의 skill-creator 플러그인을 사용하면 Claude Code 내에서 이러한 비교 과정을 자동화할 수 있습니다. 이 플러그인은 스킬이 실행되어야 할 프롬프트와 실행되지 않아야 할 프롬프트를 생성하고, 각 경우의 실행 빈도를 측정합니다.

이 형식은 특정 업체의 것인가요, 아니면 표준인가요?

Anthropic이 2025년 말에 이 형식을 발표한 후, agentskills.io에서 호스팅하는 오픈 표준으로 공개했습니다. 2026년 8월 기준으로 해당 사양은 필수 필드인 name과 description, 선택 필드인 license, compatibility, metadata 및 allowed-tools, 세 가지 선택 디렉터리, 그리고 단계별 로딩 동작을 정의합니다. 또한 참조 검증 도구도 함께 제공하므로, 공유하기 전에 skills-ref validate ./my-skill을 사용하여 폴더가 사양에 부합하는지 확인할 수 있습니다.

클라이언트 목록이 가장 확실한 지표입니다. 동일한 폴더를 Claude Code, Cursor, OpenAI Codex, Gemini CLI, GitHub Copilot, VS Code, Goose, OpenHands, opencode 등이 읽을 수 있습니다. Microsoft는 github.com/microsoft/skills에 자체 스킬을 이 형식으로 게시하고 있으며, 사용자가 작업을 한 번 수행하는 것을 지켜본 뒤 이를 의도와 순차적 단계로 재구성하여 스킬로 출력하는 Skill Recorder라는 데스크톱 도구를 제공합니다. 타사의 사양에 맞는 출력 형식을 생성하는 레코더를 업체가 직접 만든다는 것은, 해당 형식이 더 이상 특정 제품의 기능에 머물지 않는다는 좋은 신호입니다.

가장 먼저 작성할 내용

라이브러리를 미리 설계하지 마십시오. 동일한 지침을 세 번째로 채팅창에 붙여넣고 있는 자신을 발견할 때까지 기다린 다음, 해당 텍스트를 SKILL.md로 옮기고 기존 붙여넣기 내용은 삭제하십시오. 이미 체감한 반복이야말로 유지할 가치가 있는 기술을 결정하는 유일하고 확실한 기준입니다. 검색 절차는 첫 번째 기술로 적합하며, 직접 구축한 SearXNG 인스턴스를 활용한 검색 기술이 그 형태를 잘 보여줍니다.

두 가지 습관이 라이브러리를 건강하게 유지합니다. 작성하지 않은 기술은 설치하기 전에 스크립트를 포함하여 반드시 내용을 읽어보십시오. 기술은 에이전트가 따를 지침이자 실행할 코드이므로, 낯선 이의 소프트웨어를 설치할 때와 동일하게 취급해야 합니다. 또한 기술은 커밋되고 공유되는 텍스트 파일이므로 폴더 내에 자격 증명을 포함하지 마십시오. 에이전트로부터 비밀 정보를 분리하는 방법에서 해당 값들을 어디에 보관해야 하는지 다루며, 올해의 에이전트 학습 로드맵에서는 나머지 설정과 함께 기술을 체계적으로 정리하는 방법을 제시합니다.

FAQ

에이전트 스킬과 MCP 서버의 차이점은 무엇입니까?

MCP(Model Context Protocol) 서버는 프로토콜을 통해 에이전트에 도구를 노출하는 실행 중인 프로세스입니다. 따라서 설정과 자격 증명이 필요하며, 도구 정의는 사용 여부와 관계없이 세션 전체의 컨텍스트를 차지합니다. 에이전트 스킬은 SKILL.md 파일을 포함하는 폴더이며, 별도의 프로세스나 프로토콜이 없습니다. 에이전트가 이를 읽기로 결정하기 전까지는 약 100 토큰 정도의 비용만 발생합니다. 에이전트에게 시스템 접근 권한을 부여하려면 MCP 서버를 사용하십시오. 해당 접근 권한을 올바르게 사용하는 절차를 에이전트에게 알려주려면 스킬을 사용하십시오. 많은 설정에서 두 가지를 모두 사용합니다.

에이전트 스킬은 Claude Code에서만 작동합니까?

아닙니다. Anthropic이 이 형식을 개발한 뒤 agentskills.io를 통해 오픈 표준으로 공개했습니다. 동일한 폴더를 Cursor, OpenAI Codex, Gemini CLI, GitHub Copilot, VS Code, Goose, OpenHands 및 기타 클라이언트에서 읽을 수 있습니다. 클라이언트마다 참조하는 위치와 이해하는 추가 프론트매터(frontmatter) 필드가 다를 뿐입니다. Claude Code는 ~/.claude/skills/ 및 .claude/skills/을 읽는 반면, GitHub Copilot과 VS Code는 저장소 내의 .github/skills/을 읽습니다. SKILL.md 파일 자체는 수정 없이 그대로 호환됩니다.

스킬을 많이 설치하면 속도가 느려집니까?

제약 사항은 개수가 아니라 시작 시의 토큰 예산입니다. 설치된 각 스킬은 이름과 설명을 포함하며, 사양 가이드라인에 따라 약 100 토큰을 소비합니다. 따라서 30개의 스킬을 설치하면 사용하기 전부터 약 3,000 토큰이 소모됩니다. 가장 먼저 성능이 저하되는 부분은 속도가 아니라 매칭 정확도입니다. 설명이 중복되는 스킬이 많으면 모델이 올바른 스킬을 선택하기 어려워집니다. 설명이 중복되지 않게 작성하고, 사용하지 않는 스킬은 삭제하십시오.

이 지침은 스킬에 넣어야 합니까, 아니면 AGENTS.md에 넣어야 합니까?

해당 지침이 저장소의 모든 작업에 적용되는지 자문해 보십시오. 빌드 명령, 사내 스타일 가이드, 명명 규칙은 모든 작업에 적용되므로 항상 활성화된 파일에 두는 것이 적절하며, 매번 로드되는 것이 목적입니다. 릴리스 체크리스트나 복구 훈련처럼 가끔 실행하는 절차는 스킬로 만드는 것이 좋습니다. 그래야 해당 절차가 필요 없는 작업에서는 비용이 발생하지 않습니다. AGENTS.md의 섹션 중 번호가 매겨진 단계로 길어진 내용은 보통 스킬로 분리되기를 기다리는 상태입니다.