Hanpy's Blog

두 글자 이상 입력하세요.

AI · Agents

AGENTS.md vs Skills vs MCP — AI 에이전트에게 일을 맡기는 3가지 방법

AI 코딩 에이전트에게 프로젝트 규칙은 AGENTS.md로, 반복 작업 절차는 Agent Skills(SKILL.md)로, 외부 시스템 연결은 MCP로 알려 줍니다. 세 표준이 언제 컨텍스트에 들어가고 무엇을 할 수 있는지 비교하고, 직접 만든 예제 파일 3종으로 확인합니다.

Hanpy약 14분

기준일: 2026-11-14. 이 글의 명세·버전·도구 지원 범위는 이 날짜에 공식 문서에서 확인한 내용입니다. 세 표준 모두 빠르게 바뀌고 있으니, 오래된 글이라면 끝의 출처에서 최신 내용을 확인해 주세요.

AI 코딩 에이전트에게 일을 맡기다 보면 같은 설명을 여러 번 하게 됩니다. "이 프로젝트는 pnpm을 써", "글을 쓸 때는 frontmatter를 이렇게 채워", "사내 위키에서 이 내용을 찾아 봐" 같은 말입니다. 매번 채팅창에 붙여 넣는 대신 이 설명을 파일이나 서버로 만들어 두는 방법이 지금 세 가지 표준으로 정리되어 있습니다.

  • AGENTS.md: 저장소에 두는 에이전트용 README. 프로젝트 규칙과 명령
  • Agent Skills (SKILL.md): 필요할 때만 꺼내 읽는 작업 매뉴얼 폴더
  • MCP (Model Context Protocol): 에이전트가 외부 시스템의 도구·데이터를 쓰게 해 주는 통신 규약

이름이 비슷하게 들려서 "셋 중 무엇을 써야 하나"라는 질문을 많이 받는데, 셋은 경쟁 관계가 아니라 맡는 층이 다릅니다. 이 글에서는 셋을 한 표로 비교하고, 이 블로그 저장소를 예로 직접 만든 파일 3종을 실행해 보면서 차이를 확인합니다.

한눈에 비교하기

구분AGENTS.mdAgent Skills (SKILL.md)MCP
한 줄 정의에이전트용 README필요할 때 읽는 작업 매뉴얼외부 도구·데이터 연결 규약
형태마크다운 파일 1개 (필수 필드 없음)폴더 + SKILL.md(YAML frontmatter + 마크다운)서버 프로그램 (JSON-RPC 2.0)
컨텍스트에 들어가는 때세션 시작 때 항상시작 때는 이름·설명만, 쓸 때 본문, 필요할 때 부속 파일도구 목록은 tools/list로 받을 때, 결과는 호출할 때
할 수 있는 일규칙·명령을 알려 줌절차를 알려 주고 스크립트를 함께 제공에이전트 밖의 코드를 실행하고 결과를 돌려줌
잘 맞는 내용빌드·테스트 명령, 코드 규칙, 폴더 구조여러 단계짜리 반복 작업 (배포, 글 초안, 리뷰)DB 조회, 사내 API, SaaS 연동
관리AAIF(Linux Foundation)agentskills.io 명세modelcontextprotocol.io 명세
주의할 점길어지면 매 세션 토큰을 먹고 잘 안 지켜짐description이 모호하면 꺼내 쓰지 않음도구 = 임의 코드 실행, 권한·신뢰 관리 필요

판단 기준을 한 문장으로 줄이면 이렇습니다.

  • 항상 알아야 하는 짧은 사실 → AGENTS.md
  • 가끔 하는 여러 단계짜리 작업 → Skill
  • 에이전트가 스스로 할 수 없는 일(권한이 필요한 외부 시스템 접근) → MCP

컨텍스트(모델이 한 번에 보는 글)에 언제 무엇이 들어가는지를 시간 순서로 놓으면 차이가 더 분명합니다.

시점AGENTS.mdAgent SkillsMCP
① 세션 시작파일 전체모든 스킬의 이름·설명만 (스킬당 약 100토큰)호스트가 tools/list로 받아 둔 도구 이름·설명 (어떻게 넣을지는 호스트가 정함)
② 할 일이 정해졌을 때(이미 들어 있음)맞는 스킬의 SKILL.md 본문(변화 없음)
③ 실행할 때적힌 명령을 에이전트가 직접 실행scripts/·assets/ 파일을 읽거나 실행tools/call 결과가 들어옴

1. AGENTS.md: 에이전트용 README

AGENTS.md는 저장소에 두는 평범한 마크다운 파일입니다. 공식 사이트는 이를 "에이전트를 위한 README"라고 소개하고, 필수 필드가 있느냐는 질문에 없다, 그냥 표준 마크다운이고 원하는 제목을 써도 된다고 답합니다. 사람용 README에 넣기엔 지나치게 자세한 빌드·테스트 명령과 코드 규칙을 여기에 둡니다.

OpenAI가 2025년 12월 9일 Linux Foundation 아래에 Agentic AI Foundation(AAIF)을 Anthropic·Block과 함께 세우면서 AGENTS.md를 기증했고, 지금은 AAIF가 관리합니다. 공식 사이트에는 Codex, Jules, Cursor, Gemini CLI, GitHub Copilot coding agent, VS Code 등 지원 도구가 나열되어 있습니다.

규칙 두 가지만 알면 됩니다.

  • 가장 가까운 파일이 이깁니다. 모노레포라면 패키지마다 AGENTS.md를 둘 수 있고, 수정하는 파일에서 가장 가까운 것이 우선합니다. 채팅에서 사용자가 직접 한 말은 모든 파일보다 우선합니다.
  • 적어 둔 명령은 실행됩니다. 테스트 명령을 적어 두면 에이전트가 작업을 끝내기 전에 그 검사를 돌리고 실패를 고치려고 합니다.

이 블로그 저장소에 둔다면 이렇게 쓸 수 있습니다.

AGENTS.md (예제 1)
# hanpy-blog-app
 
Next.js 16 + Content Collections 블로그. 글은 `_content/{category}/{lng}/{sub}/{slug}.mdx`.
 
## 명령
- 설치: `pnpm install`
- 빌드(글 검사 포함): `pnpm build`
- 타입 검사: `pnpm typecheck` (빌드를 한 번 돌린 뒤)
- 사이드바·시리즈 비교: `pnpm check:sidebar`
 
## 규칙
- 글 본문에 `# `(h1)을 쓰지 않는다. 제목은 frontmatter `title` 하나
- 새 카테고리·서브카테고리·그룹은 `src/config/taxonomy.ts`에 먼저 등록한다
- 클라이언트 컴포넌트에서 `@/lib/content`를 import하지 않는다 (글 본문 전체가 번들에 들어감)
- 기존 글 주소(URL)는 바꾸지 않는다
 
## PR
- 브랜치: 글은 `post/{slug}`, 기능은 `feat/{이름}`
- PR 전에 `pnpm build && pnpm check:sidebar` 통과

Claude Code를 쓴다면: CLAUDE.md에서 불러오기

여기서 하나 주의할 점이 있습니다. 기준일에 확인한 Claude Code 공식 문서는 "Claude Code는 AGENTS.md가 아니라 CLAUDE.md를 읽는다"고 적고 있습니다. 그래서 CLAUDE.md 첫 줄에서 AGENTS.md를 불러오도록 안내합니다.

CLAUDE.md
@AGENTS.md
 
## Claude Code
- 글 작업은 new-blog-post 스킬을 따른다

이렇게 하면 공통 규칙은 AGENTS.md 하나로 관리하고, Claude Code에만 필요한 내용은 import 아래에 덧붙일 수 있습니다. Claude 전용 내용이 없다면 ln -s AGENTS.md CLAUDE.md처럼 심볼릭 링크도 되지만, Windows에서는 관리자 권한이나 개발자 모드가 필요해서 문서는 import를 권합니다.

길이는 짧게

AGENTS.md(와 CLAUDE.md)는 매 세션 처음부터 컨텍스트에 들어갑니다. Claude Code 문서는 CLAUDE.md를 파일당 200줄 아래로 유지하라고 권하고, 여러 단계짜리 절차나 일부 코드에만 해당하는 내용은 Skill이나 경로별 규칙으로 옮기라고 합니다. 다음 절의 Skills가 바로 그 자리입니다.

2. Agent Skills: 필요할 때 펼치는 작업 매뉴얼

Skill은 폴더 하나입니다. 안에 SKILL.md가 반드시 있어야 하고, 필요하면 scripts/(실행 코드), references/(참고 문서), assets/(템플릿·데이터)를 둡니다. 명세는 agentskills.io에서 관리합니다.

스킬 폴더 구조 (예제 2)
.agents/skills/new-blog-post/
├── SKILL.md              # 필수: frontmatter + 지시문
├── assets/
│   └── frontmatter.yaml  # 글 frontmatter 템플릿
└── scripts/
    └── check.sh          # 빌드·사이드바 검사

SKILL.md는 YAML frontmatter로 시작합니다. 필수 필드는 name과 description 두 개뿐입니다.

필드필수규칙 (명세 기준)
nameO1~64자, 소문자·숫자·하이픈만, 하이픈으로 시작·끝 금지, -- 금지, 폴더 이름과 같아야 함
descriptionO1~1024자, 무엇을 하는지 + 언제 쓰는지
license라이선스 이름이나 파일
compatibility1~500자, 필요한 환경(패키지, 네트워크 등)
metadata문자열 키·값
allowed-tools미리 허용할 도구 목록 (실험 기능, 도구마다 지원이 다름)

이 블로그에 새 글 초안을 만드는 스킬을 둔다면 이렇게 씁니다.

.agents/skills/new-blog-post/SKILL.md (예제 2)
---
name: new-blog-post
description: 한피 블로그(_content)에 새 글 초안을 만든다. 글 경로와 frontmatter(title, summary, publishedAt, group, order, series, tags)를 규칙대로 채우고 빌드 검사를 돌린다. 사용자가 "새 글", "글 초안", "포스트 추가"를 말할 때 사용한다.
metadata:
  author: hanpy
  version: "1.0"
---
 
# 새 블로그 글 초안 만들기
 
## 1. 위치 정하기
- 경로는 `_content/{category}/{lng}/{sub}/{slug}.mdx`
- `category`·`sub`·`group`은 `src/config/taxonomy.ts`에 등록된 값만 쓴다. 없으면 먼저 등록한다
- 시리즈 글이면 `src/config/series.ts`에 id가 있는지 확인한다
 
## 2. frontmatter 채우기
[템플릿](assets/frontmatter.yaml)을 복사해서 채운다.
- `publishedAt`은 오늘 날짜(YYYY-MM-DD)
- `order`는 같은 group 안에서 마지막 번호 + 1
 
## 3. 본문 규칙
- 본문에 `# ` (h1)을 쓰지 않는다. 제목은 frontmatter `title` 하나
- 끝에 `## 정리`와 `## 참고 자료`를 둔다
 
## 4. 확인
`scripts/check.sh`를 실행하고, 실패하면 오류 문장을 읽고 고친 뒤 다시 실행한다.

핵심은 점진적 공개(progressive disclosure)

Skill이 AGENTS.md와 가장 다른 점은 읽히는 시점입니다. 명세는 세 단계로 나눕니다.

  1. 메타데이터(약 100토큰): 시작할 때 모든 스킬의 name·description만 읽습니다.
  2. 지시문(5,000토큰 미만 권장): 작업이 description과 맞으면 그때 SKILL.md 본문 전체를 읽습니다.
  3. 부속 파일(필요할 때): scripts/·references/·assets/ 파일은 본문이 가리킬 때만 읽습니다.

그래서 스킬을 수십 개 깔아 두어도 평소에는 목록 몇 줄만 차지합니다. 반대로 말하면 description이 스킬을 꺼낼지 말지를 정합니다. "글 관련 도구" 같은 모호한 설명 대신, 무엇을 하는지와 어떤 말을 들으면 써야 하는지를 적어야 합니다. SKILL.md는 500줄 아래로 두고 긴 참고 자료는 references/로 빼라는 것도 같은 이유입니다.

검사기로 확인하기

명세 저장소의 참조 라이브러리(skills-ref, PyPI 패키지 이름 skills-ref, 명령 이름 agentskills)로 형식을 검사할 수 있습니다. 위 예제를 직접 검사한 결과입니다.

스킬 형식 검사 (직접 실행)
$ pip install skills-ref
$ agentskills validate ./new-blog-post
Valid skill: new-blog-post
 
# 규칙을 어긴 이름은 이유와 함께 거절됩니다
$ agentskills validate ./bad/New_Post
Validation failed for bad/New_Post:
  - Skill name 'New_Post' must be lowercase
  - Skill name 'New_Post' contains invalid characters. Only letters, digits, and hyphens are allowed.

to-prompt 명령은 에이전트가 시작할 때 실제로 보는 1단계 정보를 보여 줍니다. 본문은 없고 이름·설명·위치만 있다는 점을 확인할 수 있습니다.

agentskills to-prompt ./new-blog-post (직접 실행)
<available_skills>
<skill>
<name>
new-blog-post
</name>
<description>
한피 블로그(_content)에 새 글 초안을 만든다. 글 경로와 frontmatter(title, summary, publishedAt, group, order, series, tags)를 규칙대로 채우고 빌드 검사를 돌린다. 사용자가 &quot;새 글&quot;, &quot;글 초안&quot;, &quot;포스트 추가&quot;를 말할 때 사용한다.
</description>
<location>
/tmp/skilldemo/new-blog-post/SKILL.md
</location>
</skill>
</available_skills>

.agents/skills/와 .claude/skills/ 중 어디를 읽는지는 도구마다 다릅니다. 쓰는 도구의 문서에서 스킬 폴더 위치를 확인하세요.

광고

3. MCP: 에이전트 밖의 시스템과 연결하기

AGENTS.md와 Skill은 결국 텍스트입니다. 에이전트가 이미 가진 능력(파일 읽기, 명령 실행)을 어떻게 쓸지 알려 줄 뿐입니다. 사내 DB를 조회하거나 SaaS API를 호출하는 것처럼 에이전트 밖에서 코드를 실행해야 하는 일은 MCP가 맡습니다.

MCP는 JSON-RPC 2.0 메시지로 세 역할을 연결합니다.

  • 호스트(Host): 연결을 시작하는 LLM 애플리케이션 (Claude Code, IDE 등)
  • 클라이언트(Client): 호스트 안에서 서버 하나와 대화하는 연결 부분
  • 서버(Server): 기능을 제공하는 쪽

서버가 제공하는 기능은 세 가지입니다.

기능무엇예
Tools모델이 실행하는 함수search_posts, create_issue
Resources사용자나 모델이 쓰는 데이터설정 파일, 문서
Prompts사용자가 고르는 메시지 템플릿"코드 리뷰" 템플릿

2026-07-28 명세: 세션 없는 요청

기준일 현재 최신 명세는 2026-07-28 판입니다. 이 판에서 프로토콜 수준의 세션과 Mcp-Session-Id 헤더, initialize 핸드셰이크가 빠졌습니다. 이제 요청마다 프로토콜 버전과 클라이언트 정보를 _meta에 직접 담아서 보내고, 서버는 요청 하나만 보고 답할 수 있습니다. 백엔드 개발자에게 익숙한 말로 하면, 스티키 세션 없이 로드 밸런서 뒤에서 늘릴 수 있는 무상태 HTTP 서비스에 가까워졌습니다. 함께 Roots·Sampling·Logging 기능은 지원 중단(deprecated) 상태가 되었습니다.

TypeScript SDK도 이 명세에 맞춘 v2가 안정판이고, 하나였던 @modelcontextprotocol/sdk 패키지가 @modelcontextprotocol/server와 @modelcontextprotocol/client로 나뉘었습니다. 기준일에 npm에서 확인한 최신 버전은 둘 다 2.4.0입니다.

예제 3: 블로그 글을 찾아 주는 MCP 서버

이 블로그의 _content 폴더에서 제목으로 공개 글을 찾아 주는 서버를 만들어 보겠습니다. 도구 하나(search_posts)를 stdio로 제공합니다.

설치
$ npm i @modelcontextprotocol/server@2.4.0 @modelcontextprotocol/client@2.4.0 zod
server.mjs (예제 3)
// blog-posts MCP 서버: 블로그 글 폴더(_content)에서 제목으로 글을 찾아 준다
import { readdir, readFile } from 'node:fs/promises'
import { join, relative } from 'node:path'
import { McpServer } from '@modelcontextprotocol/server'
import { serveStdio } from '@modelcontextprotocol/server/stdio'
import { z } from 'zod'
 
const ROOT = process.env.BLOG_CONTENT_DIR ?? './_content'
 
async function* walk(dir) {
  for (const e of await readdir(dir, { withFileTypes: true })) {
    const p = join(dir, e.name)
    if (e.isDirectory()) yield* walk(p)
    else if (e.name.endsWith('.mdx')) yield p
  }
}
 
async function findPosts(keyword) {
  const hits = []
  for await (const file of walk(ROOT)) {
    const text = await readFile(file, 'utf8')
    if (/^draft:\s*true/m.test(text)) continue // 초안은 건너뜀
    const title = text.match(/^title:\s*'?(.+?)'?\s*$/m)?.[1] ?? ''
    if (title.toLowerCase().includes(keyword.toLowerCase())) {
      hits.push({ title, url: '/' + relative(ROOT, file).replace(/\.mdx$/, '') })
    }
  }
  return hits
}
 
serveStdio(() => {
  const server = new McpServer({ name: 'blog-posts', version: '1.0.0' }, { capabilities: { tools: {} } })
  server.registerTool(
    'search_posts',
    {
      title: '블로그 글 검색',
      description: '공개된 블로그 글을 제목 키워드로 찾아 제목과 주소를 돌려준다',
      inputSchema: z.object({ keyword: z.string().min(1) }),
      outputSchema: z.object({ posts: z.array(z.object({ title: z.string(), url: z.string() })) }),
      annotations: { readOnlyHint: true },
    },
    async ({ keyword }) => {
      const posts = await findPosts(keyword)
      return {
        content: [{ type: 'text', text: posts.map((p) => `${p.title} → ${p.url}`).join('\n') || '결과 없음' }],
        structuredContent: { posts },
      }
    },
  )
  return server
})

확인용 클라이언트로 서버를 띄워 도구 목록을 받고 JWT를 검색해 봤습니다.

client.mjs
import { Client } from '@modelcontextprotocol/client'
import { StdioClientTransport } from '@modelcontextprotocol/client/stdio'
 
const transport = new StdioClientTransport({
  command: 'node',
  args: ['server.mjs'],
  env: { ...process.env, BLOG_CONTENT_DIR: process.argv[2] ?? './_content' },
})
const client = new Client({ name: 'demo-client', version: '1.0.0' })
await client.connect(transport)
 
const { tools } = await client.listTools()
console.log('tools:', tools.map((t) => t.name))
 
const result = await client.callTool({ name: 'search_posts', arguments: { keyword: 'JWT' } })
console.log(result.content[0].text)
await client.close()
실행 결과 (직접 실행)
$ node client.mjs ~/hanpy-blog-app/_content
tools: [ 'search_posts' ]
NestJS에서 JWT를 이용한 인증(Authentication) 구현하기 → /backend/ko/nestjs/nestjs-security-01-authentication
JWT 기반 로그인 구현 흐름: Access Token, Refresh Token → /backend/ko/security/auth-05-jwt

핸드셰이크 없이 바로 호출해 보기

새 명세가 정말 무상태인지, SDK 없이 JSON-RPC 한 줄을 서버의 표준 입력에 직접 넣어 확인해 봤습니다. initialize 없이 첫 메시지가 바로 tools/call이고, 버전 정보는 _meta에 들어 있습니다.

raw JSON-RPC로 tools/call (직접 실행)
$ (echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_posts","arguments":{"keyword":"OIDC"},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"raw","version":"0"},"io.modelcontextprotocol/clientCapabilities":{}}}}'; sleep 1) \
  | BLOG_CONTENT_DIR=~/hanpy-blog-app/_content node server.mjs
응답 (보기 좋게 정리)
{
  "result": {
    "content": [
      {
        "type": "text",
        "text": "OpenID Connect(OIDC) 쉽게 이해하기: OAuth 2.0 위에서 로그인 기능을 만든 이유 → /backend/ko/security/auth-08-oidc"
      }
    ],
    "structuredContent": {
      "posts": [
        {
          "title": "OpenID Connect(OIDC) 쉽게 이해하기: OAuth 2.0 위에서 로그인 기능을 만든 이유",
          "url": "/backend/ko/security/auth-08-oidc"
        }
      ]
    },
    "resultType": "complete",
    "_meta": { "io.modelcontextprotocol/serverInfo": { "name": "blog-posts", "version": "1.0.0" } }
  },
  "jsonrpc": "2.0",
  "id": 1
}

응답에 들어 있는 resultType: "complete"도 2026-07-28 판에서 모든 결과에 필수가 된 필드입니다. 실습하다 한 번 막힌 곳도 있었습니다. 처음에는 sleep 1 없이 echo ... | node server.mjs로 보냈더니 아무 응답이 없었습니다. stdio 서버는 표준 입력이 닫히면 처리 중이던 요청을 취소하고 종료하기 때문입니다(SDK 문서에 그렇게 적혀 있습니다). 직접 시험할 때는 응답이 올 때까지 입력을 열어 두어야 합니다.

MCP의 보안: 도구는 임의 코드 실행이다

MCP 명세는 보안 원칙에서 도구는 임의 코드 실행과 같으니 조심해서 다루라고 하고, 신뢰할 수 있는 서버가 아니면 도구 설명(annotations 포함)도 믿지 말라고 합니다. 호스트는 도구를 호출하기 전에 사용자 동의를 받아야 합니다. 위 예제에 readOnlyHint: true를 달았지만, 이것은 서버가 스스로 주장하는 힌트일 뿐 보장이 아닙니다. 설치하는 MCP 서버는 그 서버가 가진 권한(파일, 토큰, 네트워크)을 모두 쓸 수 있다고 생각해야 합니다. MCP 보안은 다음 글에서 따로 다룹니다.

인증이 필요한 원격 MCP 서버는 OAuth 흐름을 씁니다. OAuth가 낯설다면 아래 글을 먼저 보세요.

OAuth 2.0 흐름과 Access Token 발급 과정 다시 보기 (클릭)

셋을 함께 쓰는 모습

세 가지는 한 저장소에서 겹치지 않게 함께 쓸 수 있습니다. 이 블로그로 예를 들면 이렇습니다.

하고 싶은 일어디에이유
"pnpm을 쓴다, h1 금지"AGENTS.md모든 작업에 해당하는 짧은 사실
"새 글 초안을 규칙대로 만든다"Skill (new-blog-post)여러 단계 + 템플릿·스크립트, 가끔만 필요
"기존 글 중 관련 글을 찾아 링크한다"MCP (search_posts)에이전트 밖의 데이터를 조회 (지금은 로컬 폴더지만 DB·검색 API로 바꿔도 같은 도구)

실제로 MCP 명세도 이 경계를 잇는 쪽으로 가고 있습니다. 2026-07-28 명세의 확장 목록에는 Skills over MCP(MCP로 스킬을 찾아 쓰는 확장)가 올라 있고, TypeScript SDK 2.4.0에도 스킬 관련 하위 경로(@modelcontextprotocol/server/ext/skills)가 들어 있습니다. 서버가 도구와 함께 "이 도구를 쓰는 절차"까지 스킬로 내려 주는 방향입니다.

정리

  • AGENTS.md는 항상 읽히는 에이전트용 README입니다. 빌드·테스트 명령과 코드 규칙처럼 짧고 늘 필요한 사실을 둡니다. Claude Code는 CLAUDE.md에서 @AGENTS.md로 불러옵니다.
  • Agent Skills는 필요할 때만 펼치는 작업 매뉴얼 폴더입니다. 시작할 때는 이름·설명(약 100토큰)만 읽히므로 description을 구체적으로 써야 합니다.
  • MCP는 에이전트 밖의 시스템을 도구로 연결하는 규약입니다. 2026-07-28 명세부터 세션 없이 요청마다 독립적으로 처리되고, 도구는 임의 코드 실행이므로 권한과 신뢰를 관리해야 합니다.
  • 고르는 기준: 항상 → AGENTS.md, 가끔 하는 절차 → Skill, 에이전트가 못 하는 일 → MCP.

참고 자료

이 글은 AI 도구로 초안을 만들고 저자가 검토·보완했습니다.

Hanpy백엔드·인프라 엔지니어 · AI 트렌드 정리 중
About 보기