AI 에이전트를 위한 SKILL.md 및 도구 설명을 마크다운으로 작성하는 방법

AI 비서가 일관성 있는 지침을 따르고, 특정 업무 도메인의 배경 지식을 활용하며, 외부 도구들을 안전하게 사용할 수 있을 때 그 진정한 가치가 발휘됩니다. 마크다운(Markdown)은 이러한 설정과 지침을 작성하기에 가장 이상적인 포맷입니다. 사람이 읽고 버전 관리를 하기 편하면서도, 대형 언어 모델(LLM)이 정확하게 해석할 수 있는 명확한 논리 구조를 제공하기 때문입니다.

이 글에서는 마크다운을 활용한 에이전트 스킬 파일(SKILL.md), 에이전트 시스템 지침서, 그리고 도구 호출용 설명서를 설계하는 원칙과 방법을 다룹니다. 우리의 궁극적인 목적은 프롬프트의 길이를 무작정 늘리는 것이 아닙니다. AI 에이전트가 주어진 능력을 손쉽게 탐색하고, 정확히 이해하며, 올바른 시점에 한 치의 오차 없이 실행하도록 유도하는 것입니다.

SKILL.md 파일이란 무엇인가

SKILL.md 파일은 재사용 가능한 특정 비즈니스 처리 능력(스킬)을 기술해 놓은 마크다운 형식의 업무 매뉴얼입니다. Anthropic의 Claude Code 등 최신 에이전트 시스템에서는 스킬이 파일시스템 내 특정 폴더에 물리적으로 적재되며, 각 스킬은 개별 SKILL.md 파일을 통해 동작을 정의합니다. 시스템에 따라 파일명은 다를 수 있지만 코어 아이디어는 동일합니다. **"에이전트가 어떤 상황일 때 이 스킬을 활성화해야 하는가", "수행 시 따라야 할 작업 워크플로는 어떻게 구성되는가", "관련 보조 스크립트나 참조 규정집은 어디에 보관되어 있는가"**를 설명해 둔 구조화된 문서입니다.

AI 시스템을 설계할 때 다음과 같은 간단한 개념 모델을 장착하면 이해하기 쉽습니다:

• 일반 프롬프트: AI에게 "지금 당장 해야 할 구체적인 미션"을 내릴 때 씁니다.
• 에이전트 스킬 (SKILL.md): AI에게 "특정 유형의 과제군"을 앞으로 계속 반복해서 처리하는 표준 절차를 가르칠 때 씁니다.
• 도구 설명 (Tool Description): AI에게 "정해진 외부 API 함수"를 언제, 어떤 파라미터로 호출해야 하는지 가이드할 때 씁니다.

스킬은 작동 원리상 지침, 실행 가이드라인, 제약사항, 보조 자료 링크가 내용의 90% 이상을 차지하므로, 마크다운 문서 형식이 가장 완벽하게 어울립니다.

왜 마크다운은 에이전트 스킬 작성에 적합한가

에이전트 지침 문서는 'AI 모델'과 '인간 개발자'라는 두 다른 주체가 동시에 해독할 수 있어야 합니다. 마크다운은 두 타겟층을 모두 완벽하게 서포트합니다.

AI 모델에게는 마크다운의 제목과 리스트 태그가 스킬 활성화 조건, 세부 동작 순서, 강제 제약조건, few-shot 템플릿 예시, 예외 대응 전략 등을 정확하게 분리해 주는 이정표가 됩니다. 인간 개발자에게는 텍스트 에디터로 언제든 편하게 열어보고, Git을 통해 줄 단위의 세부 규정 변경 이력(Review)을 관리하며, 소스 코드와 완벽히 격리된 문서 형태로 배포할 수 있는 인프라가 됩니다.

이는 스킬이나 도구를 설계할 때 치명적으로 중요한 요인입니다. 지침이 모호하면 자율형 에이전트의 자동화 실행 과정에서 심각한 오작동이 유발되기 때문입니다. 명세가 애매한 스킬은 엉뚱한 맥락에서 켜지고, 날림으로 작성된 도구 설명은 오염된 매개변수 주입을 초래하여 API 오류를 일으킵니다. 안전 규칙이 누락되면 에이전트는 근거 자료를 제대로 검증하지 않은 채 위험한 로컬 쓰기 명령을 수행하기도 합니다.

스킬(Skills)과 도구 설명(Tool Descriptions)의 본질적 차이

스킬과 도구는 에이전트의 팔과 다리가 되어준다는 점에서는 비슷하지만, 맡은 포지션과 수준이 다릅니다:

| 구성 요소 | 핵심 역할 | 전형적인 예시 | |---|---|---| | 스킬 (Skill) | 복합적인 업무 처리 프로세스나 도메인 가이드라인을 교육함 | "풀 리퀘스트(PR) 소스 코드 리뷰 및 병합 가이드" | | 도구 설명 (Tool) | 호출 가능한 프로그래밍 함수명, 파라미터 규격, 리턴값 전달 | "키워드 쿼리로 관련 데이터베이스 테이블 검색" | | 시스템 프롬프트 | 비서 전체의 핵심 퍼소나, 말투, 기저 행동 규칙 수립 | "언제나 핵심만 답변하고, 근거 없이 짐작하지 말 것" | | 프로젝트 지침서 | 현재 소스 레포지토리 내부의 고유 개발 규칙 규정 | "pnpm 빌드 도구를 쓰고, 요청 전에는 빌드 명령을 삼갈 것" |

OpenAI의 Function Calling(함수 호출) 및 에이전트 SDK 매뉴얼을 살펴보면 도구(Tools)는 모델이 자기 경계를 넘어 외부 API를 호출하거나, 코드 샌드박스를 작동시키거나, 데이터를 가져오기 위한 접점으로 설명됩니다. 공식 지침서들은 "도구가 처리할 핵심 임무"와 "도구를 켜야 할 적절한 동기"를 담은 짧고 명료한 도구 설명을 지필하라고 권고합니다. 이 공식은 마크다운 스킬에도 동일하게 유효합니다. 활성화 타이밍과 명확한 해결 능력을 기술해야 합니다.

SKILL.md 마크다운 템플릿 양식

실전에서 활용도가 높은 스킬 정의 문서는 반드시 다음 6가지 질문에 정답을 제시해야 합니다.

1. 이 스킬이 제공하는 구체적인 비즈니스 가치가 무엇인가?
2. 에이전트가 어떤 맥락일 때 이 스킬을 활성화해야 하는가?
3. 어떤 정황일 때는 이 스킬을 절대 켜면 안 되는가?
4. 작업 완수를 위해 에이전트가 실행해야 할 표준 단계는 무엇인가?
5. 연동하여 구동할 수 있는 로컬 파일, 외부 스크립트, 레퍼런스는 무엇인가?
6. 사용자와 시스템에 최종적으로 넘길 결과물의 형상은 어떠해야 하는가?

다음은 표준 구조 템플릿입니다:

---
name: markdown-conversion-review
description: 사용자가 PDF, Word, HTML 등에서 추출 가공된 마크다운 결과물의 오탈자나 레이아웃 문제를 감사하고 정제하고자 할 때 호출하는 스킬.
---

# 스킬명: 마크다운 변환 결과물 감사 및 정제

## 활성화 타이밍 (Use This Skill When)
- 사용자가 변환된 마크다운 텍스트의 가독성 개선이나 마크다운 문법 규격 교정을 의뢰할 때.
- 가공 데이터를 프로젝트 README, 서비스 기술 매뉴얼, 블로그 배포 포스트, 혹은 프롬프트 주입용 컨텍스트로 최적화할 때.
- 원문에서 추출된 테이블 마커, 제목 태그 계층, 각주 하이퍼링크가 망가져 보정이 시급할 때.

## 비활성화 조건 (Do Not Use This Skill When)
- 사용자가 단순히 마크다운의 기초적인 문법 규격을 질문하는 수준일 때.
- 현재 할당받은 문서 수정 작업과 무관한 외부 소스 디렉토리 파일을 수정해야 할 때.

## 표준 작업 워크플로 (Workflow)
1. **구조 분석**: 입력된 마크다운 지문의 구조적 결함(제목 계층 꼬임, 테이블 포맷 파손, 링크 유실, 닫히지 않은 코드 블록 등)을 스캔합니다.
2. **원문 맥락 수호**: 정제 과정에서 원작자의 본래 서술 취지와 문장 선후 관계를 철저히 보존하며, 명확한 요청 없는 과도한 창작식 쓰기는 배제합니다.
3. **포맷正規化**: 단순하고 직관적인 표준 마크다운 문법만 사용하여 문서의 제목, 테이블, 리스트, 코드 블록을 정돈합니다.
4. **한계 기록**: 원본 레이아웃의 고유 기하학적 복잡성으로 인해 표준 마크다운으로 온전히 복구하지 못한 영역은 파일 하단에 감사 보고서 형태로 기록합니다.
5. **결과물 제공**: 보정이 완료된 클린 마크다운 본문과 함께 변환 작업 노트를 작성하여 전달합니다.

## 품질 보증 기준 (Quality Bar)
- 원본 소스에 기록되지 않은 미상의 정보를 독단적으로 지어내지 말 것.
- 개발용 코드 블록은 사용자 요청이 없으면 원래 코드를 온전히 한 자도 바꾸지 않고 보존할 것.
- 불필요한 HTML 태그의 남용을 금하고, 기본 표준 마크다운 문법의 가독성을 최우선시할 것.

## 최종 출력 규격 (Output Format)
아래의 구조대로 응답을 반환할 것:
1. 정제가 완료된 마크다운 결과물 본문
2. 작업 요약 보고서 및 변환 핵심 조치 사항
3. 복구 불가능했던 서식 한계 및 의문 사항 리스트

문서 맨 위의 Frontmatter(메타데이터) 필드는 사용하시는 에이전트 코어의 명세(예: Claude Code 스킬 파일 구조 등)에 맞춰 수정하시면 되며, 본문의 구성(조건, 제외 시나리오, 워크플로 단계, 품질 보증 등)은 어떤 환경에서든 동일하게 이식 가능합니다.

고품질 설명(Description) 필드를 지필하는 원칙

스킬이든 도구든 메타 정보 상의 description 한 줄은 AI가 해당 임무를 나에게 배정할지 말지를 결정하는 의사결정의 핵심 단서입니다.

피해야 할 설명문 서술:

description: 마크다운 편집을 도와주는 기능입니다.

권장하는 설명문 서술:

description: 사용자가 변환 가공 완료된 마크다운 문서의 포맷 정상화 및 가독성 향상 처리를 지시하거나, 문서를 개발 리포지토리 README, 기술 블로그 포스팅 원고, 혹은 AI 프롬프트용 지식 소스 데이터로 최적화해 달라고 요청할 때 실행하는 스킬.

바람직한 설명문은 아래 4요소를 모두 명료하게 포함합니다:

• 실행 타이밍: "사용자가 ~을 지시하거나, ~해 달라고 요청할 때"
• 구체적인 가치 액션: "포맷 정상화 및 가독성 향상 처리, 혹은 최적화"
• 대상 원자재: "변환 가공 완료된 마크다운 문서"
• 소비되는 최종 맥락: "개발 리포지토리 README, 기술 블로그 포스팅 원고, 혹은 AI 프롬프트용 지식 소스 데이터"

API 도구 설명서(Tool Description)의 간결화 공식

도구 정의서(Tool Specification)는 스킬에 비해 훨씬 컴팩트하게 구성되어야 합니다. 컴퓨터의 구체적인 함수 인터페이스를 묘사하는 장치이므로, 모델에게 아래 세 가지 팩트만 즉각 통보하면 충분합니다.

• 이 컴퓨터 기능이 실제로 수행하는 정확한 액션이 무엇인가?
• 이를 구동하기 위해 필요한 정확한 입력 변수(Parameters)와 데이터 형식은 무엇인가?
• 구동 후 반환되는 결과 객체의 형상은 어떠한가?

JSON 포맷의 도구 명세 예시:

{
  "name": "convert_file_to_markdown",
  "description": "사용자가 업로드한 PDF, DOCX, PPTX, XLSX, HTML 혹은 이미지 파일을 AI 파이프라인이 즉각 연산 처리하기 좋게 가벼운 마크다운 텍스트 문서로 변환하고 구조화할 때 호출하는 컴퓨터 함수.",
  "parameters": {
    "type": "object",
    "properties": {
      "file_id": {
        "type": "string",
        "description": "변환을 개시할 대상 파일의 고유 식별 시스템 ID."
      },
      "preserve_tables": {
        "type": "boolean",
        "description": "문서 내부에 매립된 데이터 표를 유실 없이 마크다운 격자 구조로 유지할지 여부. 기본값은 true."
      }
    },
    "required": ["file_id"]
  }
}

화려한 미사여구 없이 지원 확장자, 목적 조건, 매개변수들의 실무적 의미를 정밀하게 명시했습니다. 이렇게 선언해 두면 모델이 매개변수를 엉뚱하게 오판하거나 누락하는 호출 불량률이 비약적으로 낮아집니다.

마크다운 포맷을 활용한 API 도구 명세 보완

코드 소스 상에 툴의 JSON 스펙이 고정되어 있더라도, 별도의 마크다운 문서 파일로 에이전트를 위한 '인용 설명서'를 작성해 주는 습관은 매우 바람직합니다.

# 도구 가이드북: convert_file_to_markdown

## 기능 개요
지원되는 다양한 문서를 마크다운 문서로 포맷 스위칭합니다.

## 올바른 활성화 시나리오
- 사용자가 탐색기에 파일을 드롭하고 마크다운 변환을 직관적으로 요구할 때.
- 텍스트 분석에 앞서 지문을 RAG 인덱서에 넣기 좋게 사전 처리(Pre-processing)하고자 할 때.

## 잘못된 비활성화 시나리오
- 사용자가 마크다운의 스펙 등에 대해 학술적인 토론을 유도할 때.
- 이미 가공 처리가 끝난 완성형 마크다운 파일을 건넸을 때.

## 입출력 명세
| 파라미터명 | 데이터 타입 | 필수 여부 | 매개변수 설명 |
|---|---|---:|---|
| file_id | string | 필수 | 변환 개시 대상 파일 ID |
| preserve_tables | boolean | 선택 | 표 형식을 최대한 살릴지 결정 여부 |

## 출력 반환 포맷
보정이 끝난 마크다운 문서 데이터 본문 및 변환 상의 정합성 경고 메모.

## 예외 사항 대응
- 지원하지 않는 압축 파일 등의 규격이 접수되면 즉시 사용 가능 문서 목록을 응답하고 실행을 정지합니다.
- 복잡한 그래픽 레이아웃 유실 우려 시, 구조 복구가 가능한 원본 지문만 리턴하고 파일 경고 카드를 붙입니다.

이는 컴퓨터 인터페이스 코드만 보고서는 파악할 수 없는 '실무 운영의 안전 규칙'을 AI에게 주입해 주는 최고의 보강 장치가 됩니다.

AI가 기뻐하는 훌륭한 스킬 문서의 조건

에이전트가 믿고 읽는 좋은 스킬 문서는 극도로 구체적인 현장 지침들을 담고 있습니다.

1. 활성화 경계선의 정밀함

추상적이고 거창한 타이틀을 달아두면 에이전트는 사용처를 헷갈립니다.

안 좋은 타이틀:

# SEO 가이드

좋은 안내 가이드:

## 활성화 타이밍
- 사용자가 특정 테크니컬 문서의 검색엔진 상위 랭크(SEO) 최적화를 위임할 때.
- 콘텐츠에 핵심 키워드가 잘 반영된 제목(H2/H3), 메타 태그, 앵커 링크 혹은 자주 묻는 질문(FAQ)의 보강이 요구될 때.
- 사용자가 구글의 E-E-A-T 품질 가이드라인 혹은 검색 유용성 업데이트(Helpful Content) 대응을 직접 거론할 때.

2. 강력한 금지 조건 (Non-Goals)의 설계

"절대 해서는 안 될 일"을 나열하는 것은 AI 어시스턴트의 가드레일을 세우는 가장 파워풀한 방법입니다.

## 명확한 배제 상황
- 법률적 소송 가이드, 의료 의약품 추천, 금융 자산 투자 조언 등 공인 면허가 강제되는 라이선스 영역의 상담 요청이 들어올 때.
- 작업 요건을 만족하기 위해 가짜 고객 후기나 임의의 통계 그래프 수치, 허위 각주 출처를 악의적으로 날조해야만 할 때.
- 타겟 문서의 본질이 우리 브랜드 정체성 혹은 사용자 서비스 요건과 논리적으로 전혀 닿아있지 않을 때.

3. 액션 중심의 흐름도 작성

어려운 작업도 순차적으로 해결해 갈 수 있게 순서가 지정된 단계별 리스트를 작성해 줍니다. 에이전트가 자율성을 발휘할 수 있는 유연한 범위를 두되, 놓쳐서는 안 될 고비를 명시합니다.

4. 올바른 표현 예시와 틀린 표현 예시의 대비

추상적인 묘사보다 직관적인 문장 비교 예시(Few-shot)가 100배 효율적입니다.

## 문체 스타일 적용 사례

- **안 좋은 표현 양식 (지양할 것)**:
  "이 환상적인 컨버터는 업로드하는 모든 파일을 어떠한 에러도 없이 백 퍼센트 완전무결하게 바꾸어 줍니다."
  *(비추천 이유: 근거 없는 신뢰를 강요하며 마케팅성 거품이 과하여 사용자의 신뢰를 해침)*

- **좋은 표현 양식 (추천할 것)**:
  "이 변환기는 다양한 오피스 지문을 마크다운 텍스트로 보정합니다. 인풋 원본이 체계적인 제목, 불릿 기호, 단순 격자형 표로 구성되어 있을 때 가장 신뢰성 높은 결과물을 추출해 냅니다."
  *(추천 이유: 사실에 기반하여 제품이 가진 솔직한 혜택과 기술적 한계를 균형감 있게 전달함)*

5. 안전 가이드라인 및 로컬 권한 명시

에이전트가 명령줄 스크립트를 직접 돌리거나 로컬 디렉토리의 민감한 핵심 파일에 쓰기 작업을 수행한다면 안전 한계를 못 박아 두어야 사고를 방지합니다.

## 안전 규약 및 권한 경계
- 기존 리포지토리 파일을 에디터로 덮어쓰기 전에, 무조건 원본 내용 전체를 한 번 메모리로 호출하여 감사할 것.
- 사용자에게 사전 양해를 구하고 chat 상에서 허가를 얻은 상황이 아니라면, 로컬 파일을 임의로 영구 삭제하지 말 것.

작성 시 빠지기 쉬운 함정

• 함정 1: 스킬 하나에 온갖 능력을 때려 넣기: 스킬은 오직 하나의 유기적인 미션에만 집중해야 합니다. 마케팅 스킬이라 쓰고 SEO, 구글 광고, 이메일 스팸 작정, 고객 서베이 분석을 다 구겨 넣으면 에이전트는 문맥 오류를 일으킵니다.
• 함정 2: 미사여구 기반의 지침 기술: "세계 최고의 품질로 문장을 장식할 것" 같은 목표는 AI에게 공허한 소리입니다. "출처 각주 링크를 삽입할 것", "텍스트를 150단어 이내로 규제할 것" 등 관측 및 검증 가능한 조건으로 지시하세요.
• 함정 3: 중요한 규칙을 일반 단락 속에 숨기기: 에이전트는 장문의 긴 줄글 한복판에 박혀 있는 규칙은 높은 확률로 망각합니다. 핵심 가이드와 경고는 반드시 리스트 불릿(-)을 사용하여 공백으로 격리해 주세요.
• 함정 4: 에러 상황에서의 행동 지침 부재: 외부 서버 접속이 끊기거나, 파일이 오염되었을 때 AI가 방황하지 않도록 "작업이 차단되면 즉시 경고 메모를 작성하고 정지할 것" 같은 출구 전략을 심어주세요.

결론

마크다운으로 표현된 SKILL.md 문서와 스마트한 도구 명세는 자율 행동을 시작한 AI 에이전트를 고품질 업무 프로세스에 단단히 붙들어 매어 두는 최고의 형상 관리 장치입니다.

AI 에이전트를 내 업무 파이프라인에 안전하게 결합시키고 싶다면, 규칙이 잘 잡힌 스킬 가이드를 마크다운으로 지필하는 것부터 시작해 보세요.

참고 자료 및 추천 사이트

• Claude 도움말: Agent Skills의 설계와 활용
• Claude Code 레퍼런스: 에이전트 SDK 내부의 Skills 설계
• OpenAI API: Function Calling 함수 연결 기술
• OpenAI Agents SDK: 툴 설계 베스트 프랙티스