에이전트 스킬(Agent Skills)의 정의와 작동 원리

에이전트 스킬의 실제 의미

에이전트 스킬은 내부에 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년 10월 기준 공개 지침). 12개의 기술을 설치해도 긴 문단 하나 정도의 맥락만 소비하게 됩니다.

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

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

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

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

도구(함수 호출이라고도 함)는 모델이 실행할 수 있는 기능입니다. 하네스는 모델에 이름, 설명, 인자 형태가 포함된 스키마를 전송합니다. 모델이 호출을 생성하면 코드가 이를 실행하고, 결과가 메시지 형태로 반환됩니다. 도구는 실제 작업을 수행합니다. 이 교환 과정의 양쪽 모두 모델 주변에서 루프를 실행하는 프로그램인 하네스에 속하며, 하네스는 시작 시점에 스킬 설명을 읽고 언제 스킬을 열지 결정하는 주체이기도 합니다.

스킬은 그 자체로 아무것도 실행하지 않습니다. 에이전트가 스킬을 읽고, 이미 보유한 도구를 사용하여 행동합니다. 모델은 도구에 인자를 전달하는 방식으로는 스킬에 인자를 전달할 수 없습니다. 스킬이 할 수 있는 일은 어떤 도구를 어떤 순서로 사용할지, 그리고 작업 후에 무엇을 확인해야 할지 모델에게 알려주는 것입니다. 다른 에이전트에게 작업을 넘기는 것이 가장 명확한 예시입니다. 하나의 Claude Code 세션은 이미 다른 세션에 메시지를 보낼 수 있으며, 스킬은 그러한 작업이 언제 필요한지, 무엇을 보낼지 정의하는 곳입니다.

요약하자면, 도구는 에이전트에게 새로운 능력을 부여하고, 스킬은 주로 에이전트가 이미 가진 능력에 대한 판단력을 제공합니다. 스킬이 새로운 능력을 추가하는 경우, 이는 에이전트가 이미 보유한 셸을 통해 실행하는 번들 스크립트를 통해 이루어집니다. 매번 정확하고 검증된 결과가 필요한 단계라면 도구나 스크립트가 적합합니다. 일관된 사고 과정이 필요한 단계라면 스킬이 적합합니다. 스킬은 단순히 판단력만 제공할 수도 있으며, 그럼에도 가장 자주 사용하게 되는 스킬일 수 있습니다. 코딩 에이전트가 작동하는 가장 작은 변경 사항을 만들도록 유도하는 Ponytail이 그 예입니다. 이는 새로운 기능을 추가하지 않고 에이전트가 기존 기능을 사용하는 방식만 변경합니다. 이러한 판단력은 반대 방향으로도 작용할 수 있습니다. 에이전트가 작업을 조기에 완료했다고 선언하지 못하도록 Depth Tree를 탐색하는 unlazy 스킬은 절제보다는 철저함을 목표로 하는 동일한 방식의 기법입니다.

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

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

컨텍스트 비용 또한 같은 방식으로 차이가 납니다. MCP 서버가 제공하는 모든 도구는 이름, 설명, 인수 스키마를 포함하며, 이를 미리 로드하는 클라이언트에서는 사용 여부와 관계없이 전체 세션 요청에 포함됩니다. Claude Code는 더 이상 기본적으로 그렇게 작동하지 않습니다. 2026년 10월 기준, 도구 검색 기능이 기본적으로 활성화되어 있어 세션 시작 시에는 도구 이름과 서버 지침만 로드되며, Claude가 도구를 검색할 때 전체 정의가 전달됩니다. 반면 스킬은 저장된 상태에서 단 한 줄의 텍스트로 존재합니다.

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

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

둘 다 마르크다운 형식의 지침이므로 혼동하기 쉽습니다. 차이점은 로드되는 시점에 있습니다. AGENTS.md, CLAUDE.md 및 시스템 프롬프트는 항상 활성화되어 있습니다. 반면 스킬은 필요할 때만 호출됩니다. Claude Code의 출력 스타일은 항상 활성화된 설정의 끝단에 위치하며, 이를 선택하면 시스템 프롬프트 자체가 수정됩니다. 따라서 스킬이 전혀 관여하지 않는 응답을 포함하여 세션 내의 모든 응답에 영향을 미칩니다.

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

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

최소한의 기술 구성 요소

Claude Code에서 개인 기술은 ~/.claude/skills/<name>/SKILL.md에 저장되며 모든 프로젝트에 적용됩니다. 프로젝트 기술은 .claude/skills/<name>/SKILL.md에 저장되고 git에 커밋되므로, 해당 저장소에서 작업하는 모든 사람과 에이전트가 이를 공유합니다. GitHub Copilot과 VS Code는 .github/skills/ 및 .agents/skills/, 그리고 .claude/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여야 하며, Agent Skills 사양에 따라 이름은 소문자, 숫자, 단일 하이픈으로만 구성되어야 하고 디렉터리 이름과 일치해야 합니다. 에이전트가 다시 실행할 수 있는 절차로 작성된 동일한 작업은 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년 10월 기준으로 해당 사양은 필수 필드인 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) 서버는 프로토콜을 통해 에이전트에 도구를 노출하는 실행 중인 프로세스입니다. 따라서 설정과 자격 증명이 필요하며, 클라이언트가 지연 로딩을 하지 않는 한 전체 도구 정의가 세션 내내 컨텍스트를 차지합니다(현재 Claude Code는 기본적으로 지연 로딩을 수행합니다). 에이전트 스킬은 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/, .claude/skills/ 또는 .agents/skills/을 읽습니다. SKILL.md 파일 자체는 변경 없이 그대로 사용할 수 있습니다.

스킬을 몇 개나 설치해야 속도가 느려지지 않습니까?

제약 조건은 개수가 아니라 시작 시의 토큰 예산입니다. 사양의 공개 지침에 따르면 각 설치된 스킬은 이름과 설명을 포함하여 약 100 토큰을 차지하므로, 30개의 스킬은 사용하기 전에도 약 3,000 토큰을 소모합니다. 가장 먼저 저하되는 것은 속도가 아니라 매칭 정확도입니다. 설명이 겹치는 스킬이 많으면 모델이 올바른 스킬을 선택하기 어려워집니다. 설명이 겹치지 않게 작성하고, 더 이상 사용하지 않는 스킬은 삭제하십시오.

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

리포지토리의 모든 작업에 적용되는지 자문해 보십시오. 빌드 명령, 사내 스타일, 명명 규칙은 모든 작업에 적용되므로 항상 활성화된 파일에 두는 것이 적절하며, 매번 로드하는 것이 목적입니다. 릴리스 체크리스트나 복구 훈련처럼 가끔 실행하는 절차는 스킬로 만드는 것이 좋습니다. 이렇게 하면 해당 절차가 필요 없는 작업에서는 한 줄짜리 설명만 로드되어 비용이 절감됩니다. AGENTS.md의 섹션이 길어져 번호가 매겨진 단계로 구성되었다면, 보통 스킬로 분리할 시점이 된 것입니다.