Skills 란 무엇인가?

Skills는 Claude가 자동으로 꺼내 쓰는 업무 메뉴얼이다.

.claude/skills/ 폴더 안에 마크다운 파일로 작성해두면, Claude가 대화 맥락을 보고 관련 Skill을 자동으로 로드한다.
또는, /명령어 형태로 직접 호출할 수 있다.

비유하자면, 신입 직원에게 구두로 매번 설명하는 대신, 잘 정리된 업무 메뉴얼 파일을 책상 위에 올려두고 필요할 때 꺼내 읽고 따른다.

Skills 기본 구조

.claude/skills/
├── SKILL.md           # 메인 지시사항 (필수)
├── template.md        # Claude가 채울 템플릿
├── examples/
│   └── sample.md      # 기대 출력 예시
└── scripts/
    └── validate.sh    # Claude가 실행할 스크립트

필수 파일은 SKILL.md 뿐이며, 나머지는 선택사항이다.
template.md 는 Claude가 출력을 생성할 때 참조하는 템플릿, examples/ 는 기대 출력 예시, scripts/ 는 스킬 실행 중 호출할 수 있는 스크립트

SKILL.md 파일 작성법

SKILL.md 파일은 frontmatter + 본문 지시사항, 두 부분으로 구성된다.

---
name: coding-style
description: 코드를 작성하거나 수정할 때 팀 컨벤션과 주석 스타일을 적용해야 할 때
allowed-tools: Read, Write, Edit
---

## 코드 작성 규칙

### 함수 주석
모든 함수는 JSDoc 형식의 주석을 반드시 포함할 것:

/**
 * 사용자 정보를 조회합니다.
 * @param {string} userId - 조회할 사용자의 ID
 * @returns {Promise<User>} 사용자 객체
 * @throws {NotFoundError} 사용자가 존재하지 않을 경우
 */

### 에러 처리
- 모든 비동기 함수는 try/catch로 감쌀 것
- catch 블록에서 에러를 그냥 무시하지 말 것
- 에러 메시지는 사용자가 이해할 수 있는 언어로 작성할 것

### 네이밍
- 변수명: camelCase
- 상수: UPPER_SNAKE_CASE
- 컴포넌트: PascalCase

frontmatter 에서 중요한 필드는 description 이다.
Claude 가 이 설명을 보고 언제 이 Skill을 꺼낼지 판단하기 때문에, 구체적이고 명확하게 적을수록 자동 감지가 잘 된다.

Plugins란 무엇인가?

Skills를 만들다 보면 이런 상황이 생긴다.

"이 설정, 팀원들한테 공유하고 싶다."

Skills, Commands, Hooks, MCP 설정을 개인이 하나씩 만드는 건 번거롭다.
Plugin은 이걸 하나로 묶어서 배포하는 패키지다.

my-team-plugin/
├── skills/
│   ├── coding-style.md
│   └── code-review.md
├── commands/
│   ├── deploy.md
│   └── tdd.md
├── hooks/
│   └── pre-commit.sh
├── mcp/
│   └── config.json
└── plugin.json            ← 패키지 메타데이터

Skills의 핵심은 단순하다. "매번 겉은 말을 반복하지 않는 것" 이다.

프로젝트마다 코딩 규칙이 다르고, 팀마다 리뷰 기준이 다르다.
그 기준을 SKILL.md 파일에 한 번 잘 정리해두면, 이후 모든 작업에서 Claude가 그 규칙을 따른다.

클로드 코드 Skills & Plugins

댓글

댓글