에이전트 스킬(SKILL.md)

1. Agent Skills

에이전트 스킬(agent skills)는 단순한 단축 명령어 기능에서 시작해서 현재는 여러 AI 에이전트 제품이 채택하는 강력한 ‘오픈 표준(open standard)’으로 발전했다. 과거 클로드 코드(claude code)는 에이전트의 행동을 확장하기 위해 사용자 지정 명령어(Custom Commands)라는 방식을 사용했다. .claude/commands/ 폴더 내에 단일 마크다운(.md) 파일 형태로 프롬프트 템플릿을 저장하는 단순한 형태였다. 이는 다음과 같은 한계점이 있었다.

• 사용자가 항상 슬래시(/) 명령어를 통해 수동으로만 호출해야 했으며, AI가 스스로 판단하여 자동 실행하는 기능(Auto-triggering)이 없었다.
• 명령어가 실행될 때마다 전체 프롬프트가 한 번에 로드되어 AI의 컨텍스트 윈도우(토큰)를 크게 낭비했다.
• 스크립트를 번들링하거나 복잡한 참조 문서를 분리해서 관리할 수 없다는 구조적 한계가 있었다.

사용자 지정 명령어의 한계를 극복하기 위해 앤스로픽(anthropic)은 새로운 방식인 에이전트 스킬을 개발했고, 오픈 표준으로 공개했다. 단일 파일 방식에서 벗어나, SKILL.md 파일을 중심으로 한 디렉토리 구조를 새롭게 채택했다. 이를 통해 실행 스크립트(scripts/)와 참조 문서(references/)를 분리하여 체계적인 관리가 가능해졌다. 사용자 의도를 파악해 0.1초 만에 알아서 스킬을 활성화하는 자동 호출(Model-invoked) 기능이 도입되었다.

필요한 순간에만 문서를 읽어들이는 점진적 정보 노출(Progressive Disclosure) 메커니즘을 적용하여 컨텍스트 토큰 소비를 극적으로 줄였다. 점진적인 정보 노출 메커니즘은 에이전트가 한정된 컨텍스트 윈도우(토큰)를 극도로 효율적으로 관리하기 위해 채택한 핵심 설계 원칙이다. 이 메커니즘은 수십 개의 스킬이 설치되어 있더라도 에이전트가 모든 내용을 처음부터 다 읽지 않게 막아주며, 발견(Discovery), 활성화(Activation), 실행(Execution)의 3단계로 정보를 나누어 필요할 때만 로드한다.

1. 발견 - 카탈로그 로드
   • 세션이 시작될 때, 에이전트는 사용 가능한 모든 스킬의 이름(name)과 설명(description)만 카탈로그 형태로 읽어 들인다.
   • 이 단계에서는 스킬당 약 50~100개의 토큰만 소모된다. 에이전트는 이 최소한의 정보만으로도 “어떤 스킬들이 존재하는지”, “언제 이 스킬을 써야 하는지”를 판단할 수 있다.
2. 활성화 - 지시사항 로드
   • 사용자의 요청이 특정 스킬의 설명과 일치하여 에이전트가 해당 스킬이 필요하다고 판단하면, 그제야 SKILL.md 파일의 전체 본문(지시사항)을 컨텍스트로 읽어 들인다.
   • 가장 핵심적인 로직이 담겨 있으며 권장 크기는 5,000 토큰 이하다. 사용되지 않는 스킬의 본문은 무시되므로 토큰 낭비가 발생하지 않는다.
3. 실행 및 자원 활용 - 리소스 온디맨드 로드
   • SKILL.md 본문 내용에는 지시사항뿐만 아니라 외부 참조 파일(scripts/, references/, assets/ 등)에 대한 경로가 포함되어 있을 수 있다.
   • 에이전트는 이 추가 리소스들을 한 번에 로드하지 않고, 지시사항을 수행하는 과정에서 특정 파일의 정보나 스크립트 실행 결과가 정말로 필요한 순간(on-demand)에만 개별적으로 로드한다.

2. SKILL.md structure

SKILL.md 파일은 크게 설정값을 정의하는 YAML 프론트매터(Frontmatter)와 에이전트가 수행할 실제 지시사항을 담은 마크다운 본문(Markdown Body)으로 구성된다. 먼저 프론트매터는 YAML 형식으로 마크다운 파일 최상단에 ---로 감싸서 작성하며, 스킬의 메타데이터와 실행 환경(트리거 조건, 권한, 서브에이전트 사용 여부 등)을 통제한다. 다음과 같은 정보가 담긴다.

• name
  • 스킬의 고유 이름이다. 최대 64자, 소문자/숫자/하이픈만 허용한다.
  • 사용자가 /스킬이름 형태로 명시적 호출을 할 때 사용된다.
• description (required)
  • AI 에이전트가 의도를 파악해 스킬을 자동 호출(Auto-trigger)할 때 사용하는 핵심 필드다.
  • 50~1024자 사이로 “무엇을 하는지”, “언제 사용하는지”, “어떤 키워드에 반응할지”를 구체적으로 명시해야 한다.
• disable-model-invocation
  • true 값으로 설정하면 AI 에이전트의 자동 호출을 막고, 오직 사용자가 / 명령어를 입력했을 때만 실행된다.
  • 커밋, 배포 등 원치 않게 실행되면 안 되는 작업에 유용하다.
• user-invocable
  • false 값으로 설정하면 사용자의 / 명령어 메뉴에서 숨긴다.
  • 배경 지식이나 팀 규칙처럼 AI 에이전트만 백그라운드에서 참고해야 하는 스킬에 사용한다.
• allowed-tools
  • 스킬 실행 중 AI 에이전트가 권한 허용을 묻지 않고 바로 사용할 수 있는 도구(예: Bash, Read)를 화이트리스트 형태로 제한한다.
• context 및 agent
  • context: fork 값으로 설정하면 메인 대화창의 컨텍스트를 오염시키지 않고 완전히 격리된 새로운 컨텍스트에서 서브(sub)에이전트가 작업을 백그라운드로 실행한다.
  • 이때 agent 필드로 특정 에이전트(예: Explore)를 지정할 수 있다.

이 외에도 프로퍼티들이 존재한다. 자세한 내용은 이 링크를 참조하길 바란다. 프론트매터는 다음과 같이 작성할 수 있다.

---
name: explain-code
description: Use this skill when the user asks how a piece of code works, mentions "explain", "코드 설명", or wants to understand a complex function. Keywords: explain, 설명, 분석
disable-model-invocation: false
allowed-tools: ["Read", "Bash"]
context: fork
agent: Explore
model: sonnet
---

마크다운 본문은 프론트매터 아래에 작성한다. 어떤 내용이 들어가면 좋을까? AI 에이전트가 스킬 호출 시 실제로 읽고 따를 구체적인 가이드라인이다. 목적(Purpose), 명세(Specification), 리팩터링(Refinement)의 3단계 구조로 나누어 작성하는 것이 권장된다.

• 목적(Purpose) - “이 스킬은 무엇을 합니까?”를 명확히 정의한다. 에이전트에게 작업의 큰 그림을 제시한다.
• 명세(Specification) - “어떻게 동작합니까?”를 구체적으로 정의하며, 사용할 도구와 단계별 절차를 포함한다.
• 리팩터링(Refinement) - “왜 이렇게 작성했는가?”를 설명한다. 작성 이유와 설계 결정(제한 사항 등)을 포함하여 에이전트가 맥락을 깊이 이해하게 돕는다.

단순히 잘 작성하는 것보다 구체적으로 아래와 같은 내용들을 참고하면 좋다.

• 에이전트가 이미 아는 일반적인 지식(e.g. PDF 개념, HTTP 개념)은 과감히 생략하고, 프로젝트만의 특정 규약, 엣지 케이스, 고유한 API 패턴 등 에이전트가 스스로 알 수 없는 내용만 담아 컨텍스트 토큰을 절약해야 한다.
• 프로젝트 특유의 주의사항을 명시한다. 예를 들어, “users 테이블은 소프트 삭제(soft delete)를 하므로 항상 ‘where deleted_at is null’ 조건을 쿼리에 포함해야 한다.”와 같은 실무적인 예외 규칙을 적어두면 에러를 방지할 수 있다.
• 복잡한 작업은 체크박스([ ]) 형태의 단계별 워크플로우로 나누어 지시하는 것이 좋다.
• 에이전트가 생성할 결과물의 마크다운 구조나 데이터 포맷 템플릿을 본문 내에 제공하면 훨씬 일관된 결과물을 얻을 수 있다.
• 작업을 한 번에 끝내지 말고, ‘계획-검증-실행’ 루프를 지시사항에 포함하도록 한다.
  • 예를 들면, “1. 스크립트를 실행해 폼을 채운다. 2. validate_fields.py 스크립트로 검증한다. 3. 실패하면 에러를 읽고 수정하여 다시 검증한다.” 같이 체계적인 검증 루프를 명시한다.
• 마크다운 본문 길이는 가급적 500줄 이하로 유지해야 한다. 방대한 API 명세서나 코드는 본문에 직접 넣지 말고 references 디렉토리에 분리한 뒤, 본문에서는 파일의 상대 경로만 참조하도록 작성한다.

다음과 같은 고급 기능들을 지원한다.

본문 내에 백틱(`)과 느낌표(!)를 결합하여 쉘 명령어를 작성하면 AI 에이전트에게 프롬프트가 전달되기 전에 시스템이 해당 명령어를 먼저 실행하고 그 출력값을 본문에 실시간으로 주입한다. 예를 들어, 현재 PR(pull request) 변경 사항을 즉시 반영하려면 본문에 아래처럼 적어둔다.

## Git PR 변경 사항 반영

!`gh pr diff`

사용자가 스킬을 호출할 때 전달한 인자(arguments)나 런타임 환경 변수를 마크다운 본문에 동적으로 삽입할 수 있다.

• $ARGUMENTS: 사용자가 입력한 전체 인자를 가져온다.
• $ARGUMENTS[N] 또는 $N: 특정 순서의 인자만 선택적으로 가져온다(예: $0, $1).
• ${CLAUDE_SKILL_DIR}: 해당 스킬 폴더의 절대 경로를 나타내며, 쉘 명령어 주입 시 내부 스크립트의 경로를 가리킬 때 매우 유용하다.
• ${CLAUDE_SESSION_ID}: 현재 대화의 고유 세션 ID로, 세션별 로그나 임시 파일을 만들 때 사용한다.

본문에 도구 사용을 지시할 때는 “파일을 읽어보세요”처럼 두루뭉술하게 쓰기보다, “read_file 도구를 호출하라”처럼 사용할 도구의 이름을 동사 형태로 명확히 지정해 주는 것이 훨씬 동작 확률을 높인다.

위 개념들을 모두 적용해서 사용자의 코드를 분석하고 비유와 다이어그램을 곁들여 설명해 주는 스킬의 SKILL.md 작성 예시를 살펴보자. 이렇게 구성하면, 프론트매터는 “사용자가 ‘코드 설명’을 요구할 때, 별도의 서브에이전트(fork)를 띄워 파일 읽기 권한을 가지고 실행”하도록 AI 에이전트를 통제한다. 마크다운 본문은 전달받은 인자($ARGUMENTS)와 현재 작업 중인 브랜치 상태를 실시간 터미널 결과를 통해 융합하여 정교하면서도 동적인 결과물을 만들게 된다.

---
name: explain-code
description: Use this skill when the user asks how a piece of code works, mentions "explain", "코드 설명", or wants to understand a complex function. Keywords: explain, 설명, 분석
disable-model-invocation: false
allowed-tools: ["Read", "Bash"]
context: fork
agent: Explore
model: sonnet
---

# Purpose (목적)
이 스킬은 사용자가 제시한 코드나 파일의 동작 원리를 분석하고, 비유(analogy)와 ASCII 다이어그램을 활용해 시각적이고 직관적으로 설명하는 역할을 합니다.

# Specification (명세)
1. 사용자가 입력한 다음 내용 및 코드를 분석하세요:
   $ARGUMENTS
2. 코드가 수행하는 핵심 로직을 3줄 이내로 요약하세요.
3. 기술적 배경이 없는 사람도 이해할 수 있도록 일상적인 '비유(analogy)'를 들어 설명하세요.
4. 로직의 흐름이나 데이터 구조를 나타내는 간단한 ASCII 다이어그램을 그리세요.
5. 필요한 경우 `${CLAUDE_SKILL_DIR}/scripts/analyze.sh` 스크립트를 실행하여 추가적인 코드 메타데이터를 수집하세요.

현재 작업 중인 브랜치 상태 (동적 컨텍스트 주입):
!`git status -s`

# Refinement (리팩터링/제한사항)
- 설명의 최종 결과물은 반드시 한국어로 작성하세요.
- 너무 깊은 기술적 용어(AST 파싱 등)는 피하고 직관적인 이해를 돕는 데 집중해야 합니다.

3. Skill directory structure

스킬의 사용 목적과 범위에 따라 적절한 디렉토리에 저장해야 한다. 개인/범용 스킬은 모든 프로젝트에서 공통으로 사용하려면 홈 디렉토리의 ~/.claude/skills/에 저장한다. 다양한 에이전트 클라이언트와 호환되는 범용 규약을 따르려면 ~/.agents/skills/ 경로를 사용할 수도 있다.

특정 프로젝트에서만 사용하려면 프로젝트 루트의 .claude/skills/에 저장한다. 오픈 표준 규약으로는 .agents/skills/를 사용할 수 있다. 하위 폴더에서 작업할 때도 에이전트가 스킬을 자동 탐색하므로, packages/frontend/.claude/skills/와 같이 중첩된 디렉토리 구조를 구성할 수 있다.

하나의 스킬 폴더(my-skill/)는 에이전트의 컨텍스트 윈도우(토큰)를 절약하고 유지보수를 쉽게 하기 위해 다음과 같이 모듈화하여 구성하는 것이 가장 이상적이다.

• SKILL.md (중심 진입점)
  • YAML 프론트매터(Frontmatter)와 마크다운 본문으로 구성된 필수 파일이다.
  • 컨텍스트 토큰 절약을 위해 본문 길이는 가급적 500줄 이하로 유지하는 것이 권장된다.
• scripts/ (스크립트)
  • 에이전트가 직접 실행할 수 있는 Python, Bash, JavaScript 등의 코드를 분리하여 저장한다.
  • 스크립트를 사용하면 에이전트가 매번 코드를 생성하지 않아도 되므로 일관되고 결정론적인 결과를 얻을 수 있다.
• references/ (참조 문서)
  • API 명세서, 복잡한 데이터 포맷 등 부피가 큰 문서를 저장한다.
  • 에이전트는 사용자의 요청에 따라 정말로 해당 지식이 필요한 순간에만 이 파일들을 로드한다.
• assets/ (정적 리소스)
  • 문서 템플릿, 다이어그램 예시, 조회용 데이터 테이블(스키마) 등 스킬 실행이나 결과물 생성에 필요한 정적 파일들을 모아둔다.
• evals/ (평가 및 테스트)
  • 스킬이 제대로 동작하는지 검증하기 위한 테스트 프롬프트(evals.json)를 저장하여 테스트 주도 개발 방식으로 스킬의 품질을 평가한다.

my-skill/
├── SKILL.md            # (필수) 스킬의 메타데이터와 핵심 지시사항
├── scripts/            # (선택) 실행 가능한 스크립트 파일
│   ├── analyze.py
│   └── format.sh
├── references/         # (선택) 추가 참조 문서
│   ├── schema.yaml
│   └── guidelines.md
├── assets/             # (선택) 정적 리소스 및 템플릿
│   └── report-template.md
└── evals/              # (선택) 스킬 테스트 및 평가 데이터
    └── evals.json

4. Reuse skills

이미 많은 에이전트 스킬들이 존재한다. “거인의 어깨에 올라가라”라는 말이 있듯이 잘 만들어진 스킬들을 재사용하는 게 좋다. skills.sh 사이트에 접속하면 이미 만들어진 스킬들을 검색해서 사용할 수 있다.

가장 많이 설치된 스킬은 find-skills다. 많은 스킬들 중 자신이 필요한 스킬을 찾는 스킬이 가장 인기가 많다. 이를 npx skills 명령어를 통해 쉽게 설치할 수 있다. find-skills 스킬을 설치해서 사용해 보자.

$ npx skills add vercel-labs/skills

해당 스킬을 사용해보자. 나는 코파일럿 에이전트를 사용했다. 에이전트를 실행한다.

$ copilot

에이전트가 사용할 수 있는 스킬 리스트를 살펴보자.

/skills list

두 개의 스킬을 확인할 수 있다.

Available Skills

Project:
  • calculator
    단순한 더하기 계산기. 사용자가 전달한 숫자들을 더한다. "더해줘", "더하기"
등의 명령어로 실행할 수 있다.

Inherited:
  • find-skills
    Helps users discover and install agent skills when they ask questions like
"how do I do X", "find a skill for X", "is there a skill that can...", or
express interest in extending capabilities. This skill should be used when the
user is looking for functionality that might exist as an installable skill.

Found 2 skills. Use /skills info <name> to view details.

위에서 설치한 find-skills 스킬을 사용해보자. “extreme programming” 키워드로 검색해보니, proffesor-for-testing/agentic-qe@xp-practices라는 스킬을 찾아줬다.

/find-skills "extreme programming"

◐ The user wants me to invoke the "find-skills" skill.

● skill(find-skills)

◐ The user wants to find skills related to "extreme programming". Let me follow the
   skill's instructions:

  1. First, check the skills.sh leaderboard
  2. Search for skills using `npx skills find extreme programming`

  Let me do both in parallel.

● Fetching web content https://skills.sh/
  └ Contents of https://skills.sh/:

● Search for extreme programming skills (shell)
  │ npx skills find extreme programming 2>&1 | head -50
  └ 27 lines...

◐ Let me check the top results more carefully. The most relevant ones seem to be:
  1. `wondelai/skills@software-design-philosophy` - 190 installs
  2. `wondelai/skills@pragmatic-programmer` - 165 installs
  3. `proffesor-for-testing/agentic-qe@xp-practices` - 60 installs (XP practices
  seems directly related to extreme programming)

  Let me check the details of the more relevant ones, particularly
  `wondelai/skills@software-design-philosophy` and
  `proffesor-for-testing/agentic-qe@xp-practices`.

● Fetching web content https://skills.sh/wondelai/skills/software-design-philosophy
  └ Contents of https://skills.sh/wondelai/skills/software-design-philosophy:

● Fetching web content https://skills.sh/proffesor-for-testing/agentic-qe/xp-pract…
  └ Contents of https://skills.sh/proffesor-for-testing/agentic-qe/xp-practices:

● Extreme Programming 관련 스킬을 찾았습니다! 직접 관련된 스킬이 하나 있습니다:

  ------------------------------------------------------------------------------

  ✅ proffesor-for-testing/agentic-qe@xp-practices — 60 installs

  XP(Extreme Programming) 핵심 실천법을 다루는 스킬입니다:

   - TDD (Test-Driven Development)
   - Continuous Integration
   - Pair Programming (Driver-Navigator, Ping-Pong 방식)
   - Collective Ownership & Small Releases
   - AI 에이전트 연동 워크플로우 포함

  🔗 https://skills.sh/proffesor-for-testing/agentic-qe/xp-practices

   npx skills add proffesor-for-testing/agentic-qe@xp-practices

  ------------------------------------------------------------------------------

   ⚠️ 60 installs로 인지도가 낮은 편입니다. 신중하게 사용하세요.

5. Example

직접 간단한 더하기 계산 스킬을 만들어본다. 다음과 같은 스킬 구조를 만든다.

.
└── .agents
    └── skills
        └── calculator
            ├── SKILL.md
            └── scripts
                └── add.py

SKILL.md 파일은 다음과 같이 작성한다.

---
name: calculator
description: 단순한 더하기 계산기. 사용자가 전달한 숫자들을 더한다. "더해줘", "더하기" 등의 명령어로 실행할 수 있다.
---

# Purpose (목적)

이 스킬은 사용자가 전달한 숫자들을 더하는 역할을 한다.

# Specification (명세)

현재 전달 받은 숫자들을 더하는 방법은 `${CLAUDE_SKILL_DIR}/scripts/add.py` 스크립트를 사용한다. 사용 예시는 다음과 같다.

``bash
python3 ${CLAUDE_SKILL_DIR}/scripts/add.py $ARGUMENTS[0] $ARGUMENTS[1]
``

코파일럿에서 다음과 같이 프롬프트를 전달한다.

1 2 3 4 5 더해줘

“더해줘”라는 키워드를 보고 코파일럿이 적절한 스킬을 찾는다. 아래처럼 calculator 스킬을 선택 후 실행 결과를 알려준다.

● skill(calculator)

● Add 1 2 3 4 5 (shell)
  │ python3 /Users/junhyunny/Desktop/action-in-blog/.agents/skills/calculator/scrip
  │ ts/add.py 1 2 3 4 5
  └ 2 lines...

● 1 + 2 + 3 + 4 + 5 = 15

TEST CODE REPOSITORY

• https://github.com/Junhyunny/blog-in-action/tree/master/2026-03-22-skills-md

REFERENCE

• https://agentskills.io/home
• https://agentskills.io/what-are-skills
• https://agentskills.io/specification
• https://agentskills.io/skill-creation/best-practices
• https://agentskills.io/skill-creation/optimizing-descriptions
• https://agentskills.io/skill-creation/evaluating-skills
• https://agentskills.io/client-implementation/adding-skills-support
• https://code.claude.com/docs/en/skills
• https://github.com/anthropics/skills
• https://skills.sh/
• https://goddaehee.tistory.com/528
• https://discuss.pytorch.kr/t/everything-claude-code-anthropic-x-forum-ventures-claude-code/8740