Claude Code Skill이란? SKILL.md부터 AGENTS.md까지 실전 구조 완전 정리 (2026)

Claude Code Skill이란? SKILL.md부터 AGENTS.md까지 실전 구조 완전 정리 (2026)

한 줄 요약

Claude Code Skill은 반복되는 개발 작업을 재사용 가능한 폴더 단위 능력(Skill)으로 정의하는 구조이며, SKILL.md, scripts, references를 조합해 AI가 프로젝트 규칙과 작업 흐름을 일관되게 수행하도록 만든다. (GitHub)

---

이 글에서 다루는 내용

• Claude Code Skill이란?
• SKILL.md 구조
• AGENTS.md 역할
• Skill 폴더 설계
• 실제 예제
• 실무 주의사항
• FAQ

---

Claude Code Skill이란?

Claude Skill은 특정 작업을 반복 가능하게 만드는 작업 패키지다.

공식 문서 기준 Skill은 다음 요소를 포함한다.

metadata
+
instructions
+
scripts
+
references

Claude는 Skill을 자동 탐색하고 필요할 때만 로드한다. (GitHub)

---

왜 Claude Skill을 사용하는가?

문제:

매번 같은 프롬프트 입력
↓
결과 편차 발생
↓
품질 불안정

Skill:

작업 규칙 저장
↓
반복 실행
↓
결과 표준화

Anthropic도 Skills를 반복 가능한 전문 작업과 팀 표준화 용도로 설명한다. (Verdent AI)

---

Claude Skill 기본 구조

최소 구조

my-skill/

├── SKILL.md

추천 구조

my-skill/

├── SKILL.md
├── references/
├── scripts/
├── examples/
├── evals/

Skill은 폴더 단위로 발견되며 SKILL.md가 진입점 역할을 한다. (Agent Skills)

---

SKILL.md란?

SKILL.md는 Skill의 핵심 정의 파일이다.

예제:

---
name: nestjs-review

description: Review NestJS backend code.

tools:
 - bash
 - edit
---

# Purpose

Review code.

# Workflow

1. Read references
2. Execute checks
3. Generate report

설명(description)은 언제 Skill을 사용할지 결정하는 핵심 요소라서 명확해야 한다. (Claude 도움말 센터)

---

AGENTS.md란?

반응형

AGENTS.md는 프로젝트 전체 운영 규칙이다.

예:

repo/

AGENTS.md
skills/
context/
subagents/

예시:

# Backend Rules

- NestJS only
- Controller thin
- Service transaction
- Repository no business logic

Agent가 프로젝트 규칙을 계속 유지하도록 도와준다. Context 중심 구조가 최근 실무 패턴으로 확산 중이다. (Medium)

---

Claude Skill 실제 예제 — NestJS 코드 리뷰

목표

코드 작성
↓
자동 리뷰
↓
테스트
↓
리포트 생성

---

폴더

skills/

└── review/
    ├── SKILL.md
    ├── scripts/
    │     └── validate.sh
    └── references/

---

validate.sh

#!/bin/bash

npm run lint
npm run test

echo "review completed"

---

실행

/skill review

---

실무에서 반드시 알아야 하는 것

1. SKILL.md는 길게 쓰지 말 것

Skill은 다른 컨텍스트와 공간을 공유한다.

→ 필요한 정보만 단계적으로 로딩한다.

이를 Progressive Disclosure라고 한다. (클로드 플랫폼)

---

2. deterministic 작업은 script로 분리

좋지 않음:

Claude가 SQL 생성

좋음:

Claude
↓
scripts/run_query.py

공식 가이드도 반복되는 작업은 script 사용을 권장한다. (GitHub)

---

3. Eval 없이 운영하지 말 것

추천:

evals/
test-cases/
benchmark/

최근 흐름은 Skill → Eval → 개선 구조다. (arXiv)

---

자주 발생하는 오류

오류 1. Skill이 실행되지 않음

원인:

description 모호

해결:

언제 사용할지 명확히 작성

---

오류 2. Context 폭발

원인:

SKILL.md 너무 큼

해결:

references 분리

---

오류 3. 이상한 Skill 선택

원인:

skill 충돌

해결:

trigger 좁게 정의

최근 연구에서는 SKILL.md 자체가 Skill 선택과 신뢰에 영향을 주는 공급망 리스크가 될 수 있다고 지적한다. (arXiv)

---

FAQ

Q. Claude Skill과 MCP 차이는?

구분SkillMCP

역할	작업 방식	외부 연결
목적	반복 작업	도구 접근
저장	로컬 폴더	서버

MCP는 연결, Skill은 작업 절차를 정의한다. (Verdent AI)

---

Q. Skill은 Claude Code만 가능한가요?

아니다.

일부 Agent Skill 포맷은 여러 도구와 호환되는 방향으로 확장 중이다. (Medium)

---

Q. Skill은 몇 개까지 만드는 게 좋은가요?

추천:

3~7개

많다고 좋은 게 아니라 재사용 빈도 기준으로 만든다.

---

핵심 요약

• Claude Skill은 반복 작업을 패키징하는 구조
• SKILL.md + scripts + references가 핵심
• AGENTS.md는 프로젝트 규칙 정의
• Progressive Disclosure가 중요
• Eval과 보안을 함께 고려해야 함

---

출처

• Anthropic Claude Skills Docs (클로드 플랫폼)
• Anthropic Skills Repository (GitHub)
• Agent Skills 분석 논문 (arXiv)
• Skill 보안 연구 (arXiv)

---

ClaudeCode, ClaudeSkill, SKILLmd, AGENTSmd, AgentSkills, LLM개발, ContextEngineering, AI개발, NestJS, AI자동화