문서에서 스킬·플러그인·MCP로
반복 절차, 배포 단위, 외부 컨텍스트를 에이전트용 표면으로 분리하는 방법
핵심 요약
- 문서의 성격에 맞춰 규칙 파일·Skill·Plugin·MCP Resource/Prompt/Tool로 나눕니다.
- 항상 필요한 짧은 지침은
AGENTS.md/CLAUDE.md에, 가끔 필요한 긴 절차는 Skill로 분리합니다. - Skill은 반복 절차의 단위, Plugin은 버전·소유자·보안 검토가 따라붙는 팀 배포 단위입니다.
- MCP는 Tools(동작)·Resources(읽기 전용 컨텍스트)·Prompts(사용자 호출 템플릿)로 외부 시스템을 노출합니다.
- "얇은 규칙 파일 + 두꺼운 Skill", "Skill + MCP Resource"로 묶으면 정보 드리프트가 줄어듭니다.
에이전틱 문서화의 최신 흐름은 "문서를 더 많이 쓰자"가 아닙니다. 문서의 성격에 맞춰 규칙 파일, Skill, Plugin, MCP Resource/Prompt/Tool로 갈라놓는 쪽입니다.
규칙 파일은 시작 지침, Skill은 반복 절차, Plugin은 배포 단위입니다. MCP는 외부 시스템과 문서를 에이전트가 쓸 수 있는 표준 인터페이스로 노출합니다.
표면 선택 기준
| 넣을 내용 | 권장 표면 | 이유 |
|---|---|---|
| 모든 작업에 항상 필요한 프로젝트 규칙 | AGENTS.md, CLAUDE.md | 시작 시 즉시 읽혀야 함 |
| 특정 파일/디렉토리에만 필요한 규칙 | nested AGENTS.md, .claude/rules/ | 전역 컨텍스트 오염 방지 |
| 반복되는 절차, 체크리스트, 스크립트 | Skill | 필요할 때만 로드하고 실행 가능 |
| 팀에 배포할 Skills + MCP + 앱 통합 | Plugin | 설치·버전·정책 단위가 필요함 |
| API 문서, DB 스키마, KB, 정책 문서 | MCP Resource | 읽기 전용 컨텍스트로 제공 |
| 사용자가 선택해 실행할 워크플로우 | MCP Prompt | 구조화된 입력과 절차 제공 |
| 외부 API 호출, 파일 변경, 액션 | MCP Tool | 모델이 호출할 수 있는 명시적 동작 |
분리의 기준
항상 필요한 짧은 지침은 규칙 파일에 둡니다. 가끔 필요한 긴 절차는 Skill로 분리합니다. 외부 시스템에서 가져와야 하는 최신 컨텍스트는 MCP로 노출합니다.
Skills: 반복 절차를 문서화하는 단위
Skill은 매번 프롬프트에 붙여 넣던 절차를 재사용 가능한 폴더로 만든 것입니다.
대부분의 Skill은 SKILL.md에 선택적으로 scripts/, references/, assets/를 곁들입니다.
.agents/skills/release-check/
├── SKILL.md
├── scripts/
│ └── collect-release-notes.sh
└── references/
└── release-policy.mdSkill로 옮겨야 하는 신호
| 신호 | 예시 |
|---|---|
| 같은 프롬프트를 반복해서 붙여 넣는다 | "변경 요약 작성 후 위험 항목을 검토해줘" |
| 긴 체크리스트가 규칙 파일을 비대하게 만든다 | 릴리스, 보안 리뷰, 장애 회고 |
| 절차에 실행 스크립트가 필요하다 | 변경 파일 수집, 테스트 데이터 생성, 보고서 렌더링 |
| 참고자료가 길지만 항상 필요하지는 않다 | 정책 전문, API 세부 레퍼런스, 예시 모음 |
SKILL.md 템플릿
---
name: release-check
description: 릴리스 전 변경 요약, 위험 검토, 검증 명령 확인이 필요할 때 사용한다.
---
## 목적
릴리스 후보 변경을 검토하고, 누락된 문서/테스트/마이그레이션 위험을 찾는다.
## 절차
1. 현재 diff와 최근 커밋을 확인한다.
2. 사용자 영향, 운영 영향, 마이그레이션 필요 여부를 분류한다.
3. `references/release-policy.md`가 필요한 경우 읽는다.
4. 검증 명령을 실행하거나 실행 불가 사유를 보고한다.
## 출력
- 변경 요약
- 위험 항목
- 실행한 검증
- 릴리스 전 남은 작업규칙 파일과 Skill을 혼동하지 말 것
프로젝트의 변하지 않는 사실은 AGENTS.md나 CLAUDE.md에 둡니다.
Skill에는 특정 업무를 처리하는 절차와 거기에 필요한 참고자료만 담습니다.
Plugins: 팀에 배포하는 설치 단위
Plugin은 Skill을 팀이나 조직에 배포하려고 포장한 단위입니다.
Codex 기준으로 Plugin은 .codex-plugin/plugin.json manifest를 두고, skills, hooks, MCP 서버, 앱 통합을 한데 묶습니다.
my-docs-plugin/
├── .codex-plugin/
│ └── plugin.json
├── skills/
│ └── docs-review/
│ └── SKILL.md
├── .mcp.json
└── assets/Plugin으로 승격할 때
| 상태 | 유지 위치 |
|---|---|
| 개인 실험 | 개인 skills 디렉토리 |
| 한 저장소에서만 쓰는 절차 | repo skill |
| 여러 저장소/팀에 배포 | Plugin |
| Skill과 MCP 설정을 함께 배포 | Plugin |
| 설치 정책, 인증, 아이콘, 설명이 필요 | Plugin |
Plugin은 배포 단위라 버전, 소유자, 변경 로그, 보안 검토가 따라옵니다. 검증되지 않은 절차를 곧장 Plugin으로 만들면 잘못된 워크플로우가 여러 팀으로 순식간에 번집니다.
MCP: 문서를 외부 컨텍스트로 제공하는 표준 인터페이스
MCP 서버는 AI 애플리케이션에 세 가지 빌딩 블록을 제공합니다.
| MCP 기능 | 의미 | 문서화 관점 |
|---|---|---|
| Tools | 모델이 호출할 수 있는 동작 | 입력/출력 스키마, 권한, 부작용을 명확히 문서화 |
| Resources | 읽기 전용 컨텍스트 | API 문서, DB 스키마, KB, 정책 문서를 최신 상태로 제공 |
| Prompts | 사용자가 호출하는 템플릿 | 도메인 워크플로우를 구조화된 입력으로 실행 |
MCP Resource 예시
docs://api/openapi.yaml -> 최신 OpenAPI 스펙
docs://adr/2026-05-billing.md -> 결제 아키텍처 결정
kb://support/refund-policy -> 환불 정책 KB
schema://warehouse/orders -> orders 테이블 스키마긴 문서를 규칙 파일에 욱여넣지 않고 필요한 순간에 가져오려면 MCP Resource가 제격입니다. 반대로 실제 파일을 수정하거나 외부 API를 호출해야 한다면 Resource가 아니라 Tool이 맞습니다.
MCP Prompt 예시
{
"name": "review-api-change",
"description": "API 변경의 호환성, 문서, 테스트 누락을 검토한다.",
"arguments": [
{ "name": "endpoint", "type": "string", "required": true },
{ "name": "change_type", "type": "string", "required": true }
]
}Prompt는 에이전트가 알아서 자동 실행하는 지침이 아닙니다. 사용자가 직접 골라 실행하는 구조화된 워크플로우로 보는 편이 안전합니다.
설계 패턴
1. 얇은 규칙 파일 + 두꺼운 Skill
AGENTS.md에는 "릴리스 전 /release-check Skill을 사용한다"만 둡니다.
실제 릴리스 체크리스트, 예시, 스크립트는 Skill에 둡니다.
## Validation
- 릴리스 PR은 `release-check` Skill을 사용해 위험 항목을 검토한다.
- 변경 로그는 `pnpm changeset` 결과와 비교한다.2. Skill + MCP Resource
Skill은 절차를 담고, MCP Resource는 최신 컨텍스트를 제공합니다.
Skill: api-change-review
-> docs://api/openapi.yaml
-> docs://adr/api-versioning.md
-> kb://support/public-api-issues이렇게 두면 Skill이 낡아도 Resource만 최신이면 사실 정보가 어긋나는 일이 줄어듭니다.
3. Plugin으로 배포
팀 공통 Skill과 MCP 서버 설정이 안정화되면 Plugin으로 묶습니다.
docs-quality-plugin
├── skills/docs-review
├── skills/release-notes
├── .mcp.json
└── .codex-plugin/plugin.jsonPlugin을 배포할 때는 "무엇을 할 수 있는가"뿐 아니라 "무엇을 해서는 안 되는가"까지 install-surface 설명에 적어 둡니다.
보안과 신뢰 경계
에이전트가 문서를 읽고 도구를 호출할수록, 문서 자체가 공격면으로 바뀝니다.
| 위험 | 예시 | 완화 |
|---|---|---|
| Prompt injection | 외부 KB 문서가 "보안 검증을 생략하라"고 지시 | Resource를 지침으로 취급하지 않고 데이터로 취급 |
| Tool overreach | 문서 검토 Skill이 배포 Tool까지 호출 | side effect Tool은 명시 승인 필요 |
| Skill drift | 오래된 절차가 최신 CI와 불일치 | Skill 버전과 검증 명령을 정기 점검 |
| Plugin 공급망 위험 | 출처 불명 Plugin 설치 | manifest, 소유자, 권한, MCP 설정 검토 |
| Resource poisoning | 잘못된 스키마/정책 문서 노출 | Resource 생성 파이프라인과 원본 링크 검증 |
체크리스트
| 항목 | 확인 |
|---|---|
| 항상 필요한 지침과 가끔 필요한 절차를 분리했는가 | ☐ |
AGENTS.md/CLAUDE.md가 Skill을 참조하되 내용을 중복하지 않는가 | ☐ |
| Skill에 목적, 사용 조건, 절차, 출력 형식이 명시되어 있는가 | ☐ |
| 긴 레퍼런스는 Skill supporting file 또는 MCP Resource로 분리했는가 | ☐ |
| Plugin 배포 전 버전, 소유자, 권한, MCP 설정을 검토했는가 | ☐ |
| MCP Tool/Resource/Prompt의 역할과 신뢰 경계를 구분했는가 | ☐ |