에이전트 스킬의 정의와 작동 원리 완벽 정리

에이전트 스킬의 실제 의미

에이전트 스킬은 디스크 상의 폴더이며, 그 안에는 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/로 옮기는 것은 단순히 정리하는 작업이 아닙니다. 이는 설계된 대로 작동하는 메커니즘입니다.

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

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

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

요약하자면, 도구는 에이전트에게 새로운 능력을 부여하고, 스킬은 이미 가진 능력에 대한 판단력을 부여합니다. 매번 정확하고 검증된 결과가 필요한 단계라면 도구나 스크립트가 필요합니다. 동일한 사고 과정을 일관되게 적용해야 하는 단계라면 스킬이 필요합니다. 스킬은 오직 판단만 제공할 뿐이지만, 코딩 에이전트가 가장 작은 단위의 변경만 수행하도록 유도하는 Ponytail에서 볼 수 있듯이 가장 자주 사용하게 되는 요소일 수 있습니다. 이는 새로운 기능을 추가하는 것이 아니라, 에이전트가 기존 기능을 사용하는 방식을 변경하기 때문입니다.

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

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

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

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

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

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

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

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

최소한의 기술(skill) 구성

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 및 기타 클라이언트에서 읽을 수 있습니다. 차이점은 각 클라이언트가 참조하는 위치와 지원하는 추가 프런트매터 필드입니다. Claude Code는 ~/.claude/skills/ 및 .claude/skills/을 읽고, GitHub Copilot과 VS Code는 저장소 내의 .github/skills/을 읽습니다. SKILL.md 파일 자체는 클라이언트 간에 변경 없이 그대로 사용됩니다.

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

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

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

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