AI Agent 개발이 점점 더 인기를 얻으면서 프로젝트 루트 디렉토리에 .agents, .claude, .cursor와 같은 다양한 설정 폴더가 등장하기 시작했습니다. 그중 .agents와 .claude는 모두 Skills를 배치할 수 있지만, 그들의 포지셔닝, 설계 철학, 적용 범위는 완전히 다릅니다. 잘못된 위치에 Skills를 배치하면 사소하게는 Skills가 작동하지 않거나, 심각하게는 팀 협업 시 설정 충돌을 일으킬 수 있습니다. 본 글에서는 밑바탕 설계부터 두 폴더의 핵심 차이점과 모범 사례를 명확히 설명해 드리겠습니다.
핵심 가치: 이 글을 읽고 나면 Skills를 .agents에 배치해야 할지, .claude에 배치해야 할지, 그리고 여러 도구를 사용하는 팀에서 Agent 설정을 어떻게 효율적으로 관리해야 할지 명확하게 알게 될 것입니다.
.agents 와 .claude 폴더 핵심 요점
가장 핵심적인 질문부터 답해 드릴게요. 이 두 폴더는 경쟁 관계가 아니라, 서로 다른 계층의 설정 체계라고 보시면 됩니다.
| 비교 차원 | .claude/ 폴더 |
.agents/ 폴더 |
|---|---|---|
| 소속 | Anthropic (Claude Code 전용) | Agentic AI 재단 / Linux 재단 |
| 위치 | Claude Code 프로젝트 설정 디렉토리 | 도구에 독립적인 Agent 설정 표준 |
| Skills 형식 | SKILL.md (Markdown + YAML 메타데이터) |
SKILL.yaml (순수 YAML) |
| 성숙도 | 프로덕션 준비 완료, Claude Code 공식 지원 | 표준 제정 중 (Work In Progress) |
| 도구 간 호환성 | Claude Code만 지원 | 모든 AI Agent 도구 지원을 목표로 설계 |
.agents 와 .claude 폴더의 설계 철학 차이
이 두 폴더의 근본적인 차이는 설계 철학에 있습니다.
.claude/는 "전용 심층 통합" 방식입니다. Claude Code에 맞춰 Skills, Subagents, Hooks, Permissions 등 모든 기능을 제공하며, Claude Code의 툴체인과 깊게 연동됩니다. 장점은 기능이 완벽하고 바로 사용할 수 있다는 것이지만, Claude Code 생태계에 종속된다는 단점이 있습니다.
.agents/는 "도구 간 범용 표준" 방식입니다. 마치 편집기에서의 .editorconfig처럼, 모든 AI Agent 도구가 이해할 수 있는 설정 규격을 정의하려고 합니다. 장점은 하나의 설정으로 여러 도구에서 사용할 수 있다는 것이지만, 표준이 아직 발전 중이며 각 도구의 지원 수준이 다를 수 있다는 점이 단점입니다.
이 둘은 같은 프로젝트 내에서 얼마든지 공존할 수 있습니다. Claude Code 전용의 심층 설정은 .claude/에, 도구 간에 재사용 가능한 범용 설정은 .agents/에 두면 됩니다.
.claude 폴더 전체 디렉토리 구조
먼저 Claude Code의 기본인 .claude/ 폴더를 살펴보겠습니다. 현재 가장 성숙한 구현 방식입니다.
.claude 폴더 디렉토리 구조 상세 설명
.claude/
├── CLAUDE.md # 프로젝트 지시사항 (루트 CLAUDE.md 대체)
├── settings.json # 프로젝트 설정 (git에 커밋하여 팀 공유)
├── settings.local.json # 로컬 설정 (gitignore, 개인 설정)
├── skills/ # Skills (기능) 디렉토리
│ └── <skill-name>/
│ ├── SKILL.md # 스킬 정의 파일 (필수)
│ ├── scripts/ # 보조 스크립트
│ ├── references/ # 참고 자료
│ └── templates/ # 템플릿 파일
├── agents/ # 하위 에이전트 정의
│ └── <agent-name>.md # 하위 에이전트 정의 파일
├── commands/ # 이전 버전의 슬래시 명령어 (skills로 통합됨)
│ └── <command-name>.md
└── agent-memory/ # 하위 에이전트의 영구 기억
└── <agent-name>/
└── MEMORY.md
또한 사용자 레벨의 ~/.claude/ 디렉토리도 있습니다. 개인 Skills를 이곳에 두면 모든 프로젝트에서 적용됩니다.
~/.claude/
├── CLAUDE.md # 사용자 레벨 지시사항 (프로젝트 간 적용)
├── settings.json # 사용자 레벨 설정
├── skills/ # 개인 Skills (모든 프로젝트에서 사용 가능)
├── agents/ # 개인 하위 에이전트
└── projects/ # 대화 기록 및 데이터
.claude 폴더 Skills의 SKILL.md 형식
Claude Code의 Skills는 Markdown 파일과 YAML 전치 메타데이터를 조합하여 정의합니다.
---
name: my-skill
description: 스킬 설명, Claude가 언제 트리거할지 판단하는 데 도움
user-invocable: true # 사용자가 /my-skill 명령어로 호출 가능
allowed-tools: Read, Grep # 사용 가능한 도구 제한
context: fork # 독립적인 하위 에이전트에서 실행
model: sonnet # 모델 커버리지
---
당신은 전문적인 코드 검토 보조원입니다...
(Markdown 형식의 스킬 지시사항)
주요 필드 설명:
user-invocable: true인 Skill은/slash-command로 등록됩니다.context: fork는 주 대화에 영향을 주지 않고 독립적인 컨텍스트에서 실행됨을 의미합니다.allowed-tools는 Skill이 사용할 수 있는 도구 집합을 제한할 수 있습니다.$ARGUMENTS,$0,$1은 매개변수 치환을 지원합니다.
🎯 개발 팁: Claude Code의 Skills 시스템은 Agent Skills 오픈 표준(agentskills.io)을 따르며, 문법은 Claude Code, Claude API, VS Code Copilot에서 공통으로 사용할 수 있습니다.
Claude Code로 AI 애플리케이션을 개발하신다면, APIYI apiyi.com에서 API 키를 발급받아 여러 모델 호출을 통합 관리하는 것을 추천합니다.
.agents 폴더의 전체 디렉터리 구조
.agents/ 폴더 규격(AGENTS-1 Spec)은 Agentic AI 재단에서 관리하며, Linux 재단 산하에 호스팅되어 모든 AI 코딩 도구가 이해할 수 있는 범용 설정 표준을 정의하는 것을 목표로 합니다.
.agents 폴더 디렉터리 구조 상세 설명
.agents/
├── manifest.yaml # 필수: 설정을 등록하고 사용 가능한 모든 설정을 선언합니다.
├── prompts/ # 필수: 지시 프롬프트
│ ├── base.md # 범용 Agent 지시
│ ├── project.md # 프로젝트별 지시
│ └── snippets/ # 모듈화된 지시 조각
├── modes/ # 필수: 행동 모드 (예: .claude/agents/ 와 유사)
│ ├── plan.md # 계획 모드
│ ├── code.md # 코딩 모드
│ └── review.md # 검토 모드
├── policies/ # 필수: 보안 정책 및 능력 제약
├── skills/ # 필수: 스킬 정의 (Agent Skills 규격 준수)
│ └── <name>/
│ └── SKILL.yaml # YAML 형식 스킬 정의
├── scopes/ # 필수: 경로별 재정의 (Monorepo 지원)
├── profiles/ # 필수: 명명된 설정 오버레이 (dev/ci/staging)
├── schemas/ # 필수: JSON Schema 검증
└── state/ # 로컬 상태 (git에 커밋되지 않음)
├── .gitignore
└── state.yaml
.claude/의 Skills가 SKILL.md(Markdown)를 사용하는 것과 달리, .agents/의 Skills는 SKILL.yaml(순수 YAML) 형식을 사용합니다.
.agents 폴더의 독특한 설계
.agents/ 규격에는 .claude/에는 없는 몇 가지 개념이 있습니다.
- Scopes(범위): Monorepo 내의 다른 하위 디렉터리에 대해 다른 설정을 정의하며, 가장 구체적인 경로가 우선적으로 일치합니다.
- Profiles(프로필):
dev,ci,prod등 명명된 설정 오버레이를 지원하며, 환경 변수와 유사합니다. - Policies(정책): 독립적인 보안 제약 디렉터리이며,
deny규칙은 항상allow규칙을 재정의합니다. - Determinism(결정성): 동일한 입력은 외부 상태에 의존하지 않고 동일한 출력을 생성해야 합니다.
.agents 및 .claude 폴더의 Skills 저장 규칙 비교
이것은 개발자가 가장 궁금해하는 실질적인 문제입니다. 제 Skills는 어디에 저장해야 할까요?
.agents 및 .claude 폴더 Skills 비교
| 비교 항목 | .claude/skills/ |
.agents/skills/ |
|---|---|---|
| 정의 파일 | SKILL.md (Markdown + YAML frontmatter) |
SKILL.yaml (순수 YAML) |
| Claude Code 지원 | 네이티브 지원, 자동 검색 | 수동 구성 또는 공식 지원 대기 필요 |
| 슬래시 명령 | user-invocable: true로 /command 자동 등록 |
특정 도구 구현에 따라 다름 |
| 하위 에이전트 실행 | context: fork로 독립적인 컨텍스트에서 실행 |
modes/를 통해 구성 |
| 모델 재정의 | model: sonnet으로 직접 지정 |
profiles/를 통해 구성 |
| 도구 제한 | allowed-tools: Read, Grep |
policies/를 통해 구성 |
| 보조 파일 | scripts/, references/, templates/ 하위 디렉터리 |
구현에 따라 다름 |
| 매개변수 전달 | $ARGUMENTS, $0, $1 변수 치환 |
규격에 명확하게 정의되지 않음 |
.agents 및 .claude 폴더 공존 방법
실제 프로젝트에서는 두 폴더를 함께 사용하여 상호 보완할 수 있습니다. 이 프로젝트를 예로 들어보겠습니다.
.claude/skills/에 Claude Code 전용 스킬 저장:
apiyi-article-generator— 글쓰기 생성, 프로젝트 템플릿 및 사양과 깊이 통합apiyi-svg-generator— SVG 삽화 생성, 프로젝트 SVG 템플릿에 의존apiyi-content-reviewer— 콘텐츠 검토, 프로젝트 품질 표준 사용
.agents/skills/에 범용 이식 가능한 스킬 저장:
markdown-proxy— URL을 Markdown으로 변환하는 크롤링, Python 스크립트 사용nano-banana-pro-image-gen— 이미지 생성, 외부 API 호출
분할 원칙은 명확합니다: Claude Code와 깊이 통합된 것은 .claude/에, 다른 AI 도구에서 재사용 가능한 것은 .agents/에 저장합니다.
🎯 선택 제안: 팀에서 Claude Code만 사용한다면 모든 스킬을
.claude/skills/에 넣으면 됩니다. 기능이 가장 완벽합니다.
팀 구성원이 Cursor, Windsurf, Codex 등 다양한 AI 도구를 사용한다면, 범용 스킬을.agents/skills/에 두는 것이 협업에 더 유리합니다.
AI Agent 개발 중 API 호출은 APIYI apiyi.com을 통해 통합 관리하는 것을 추천합니다. 하나의 API 키로 다양한 모델을 사용할 수 있습니다.
.agents 와 .claude 프로젝트 설정 파일 비교
Skills 폴더 외에도, 두 시스템에는 각각 프로젝트 설정 파일이 존재합니다.
CLAUDE.md 와 AGENTS.md 의 차이점
| 비교 항목 | CLAUDE.md | AGENTS.md |
|---|---|---|
| 지원 도구 | Claude Code | Claude Code, OpenAI Codex, Google Jules, Cursor, GitHub Copilot 등 |
| 파일 계층 | 사용자 레벨 (~/.claude/) → 프로젝트 레벨 (./) → 하위 디렉토리 레벨 |
프로젝트 레벨 (./) → 하위 디렉토리 레벨 |
| 로컬 재정의 | CLAUDE.local.md (gitignore) |
없음 |
| 공식 표준 | 없음 (Anthropic 제품 문서) | 있음 (Linux Foundation 산하 Agentic AI Foundation) |
| 생태계 규모 | 성장 중 (Next.js, LangChain, Deno 등 채택) | 대규모 (n8n 178K stars, llama.cpp 97K stars, Bun 82K stars) |
| 초기화 | Claude Code 내 /init 명령어 |
수동 생성 |
실제 권장 사항: 두 파일을 함께 사용할 수 있습니다. CLAUDE.md에는 Claude Code 전용 설정(예: Hooks 설정, 권한 규칙)을, AGENTS.md에는 모든 AI 도구에 공통으로 적용되는 프로젝트 컨텍스트(예: 빌드 명령어, 코딩 규약, 아키텍처 설명)를 넣는 것이 좋습니다.
.agents 와 .claude 연동 파일 생태계 개요
| 파일/디렉토리 | 소속 시스템 | 용도 | git 제출 여부 |
|---|---|---|---|
CLAUDE.md |
.claude | Claude Code 프로젝트 설정 | 예 |
CLAUDE.local.md |
.claude | 개인 로컬 설정 | 아니요 |
.claude/settings.json |
.claude | 권한, Hooks, MCP | 예 |
.claude/settings.local.json |
.claude | 개인 로컬 설정 | 아니요 |
AGENTS.md |
.agents | 범용 Agent 프로젝트 설정 | 예 |
.agents/manifest.yaml |
.agents | 설정 레지스트리 | 예 |
.agents/state/state.yaml |
.agents | 로컬 실행 상태 | 아니요 |
.cursorrules |
Cursor | Cursor 전용 규칙 | 예 |
팁: 2026년 ETH Zurich 연구에 따르면, AI가 생성한 컨텍스트 파일이 오히려 Agent 성능을 저하시킬 수 있다는 결과가 나왔습니다. 따라서 사람이 직접 작성하고, 코드에서 추론하기 어려운 비명시적인 정보(사용자 정의 툴체인, 비정형 패턴 등)로 제한하는 것이 좋습니다.
자주 묻는 질문
Q1: Claude Code는 .agents/skills/ 디렉토리의 Skills를 읽을 수 있나요?
현재 Claude Code는 네이티브로 .claude/skills/에서만 Skills를 자동으로 탐색하고 로드합니다. .agents/skills/의 내용은 자동으로 인식되지 않습니다. 커뮤니티에서 GitHub에 Claude Code가 .agents/ 디렉토리를 지원하도록 요청하는 Issue(#31005)를 제출했습니다. Claude Code에서 Skills를 사용하려면 현재 .claude/skills/에 배치해야 합니다.
Q2: .agents 폴더 규격은 성숙되었나요? 프로덕션 프로젝트에 사용할 수 있나요?
.agents/ 폴더 규격(AGENTS-1 Spec)은 현재 개발 중(Work In Progress)이지만, AGENTS.md 파일은 이미 널리 채택되었습니다. n8n(178K stars), llama.cpp(97K stars), Bun(82K stars) 등 대규모 오픈소스 프로젝트에서 사용하고 있습니다. 범용 지시 파일로 AGENTS.md를 먼저 채택하고, .agents/의 전체 디렉토리 구조 등 규격이 안정화된 후에 사용하는 것을 권장합니다.
Q3: 팀원들이 각기 다른 AI 도구(Claude Code + Cursor)를 사용할 때 설정을 어떻게 관리해야 하나요?
계층별 관리를 추천합니다: 1) AGENTS.md에는 범용 프로젝트 정보(빌드 명령, 코딩 규범)를 넣어 모든 도구가 읽도록 합니다. 2) CLAUDE.md에는 Claude Code 전용 지시를 넣습니다. 3) .cursorrules에는 Cursor 전용 규칙을 넣습니다. 범용 Skills는 .agents/skills/에, 도구별 전용 Skills는 각 디렉토리에 넣습니다. APIYI apiyi.com을 통해 팀의 AI API 호출을 통합 관리하면, 하나의 플랫폼으로 모든 모델을 커버할 수 있습니다.
Q4: SKILL.md와 SKILL.yaml의 형식 차이는 무엇인가요?
SKILL.md는 Claude Code의 형식으로, Markdown 파일 + YAML 프론트매터(frontmatter)를 사용합니다. 지시 부분은 Markdown으로 작성되어 사람이 읽기 더 좋습니다. SKILL.yaml은 .agents/ 규격의 형식으로, 전체 YAML 구조로 정의되어 기계가 파싱하기 더 편리합니다. 두 형식 모두 핵심 정보(이름, 설명, 트리거 조건)는 동일하며, 형식만 다릅니다.
요약
.agents와 .claude 폴더의 핵심 차이점은 다음과 같습니다.
- 목적의 차이:
.claude/는 Claude Code의 전용 프로젝트 설정 디렉토리로, 모든 Claude Code 기능을 깊이 통합합니다..agents/는 Linux Foundation 산하의 도구 간 범용 표준입니다. - Skills 형식의 차이:
.claude/skills/는SKILL.md(Markdown)를 사용하며 Claude Code가 네이티브로 로드합니다..agents/skills/는SKILL.yaml(YAML)을 사용하며 도구에 독립적으로 설계되었습니다. - 공존 및 상호 보완 가능: Claude Code의 심층 기능(Hooks, 하위 에이전트, 권한)은
.claude/에, 범용 이식 가능한 스킬은.agents/에, 프로젝트 기본 지시는AGENTS.md에 배치할 수 있습니다.
어떤 폴더를 선택할지는 팀의 툴체인 구성과 스킬의 이식성 요구사항에 따라 결정됩니다.
APIYI apiyi.com을 통해 AI 에이전트 개발 시 모델 호출을 통합 관리하는 것을 추천합니다. 이 플랫폼은 무료 사용량과 통합된 단일 인터페이스를 제공하며, Claude, GPT, Gemini 등 주요 모델을 한 곳에서 연동할 수 있습니다.
📚 참고 자료
-
Claude Code Skills 공식 문서: Skills의 전체 정의, 형식 및 사용 방법
- 링크:
code.claude.com/docs/en/skills - 설명: SKILL.md 형식, 트리거 규칙 및 매개변수 전달에 대해 알아보세요.
- 링크:
-
Claude Code 서브 에이전트 문서: Subagents의 정의 및 구성 방법
- 링크:
code.claude.com/docs/en/sub-agents - 설명:
.claude/agents/디렉토리의 파일 형식에 대해 알아보세요.
- 링크:
-
AGENTS.md 공식 웹사이트: 도구 간 Agent 명령어 파일 표준
- 링크:
agents.md - 설명: AGENTS.md 작성 규범 및 지원 도구 목록을 알아보세요.
- 링크:
-
.agents/폴더 규격: AGENTS-1 Spec의 전체 디렉토리 구조 정의- 링크:
github.com/agentsfolder/spec - 설명: manifest.yaml, modes, policies, scopes의 설계에 대해 알아보세요.
- 링크:
-
APIYI 문서 센터: AI Agent 개발에서의 통합 API 호출 관리
- 링크:
docs.apiyi.com - 설명: 다중 모델 통합 인터페이스를 지원하여 Agent 개발 시나리오에 적합합니다.
- 링크:
작성자: APIYI 기술팀
기술 교류: 댓글로 자유롭게 토론해 주세요. 더 많은 자료는 APIYI docs.apiyi.com 문서 센터에서 확인하실 수 있습니다.
