스킬과 에이전트 SDK(Skills and Agent SDKs) — Anthropic Skills, AGENTS.md, OpenAI Apps SDK

MCP는 "어떤 도구가 존재하는가"를 말합니다. 스킬(Skills)은 "어떤 작업을 어떻게 수행하는가"를 말합니다. 2026년의 스택은 이 두 가지를 모두 계층으로 포개어 놓습니다. Anthropic의 에이전트 스킬(Agent Skills; 오픈 표준, 2025년 12월 공개)은 점진적 공개(progressive disclosure) 방식을 갖춘 SKILL.md로 배포됩니다. OpenAI의 Apps SDK는 MCP에 위젯 메타데이터(widget metadata)를 더한 형태입니다. AGENTS.md(현재 60,000개 이상의 저장소에서 사용 중)는 저장소 루트(repo root)에 놓이는 프로젝트 수준의 에이전트 컨텍스트(project-level agent context)입니다. 이 강의는 각 계층이 무엇을 담당하는지 분명히 짚어 보고, 여러 에이전트(agent)를 오가며 그대로 사용할 수 있는 최소 형태의 SKILL.md + AGENTS.md 번들(bundle)을 직접 만들어 봅니다.

유형: Learn
언어: Python (표준 라이브러리, SKILL.md 파서(parser)와 로더(loader))
선수 학습: Phase 13 · 07 (MCP 서버)
소요 시간: 약 45분

학습 목표

• 세 가지 계층을 구분합니다. AGENTS.md(프로젝트 컨텍스트), SKILL.md(재사용 가능한 노하우), MCP(도구)입니다.
• YAML 프런트매터(YAML frontmatter)와 점진적 공개를 갖춘 SKILL.md를 작성합니다.
• 스킬을 파일시스템 방식으로 에이전트 런타임(agent runtime)에 적재(load)합니다.
• 하나의 패키지가 Claude Code, Cursor, Codex에서 동작하도록 스킬과 MCP 서버, AGENTS.md를 조합합니다.

문제

한 엔지니어가 릴리스 노트 작성(release-notes-writing) 워크플로(workflow)를 여러 단계로 이어지는 프롬프트(prompt)로 정리했다고 가정합시다. "최근에 머지(merge)된 PR을 읽고, 영역별로 묶고, 각각을 요약한 뒤, 팀 스타일에 맞춰 체인지로그(changelog) 항목을 작성하고, Slack 초안(draft)에 올린다." 엔지니어는 이 워크플로를 팀의 Notion 문서에 정리해 두었습니다.

이제 같은 워크플로를 Claude Code, Cursor, Codex CLI에서 모두 사용하고 싶어졌습니다. 그런데 에이전트마다 지시(instruction)를 적재하는 방식이 다릅니다. Claude Code는 슬래시 명령(slash-command), Cursor는 룰(rules), Codex는 .codex.md를 사용합니다. 결국 엔지니어는 같은 워크플로를 세 번 복사해 두고, 세 벌의 사본을 따로따로 유지보수하게 됩니다.

AGENTS.md와 SKILL.md는 이 문제를 함께 해결합니다.

• AGENTS.md: 저장소 루트에 둡니다. 호환되는 모든 에이전트가 세션 시작 시점에 이 파일을 읽습니다. "이 프로젝트는 어떻게 동작하는가? 규칙(convention)은 무엇인가? 어떤 명령으로 테스트를 실행하는가?"를 알려 줍니다.
• SKILL.md: 어디로든 옮길 수 있는 번들입니다. YAML 프런트매터(name, description) + 마크다운 본문(markdown body) + 선택적 리소스로 구성됩니다. 스킬을 지원하는 에이전트는 필요할 때 이름으로 적재합니다.
• MCP(Phase 13 · 06-14): 스킬이 호출해야 하는 도구를 담당합니다.

세 개의 계층, 그러나 옮겨 다닐 수 있는 하나의 산출물(portable artifact)입니다.

개념

AGENTS.md (agents.md)

2025년 말에 등장해 2026년 4월까지 60,000개가 넘는 저장소에 도입되었습니다. 저장소 루트에 단 하나의 파일로 둡니다. 형식은 다음과 같습니다.

# Project: my-service

## Conventions
- TypeScript with strict mode.
- Use Pydantic for models on the Python side.
- Tests run with `pnpm test`.

## Build and run
- `pnpm dev` for local dev server.
- `pnpm build` for production bundle.

에이전트는 세션 시작 시점에 이 파일을 읽고, 해당 프로젝트에 맞도록 자신의 동작을 보정합니다. 2026년의 코딩 에이전트는 사실상 모두 AGENTS.md를 지원합니다. Claude Code, Cursor, Codex, Copilot Workspace, opencode, Windsurf, Zed가 여기에 포함됩니다.

SKILL.md 형식

Anthropic의 에이전트 스킬(2025년 12월 오픈 표준으로 공개)의 형식은 다음과 같습니다.

---
name: release-notes-writer
description: Write a changelog entry for the latest merged PRs following this project's style.
---

# Release notes writer

When invoked, run these steps:

1. List PRs merged since the last tag. Use `gh pr list --base main --state merged`.
2. Group by label: feature, fix, chore, docs.
3. For each PR in each group, write one line: `- <title> (#<num>)`.
4. Draft the release notes and stage them in CHANGELOG.md.

If the user says "ship", run `git tag vX.Y.Z` and `gh release create`.

## Notes

- Never include commits without a PR.
- Skip "chore" entries from the public changelog.

프런트매터는 스킬의 정체(identity)를 선언합니다. 본문은 스킬이 적재될 때 모델(model)에 함께 제시되는 프롬프트입니다.

점진적 공개(Progressive disclosure)

스킬은 에이전트가 정말 필요할 때에만 가져오는 하위 리소스(sub-resource)를 참조할 수 있습니다. 예를 들면 다음과 같습니다.

skills/
  release-notes-writer/
    SKILL.md
    style-guide.md
    template.md
    scripts/
      generate.sh

SKILL.md는 "스타일 규칙은 style-guide.md를 참고하라"고 안내해 둡니다. 에이전트는 스킬이 실제로 실행되는 동안에만 style-guide.md를 읽어 옵니다. 이렇게 하면 모델이 항상 필요로 하지는 않는 세부 정보로 프롬프트를 부풀리지 않을 수 있습니다.

파일시스템 기반 발견(Filesystem discovery)

에이전트 런타임은 미리 정해진 디렉터리에서 SKILL.md 파일을 탐색합니다.

• ~/.anthropic/skills/*/SKILL.md
• 프로젝트의 ./skills/*/SKILL.md
• ~/.claude/skills/*/SKILL.md

적재는 폴더 이름과 프런트매터의 name 값을 기준으로 이루어집니다. Claude Code, Anthropic의 Claude Agent SDK, 그리고 여러 에이전트를 아우르는 SkillKit(cross-agent) 모두 이 패턴을 따릅니다.

Anthropic Claude Agent SDK

@anthropic-ai/claude-agent-sdk(TypeScript)와 claude-agent-sdk(Python)는 세션 시작 시점에 스킬을 적재하고, 런타임 내부에서 호출 가능한 "에이전트"로 노출합니다. 에이전트 루프(agent loop)는 사용자가 특정 스킬을 호출하면 해당 스킬로 작업을 디스패치(dispatch)합니다.

OpenAI Apps SDK

2025년 10월에 출시되었고 MCP 위에 그대로 올려진 형태입니다. OpenAI가 이전에 제공하던 커넥터(Connectors)와 커스텀 GPT 액션(Custom GPT Actions)을 하나의 개발자 인터페이스(developer surface)로 통합했습니다. Apps SDK 앱(app)은 다음의 조합입니다.

• MCP 서버(도구, 리소스, 프롬프트)
• ChatGPT UI를 위한 위젯 메타데이터
• 상호작용 화면(interactive surface)을 위한 선택적 MCP Apps ui:// 리소스

같은 프로토콜(protocol) 위에서 더 풍부한 사용자 경험(UX)을 제공합니다.

SkillKit을 통한 교차 에이전트 이식성(Cross-agent portability)

SkillKit과 유사한 교차 에이전트 배포 계층(cross-agent distribution layer)은 단 하나의 SKILL.md를 Claude Code, Cursor, Codex, Gemini CLI, OpenCode 등 32개가 넘는 AI 에이전트의 고유 형식(native format)으로 변환해 줍니다. 단일한 진실의 출처(source of truth) 하나에, 그것을 소비하는 여러 클라이언트(consumer)가 붙는 구조입니다.

세 계층 스택

세 계층은 함께 맞물려 동작합니다. 에이전트는 세션 시작 시점에 AGENTS.md를 읽고, 사용자가 스킬을 호출하면 해당 스킬의 지시문이 MCP 도구 호출(tool call)을 포함하며, 에이전트는 MCP 클라이언트(client)를 통해 그 호출을 디스패치합니다.

사용해 보기

code/main.py는 표준 라이브러리(stdlib)만으로 만든 SKILL.md 파서와 로더를 제공합니다. ./skills/ 아래의 스킬을 탐색하고, YAML 프런트매터와 마크다운 본문을 파싱(parsing)한 뒤, 스킬 이름을 키(key)로 하는 딕셔너리(dict)를 만들어 둡니다. 그런 다음 release-notes-writer를 이름으로 호출하는 에이전트 루프를 시뮬레이션(simulation)합니다.

살펴볼 지점은 다음과 같습니다.

• 최소한의 표준 라이브러리 파서로 YAML 프런트매터를 파싱합니다. pyyaml 의존성이 필요하지 않습니다.
• 스킬 본문은 그대로 저장됩니다. 에이전트는 호출 시 이를 시스템 프롬프트(system prompt) 앞에 붙입니다.
• read_subresource 함수를 통해 참조 파일을 필요한 시점에 가져오며 점진적 공개를 시연합니다.

산출물 만들기

이 강의는 outputs/skill-agent-bundle.md를 만들어 냅니다. 어떤 워크플로가 주어졌을 때, 이 스킬은 여러 에이전트 사이를 그대로 옮겨 다닐 수 있는 SKILL.md + AGENTS.md + MCP 서버 청사진(blueprint) 번들을 만들어 줍니다.

연습문제

1. (쉬움) code/main.py를 실행합니다. skills/ 아래에 두 번째 스킬을 추가하고 로더가 이를 잡아내는지 확인합니다.

2. (중간) 이 강의 저장소(course repo)를 위한 AGENTS.md를 작성합니다. 테스트 명령(testing command), 스타일 규약(style convention), Phase 13의 멘탈 모델(mental model)을 포함합니다.

3. (중간) 팀 내부 문서에 있는 여러 단계의 워크플로를 SKILL.md로 옮깁니다. Claude Code에서 정상적으로 적재되는지 확인합니다.

4. (어려움) 같은 스킬을 Cursor와 Codex의 고유 룰 형식으로 손수 번역합니다. 형식 사이의 차이(diff)를 세어 봅니다. 바로 이것이 SkillKit이 자동화해 주는 변환 표면(translation surface)입니다.

5. (어려움) Anthropic의 에이전트 스킬 블로그 글을 읽습니다. 이 강의의 로더가 다루지 않는 Claude Agent SDK 기능을 하나 찾아냅니다. 힌트: 에이전트의 하위 호출(agent sub-invocation)입니다.

핵심 용어

더 읽을거리

• Anthropic — Agent Skills announcement — 2025년 12월 공개 발표
• Anthropic — Agent Skills docs — SKILL.md 형식 참고 문서
• OpenAI — Apps SDK — ChatGPT를 위한 MCP 기반 개발자 플랫폼
• agents.md — AGENTS.md 형식과 도입 현황 목록
• Anthropic — anthropics/skills GitHub — 공식 스킬 예시