Claude Code 커스텀 스킬 만들기 (+ OpenCode, Roo Code)

AI 코딩 에이전트를 쓰다 보면 반복되는 패턴이 생깁니다. “커밋 메시지는 한국어로 써줘”, “PR 설명은 이 형식으로”, “코드리뷰는 이 기준으로” — 매번 같은 말을 하게 됩니다.

Claude Code의 Skills는 이런 반복 지침을 재사용 가능한 모듈로 만드는 시스템입니다. 한번 만들어두면 npx skills add로 누구나 설치할 수 있고, 필요할 때 자동으로 로드됩니다.

이 글에서는 커스텀 스킬을 처음부터 만들고, 테스트하고, 배포하는 전체 과정을 다룹니다.

Skills란?

Skills는 Claude가 특정 작업을 수행할 때 동적으로 로드하는 지침 파일입니다. 핵심은 SKILL.md — YAML 프론트매터와 마크다운 지침으로 구성된 단일 파일입니다.

my-skill/
├── SKILL.md          # 필수: 프론트매터 + 지침
├── scripts/          # 선택: 실행 가능한 코드
├── references/       # 선택: 참조 문서
└── assets/           # 선택: 템플릿, 리소스

Claude는 대화 시작 시 설치된 스킬의 name과 description만 읽습니다(~100 토큰). 사용자의 요청이 스킬과 관련되면 그때 SKILL.md 본문을 로드하고, 필요하면 scripts/나 references/ 파일까지 참조합니다. 이 프로그레시브 디스클로저 덕분에 컨텍스트 윈도우를 낭비하지 않습니다.

SKILL.md 구조

최소한의 스킬은 이렇게 생겼습니다:

---
name: my-skill
description: 이 스킬이 하는 일과 언제 사용해야 하는지 설명
---

# 스킬 지침

여기에 Claude가 따라야 할 지침을 작성합니다.

프론트매터 필드

필드	필수	설명
`name`	O	소문자+숫자+하이픈, 1-64자. 폴더명과 일치해야 함
`description`	O	스킬의 용도와 트리거 조건. 1-1024자
`license`		라이선스
`compatibility`		환경 요구사항
`metadata`		임의 key-value

description이 가장 중요합니다. Claude는 이 텍스트를 보고 “이 스킬을 지금 로드할지” 판단합니다. 적극적으로 작성하세요 — Claude는 스킬을 과소 트리거하는 경향이 있어서, 관련 키워드와 사용 시나리오를 구체적으로 나열하는 것이 좋습니다.

지침 작성 팁

명령형으로 작성하세요. “~할 수 있습니다”가 아니라 “~하세요”.

# 좋은 예
커밋 메시지를 한국어로 작성하세요.
제목은 50자 이내로 유지하세요.

# 나쁜 예
커밋 메시지는 한국어로 작성할 수 있습니다.
제목은 50자 이내가 좋습니다.

WHY를 설명하세요. ALWAYS/NEVER보다 이유를 적는 것이 효과적입니다.

# 좋은 예
테스트 파일에는 반드시 에러 케이스를 포함하세요.
프로덕션에서 발견된 버그의 60%가 에러 핸들링 누락이었습니다.

# 나쁜 예
ALWAYS include error cases in tests.

500줄 이하로 유지하세요. 스킬이 길어지면 references/ 폴더에 별도 문서로 분리하고, 본문에서 참조하는 구조로 만드세요.

실전: 한국어 커밋 스킬 만들기

실제로 간단한 스킬을 만들어 보겠습니다. “커밋 메시지를 한국어로 작성하는” 스킬입니다.

1단계: 폴더 생성

mkdir -p ko-commit

2단계: SKILL.md 작성

---
name: ko-commit
description: >
  커밋 메시지를 한국어로 작성하는 스킬.
  /commit, git commit, 커밋, "변경사항 커밋" 등의 요청에 트리거됩니다.
  한국어 커밋 컨벤션을 따릅니다.
---

# 한국어 커밋 메시지

커밋 메시지를 작성할 때 다음 규칙을 따르세요.

## 형식

<타입>: <제목>

<본문 (선택)>


## 타입

- `기능`: 새로운 기능 추가
- `수정`: 버그 수정
- `리팩터`: 동작 변경 없는 코드 개선
- `문서`: 문서 추가/수정
- `스타일`: 코드 포맷, 세미콜론 등
- `설정`: 빌드, CI, 의존성 등

## 규칙

- 제목은 50자 이내로 작성하세요
- 제목에 마침표를 붙이지 마세요
- 본문은 변경 이유를 설명하세요 (무엇을 했는지가 아님)
- 한 커밋에 하나의 논리적 변경만 포함하세요

3단계: 설치 및 테스트

로컬에서 바로 테스트할 수 있습니다:

# 프로젝트 .claude/skills/ 에 복사
mkdir -p .claude/skills/ko-commit
cp ko-commit/SKILL.md .claude/skills/ko-commit/

이제 Claude Code에서 /commit을 실행하면 한국어 커밋 메시지를 생성합니다.

skill-creator로 품질 높이기

anthropics/skills 저장소의 skill-creator는 스킬을 체계적으로 만들고 평가하는 도구입니다.

설치

npx skills add anthropics/skills skill-creator

주요 기능

1. 인터뷰 기반 스킬 생성 — /skill-creator를 실행하면 목적, 입출력, 엣지 케이스 등을 질문하고 SKILL.md를 자동 생성합니다.

2. 테스트 및 평가 — evals/evals.json에 테스트 케이스를 정의하고 자동으로 실행합니다:

[
  {
    "prompt": "이 변경사항을 커밋해줘",
    "expectations": [
      "커밋 메시지가 한국어로 작성됨",
      "타입 접두사가 포함됨",
      "제목이 50자 이내"
    ]
  }
]

3. A/B 비교 — 스킬 적용 전/후를 블라인드 비교하여 실제 개선 효과를 측정합니다.

4. Description 최적화 — 트리거 정확도를 높이기 위해 should-trigger / should-not-trigger 쿼리로 자동 테스트 루프를 돌립니다.

배포하기

GitHub 저장소로 공유

스킬을 GitHub 저장소에 올리면 누구나 설치할 수 있습니다:

# 설치하는 사용자
npx skills add username/repo skill-name

저장소 구조:

my-skills-repo/
├── skills/
│   ├── ko-commit/
│   │   └── SKILL.md
│   └── ko-review/
│       └── SKILL.md
└── README.md

실제 예시

제가 만든 스킬 저장소들입니다:

geniuskey/ko-skills — 한국어 커밋, PR, 코드리뷰 스킬
geniuskey/skills — 다양한 커스텀 스킬 모음

설치:

npx skills add geniuskey/ko-skills

부록 A: OpenCode에서 커스텀 지침 만들기

OpenCode는 Claude Code와 유사한 터미널 AI 코딩 에이전트입니다. 스킬과 비슷한 커스터마이징을 4가지 방식으로 지원합니다.

1. Rules (AGENTS.md)

프로젝트 루트에 AGENTS.md를 만들면 모든 대화에 자동 적용됩니다. Claude Code의 CLAUDE.md와 같은 역할입니다.

# 프로젝트 규칙

- TypeScript strict mode 사용
- 커밋 메시지는 한국어로 작성
- 테스트 파일은 `__tests__/` 디렉토리에 배치

글로벌 설정: ~/.config/opencode/AGENTS.md

추가 파일 포함 (opencode.json):

{
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md"]
}

2. Custom Agents

.opencode/agents/ 디렉토리에 마크다운 파일을 만들면 전용 에이전트를 정의할 수 있습니다.

---
description: 한국어 코드리뷰 전문 에이전트
model: anthropic/claude-sonnet-4-20250514
---

코드리뷰를 수행할 때 다음을 확인하세요:
- 타입 안전성
- 에러 핸들링
- 성능 이슈
리뷰 결과를 한국어로 작성하세요.

파일명이 에이전트 ID가 됩니다 — reviewer.md로 저장하면 @reviewer로 호출할 수 있습니다.

3. Custom Commands

.opencode/commands/ 에 마크다운 파일을 만들면 슬래시 명령어를 정의할 수 있습니다.

---
description: 한국어 커밋 메시지 생성
---

변경사항을 분석하고 한국어 커밋 메시지를 작성하세요.
$ARGUMENTS 가 있으면 해당 내용을 반영하세요.

commit.md로 저장하면 /commit 명령어로 사용할 수 있습니다.

4. Agent Skills (호환)

OpenCode는 Agent Skills 표준을 지원합니다. .opencode/skills/ 또는 .claude/skills/ 경로에서 SKILL.md를 자동 탐색합니다.

.opencode/skills/ko-commit/SKILL.md
.claude/skills/ko-commit/SKILL.md      # Claude Code와 공유 가능

부록 B: Roo Code에서 커스텀 모드 만들기

Roo Code는 VS Code 확장 기반 AI 코딩 에이전트입니다. Custom Modes와 Custom Instructions 두 가지 시스템을 제공합니다.

1. Custom Modes

프로젝트 루트에 .roomodes 파일(YAML 또는 JSON)을 만들어 전용 모드를 정의합니다.

customModes:
  - slug: ko-committer
    name: "한국어 커밋"
    roleDefinition: |
      한국어 커밋 메시지를 작성하는 전문 모드입니다.
      커밋 메시지 형식: <타입>: <제목>
      타입: 기능, 수정, 리팩터, 문서, 스타일, 설정
    whenToUse: "커밋 메시지를 작성할 때 사용"
    groups:
      - read
      - command

글로벌 설정: settings/custom_modes.yaml

groups로 도구 접근을 제한할 수 있습니다:

그룹	설명
`read`	파일 읽기
`edit`	파일 수정
`command`	셸 명령 실행
`mcp`	MCP 서버 도구

파일 패턴으로 세밀한 제어도 가능합니다:

groups:
  - read
  - - edit
    - fileRegex: \.(md|mdx)$
      description: Markdown 파일만 수정 가능

2. Custom Instructions (Rules)

.roo/rules/ 디렉토리에 .md 파일을 넣으면 모든 모드에 적용되는 지침이 됩니다.

.roo/
├── rules/                    # 모든 모드에 적용
│   ├── 01-coding-style.md
│   └── 02-testing.md
└── rules-ko-committer/       # ko-committer 모드에만 적용
    └── commit-rules.md

파일명 기준 알파벳 순서로 로드됩니다. 번호 접두사(01-, 02-)를 붙이면 순서를 제어할 수 있습니다.

글로벌 규칙: ~/.roo/rules/에 넣으면 모든 프로젝트에 적용됩니다.

정리

	Claude Code	OpenCode	Roo Code
핵심 파일	`SKILL.md`	`AGENTS.md`	`.roomodes`
프로젝트 경로	`.claude/skills/`	`.opencode/`	`.roo/rules/`
글로벌 경로	`~/.claude/skills/`	`~/.config/opencode/`	`~/.roo/rules/`
설치 명령	`npx skills add`	-	-
특징	프로그레시브 로딩, 공유 생태계	에이전트/커맨드 분리, 권한 제어	모드별 도구 제한, 파일 패턴 제어

세 도구 모두 “마크다운 파일에 지침을 작성한다”는 기본 원리는 같습니다. Claude Code는 Skills 생태계를 통해 공유와 설치가 편리하고, OpenCode는 에이전트와 커맨드를 분리해 유연하며, Roo Code는 모드별로 도구 접근을 세밀하게 제어할 수 있다는 차이가 있습니다.

어떤 도구를 쓰든, 핵심은 같습니다 — 반복하는 지침을 파일로 만들어 두세요.