AI 코딩 에이전트 스킬 사용법

Claude Code와 Gemini CLI에 프로젝트 전용 지식을 주입하는 방법을 다룬다. 스킬의 개념을 이해한 뒤, AI에게 먼저 환경 분석을 시키고 그 결과에 맞는 스킬을 작성하는 흐름을 익힌다.

코드 블록의 Try it Yourself 버튼으로 직접 실행할 수 있다.

구문

AI 코딩 에이전트 스킬 사용법

Claude Code와 Gemini CLI에 프로젝트 전용 지식을 주입하는 방법을 다룬다. 스킬의 개념을 이해한 뒤, AI에게 먼저 환경 분석을 시키고 그 결과에 맞는 스킬을 작성하는 흐름을 익힌다.

1. 스킬이 필요한 이유

같은 요청을 해도 에이전트의 응답이 매번 다를 때가 있다. 한 번은 함수형 컴포넌트로 짜고, 다음엔 클래스형으로 짠다. 파일명을 MyComponent.jsx로 만들었다가 다음엔 my-component.js로 만든다.

스킬은 "이 프로젝트에서는 이렇게 한다" 를 에이전트에게 학습시키는 장치다. 한 번 잘 만들어 두면, 누가 작업해도 동일한 규칙으로 결과가 나온다.

컨텍스트 파일과의 차이

구분	컨텍스트 파일 (CLAUDE.md / GEMINI.md)	스킬 (SKILL.md)
로드 시점	세션 시작 시 항상 로드	관련 요청 감지 시에만 로드
용도	프로젝트 전반의 배경 지식	특정 작업의 상세 절차
크기 관리	커지면 토큰 낭비	수십 개 있어도 부담 없음
비유	신입사원에게 주는 회사 소개서	특정 업무 매뉴얼

규칙이 많아질수록 컨텍스트 파일은 무거워진다. 이때 스킬로 쪼개면 필요한 순간에만 불러온다.

2. SKILL.md 기본 구조

최소 구성

my-skill/
└── SKILL.md

확장 구성

my-skill/
├── SKILL.md              ← 필수
├── scripts/              ← 에이전트가 실행할 코드
├── references/           ← 필요 시 읽는 참조 문서
└── assets/               ← 템플릿, 폰트, 아이콘 등

SKILL.md 작성 형식

---
name: skill-name
description: 이 스킬이 무엇을 하고 언제 트리거되는지 설명
---

# 스킬 본문

에이전트가 따라야 할 절차와 규칙을 작성한다.

프론트매터의 필수 필드는 두 개뿐이다.

필드	제한	설명
`name`	64자	스킬 식별자
`description`	200자	트리거 판단 기준. 에이전트가 이 문장으로 매칭한다

3. 환경 분석 — AI에게 먼저 물어본다

여기가 핵심이다. 스킬은 프로젝트 환경에 맞춰야 효과가 있다. 같은 "컴포넌트 만들기" 스킬이라도 React 19 + Tailwind v4 프로젝트와 순수 HTML 프로젝트에서 내용이 달라져야 한다.

작성을 시작하기 전에, 에이전트에게 현재 프로젝트를 분석시킨다.

분석 프롬프트 템플릿

이 프로젝트의 기술 스택, 폴더 구조, 네이밍 컨벤션,
자주 반복되는 작업 패턴을 분석해줘.
결과를 다음 형식으로 정리해줘.

1. 기술 스택
2. 폴더 구조
3. 네이밍 규칙 (파일명, 컴포넌트명, 변수명)
4. 포맷팅/린트 설정
5. 반복 작업 후보 (스킬로 만들면 좋을 작업)

에이전트는 package.json, tsconfig.json, 폴더 구조, 기존 코드를 실제로 읽고 요약한다. 이 요약을 기반으로 스킬을 설계한다.

분석 결과 해석 예시

에이전트가 내놓을 응답의 형태는 프로젝트마다 다르다. 예시 두 가지를 비교한다.

응답 A — React 프로젝트

1. 기술 스택: React 19, Vite, Tailwind v4, React Router v7
2. 폴더 구조: src/components, src/pages, src/api
3. 네이밍: PascalCase.jsx 컴포넌트, camelCase 훅
4. 포맷팅: ESLint + Prettier, 세미콜론 없음
5. 반복 작업: API 훅 작성, 페이지 추가, 컴포넌트 분리

응답 B — HTML 정적 사이트

1. 기술 스택: HTML5, CSS3 (모던 기능), Vanilla JS
2. 폴더 구조: / 루트, /css, /js, /images
3. 네이밍: kebab-case.html, kebab-case.css
4. 포맷팅: Prettier만 사용
5. 반복 작업: 시맨틱 구조 확인, 접근성 점검, 반응형 작성

두 응답의 "반복 작업 후보"가 스킬 설계의 출발점이 된다.

4. 환경에 맞춘 스킬 작성

분석 결과를 에이전트에게 다시 넘기며 스킬 초안을 요청한다.

생성 프롬프트 템플릿

방금 분석한 환경에 맞춰서 다음 작업을 자동화하는
스킬을 작성해줘.

- 스킬 이름: [영문 kebab-case]
- 목적: [한 줄 설명]
- 트리거 키워드: [사용자가 쓸 법한 표현들]

SKILL.md 파일 하나로 완결되게 작성해줘.

에이전트는 앞서 분석한 환경 정보를 반영해서 SKILL.md 초안을 내놓는다.

응답 A 기반 스킬 예시

---
name: api-hook
description: >
  TMDB 같은 외부 API용 커스텀 훅을 작성하는 스킬.
  "API 훅 만들어줘", "useFetch 추가", "데이터 가져오는 훅"
  요청에 트리거된다.
---

# API 훅 작성 지침

1. 파일 위치: src/hooks/useXxx.js
2. 함수명: use + PascalCase
3. 반환값: { data, loading, error } 객체
4. 의존 배열에 쿼리 키 전부 포함
5. AbortController로 언마운트 시 요청 취소
6. 세미콜론 없이 작성

응답 B 기반 스킬 예시

---
name: a11y-check
description: >
  HTML 접근성 점검 스킬. "접근성 확인", "a11y",
  "시맨틱 검토", "스크린리더 대응" 요청에 트리거된다.
---

# 접근성 점검 지침

1. 이미지에 alt 속성이 있는지 확인한다.
2. 버튼과 링크를 구분한다 (button vs a).
3. 폼 요소에 label을 연결한다.
4. 헤딩 레벨(h1~h6)이 순서대로 사용됐는지 본다.
5. color 대비는 WCAG AA 이상인지 확인한다.
6. 키보드만으로 모든 인터랙션이 가능한지 점검한다.

두 스킬은 같은 "품질 점검" 주제지만, 환경에 따라 절차가 완전히 다르다.

5. Claude Code에 설치

저장 경로

범위	경로
프로젝트 전용	`.claude/skills/스킬명/`
개인 전역	`~/.claude/skills/스킬명/`

프로젝트 스킬은 Git에 커밋하면 팀원과 공유된다.

새로 만들기

mkdir -p .claude/skills/api-hook
touch .claude/skills/api-hook/SKILL.md

SKILL.md 내용을 채우면 바로 인식된다. Claude Code는 파일 변경을 감지해 세션 중에도 반영한다.

.skill 파일로 배포된 스킬 설치

cp code-quality.skill code-quality.zip
unzip code-quality.zip -d .claude/skills/code-quality

스킬 목록 확인

Claude Code에서 슬래시 커맨드 입력창에 /를 쳤을 때 스킬 이름이 뜨면 정상 인식된 것이다.

트리거 방식

사용자 요청과 description이 매칭되면 자동으로 로드된다. 명시적으로 부르고 싶다면 슬래시 커맨드로 호출한다.

/api-hook

6. Gemini CLI에 설치

저장 경로

범위	경로
프로젝트 전용	`.gemini/skills/스킬명/`
개인 전역	`~/.gemini/skills/스킬명/`

SKILL.md 형식은 Claude Code와 완전히 동일하다. 같은 파일을 폴더만 바꿔서 쓸 수 있다.

새로 만들기

mkdir -p .gemini/skills/api-hook
touch .gemini/skills/api-hook/SKILL.md

Claude Code 스킬을 Gemini CLI로 옮기기

cp -r .claude/skills/api-hook .gemini/skills/api-hook

스킬 목록 확인

gemini

세션이 뜨면 입력창에 아래 명령어를 친다.

/skills

사용 가능한 스킬 목록이 표시된다.

트리거 방식 — Claude Code와의 차이

Gemini CLI는 한 단계 더 있다. 스킬이 매칭되면 사용자에게 확인 프롬프트를 띄운다. 사용자가 승인하면 그때 SKILL.md 본문이 로드된다.

[ Activate skill: api-hook? ]
  Purpose: TMDB 같은 외부 API용 커스텀 훅 작성
  Directory: .gemini/skills/api-hook/
  [Y/n]

7. 양쪽 도구에 동시 적용 — 심볼릭 링크

같은 스킬을 Claude Code와 Gemini CLI 양쪽에서 유지보수하려면, 한쪽을 원본으로 두고 다른 쪽을 심볼릭 링크로 건다.

# Claude Code를 원본으로
ln -s ../../../.claude/skills/api-hook .gemini/skills/api-hook

New-Item -ItemType SymbolicLink `
  -Path ".gemini\skills\api-hook" `
  -Target "..\..\..\.claude\skills\api-hook"

한쪽만 수정하면 양쪽에 반영된다.

스킬파일링크

https://drive.google.com/file/d/1Kna3bzBw1X5nIY9w24KAeXtzhVcHsD9e/view?usp=drive_link

AI 코딩 에이전트 스킬 사용법

코드 블록의 Try it Yourself 버튼으로 직접 실행할 수 있다.

구문

AI 코딩 에이전트 스킬 사용법

1. 스킬이 필요한 이유

컨텍스트 파일과의 차이

구분	컨텍스트 파일 (CLAUDE.md / GEMINI.md)	스킬 (SKILL.md)
로드 시점	세션 시작 시 항상 로드	관련 요청 감지 시에만 로드
용도	프로젝트 전반의 배경 지식	특정 작업의 상세 절차
크기 관리	커지면 토큰 낭비	수십 개 있어도 부담 없음
비유	신입사원에게 주는 회사 소개서	특정 업무 매뉴얼

규칙이 많아질수록 컨텍스트 파일은 무거워진다. 이때 스킬로 쪼개면 필요한 순간에만 불러온다.

2. SKILL.md 기본 구조

최소 구성

my-skill/
└── SKILL.md

확장 구성

my-skill/
├── SKILL.md              ← 필수
├── scripts/              ← 에이전트가 실행할 코드
├── references/           ← 필요 시 읽는 참조 문서
└── assets/               ← 템플릿, 폰트, 아이콘 등

SKILL.md 작성 형식

---
name: skill-name
description: 이 스킬이 무엇을 하고 언제 트리거되는지 설명
---

# 스킬 본문

에이전트가 따라야 할 절차와 규칙을 작성한다.

프론트매터의 필수 필드는 두 개뿐이다.

필드	제한	설명
`name`	64자	스킬 식별자
`description`	200자	트리거 판단 기준. 에이전트가 이 문장으로 매칭한다

3. 환경 분석 — AI에게 먼저 물어본다

작성을 시작하기 전에, 에이전트에게 현재 프로젝트를 분석시킨다.

분석 프롬프트 템플릿

이 프로젝트의 기술 스택, 폴더 구조, 네이밍 컨벤션,
자주 반복되는 작업 패턴을 분석해줘.
결과를 다음 형식으로 정리해줘.

1. 기술 스택
2. 폴더 구조
3. 네이밍 규칙 (파일명, 컴포넌트명, 변수명)
4. 포맷팅/린트 설정
5. 반복 작업 후보 (스킬로 만들면 좋을 작업)

에이전트는 package.json, tsconfig.json, 폴더 구조, 기존 코드를 실제로 읽고 요약한다. 이 요약을 기반으로 스킬을 설계한다.

분석 결과 해석 예시

에이전트가 내놓을 응답의 형태는 프로젝트마다 다르다. 예시 두 가지를 비교한다.

응답 A — React 프로젝트

1. 기술 스택: React 19, Vite, Tailwind v4, React Router v7
2. 폴더 구조: src/components, src/pages, src/api
3. 네이밍: PascalCase.jsx 컴포넌트, camelCase 훅
4. 포맷팅: ESLint + Prettier, 세미콜론 없음
5. 반복 작업: API 훅 작성, 페이지 추가, 컴포넌트 분리

응답 B — HTML 정적 사이트

1. 기술 스택: HTML5, CSS3 (모던 기능), Vanilla JS
2. 폴더 구조: / 루트, /css, /js, /images
3. 네이밍: kebab-case.html, kebab-case.css
4. 포맷팅: Prettier만 사용
5. 반복 작업: 시맨틱 구조 확인, 접근성 점검, 반응형 작성

두 응답의 "반복 작업 후보"가 스킬 설계의 출발점이 된다.

4. 환경에 맞춘 스킬 작성

분석 결과를 에이전트에게 다시 넘기며 스킬 초안을 요청한다.

생성 프롬프트 템플릿

방금 분석한 환경에 맞춰서 다음 작업을 자동화하는
스킬을 작성해줘.

- 스킬 이름: [영문 kebab-case]
- 목적: [한 줄 설명]
- 트리거 키워드: [사용자가 쓸 법한 표현들]

SKILL.md 파일 하나로 완결되게 작성해줘.

에이전트는 앞서 분석한 환경 정보를 반영해서 SKILL.md 초안을 내놓는다.

응답 A 기반 스킬 예시

---
name: api-hook
description: >
  TMDB 같은 외부 API용 커스텀 훅을 작성하는 스킬.
  "API 훅 만들어줘", "useFetch 추가", "데이터 가져오는 훅"
  요청에 트리거된다.
---

# API 훅 작성 지침

1. 파일 위치: src/hooks/useXxx.js
2. 함수명: use + PascalCase
3. 반환값: { data, loading, error } 객체
4. 의존 배열에 쿼리 키 전부 포함
5. AbortController로 언마운트 시 요청 취소
6. 세미콜론 없이 작성

응답 B 기반 스킬 예시

---
name: a11y-check
description: >
  HTML 접근성 점검 스킬. "접근성 확인", "a11y",
  "시맨틱 검토", "스크린리더 대응" 요청에 트리거된다.
---

# 접근성 점검 지침

1. 이미지에 alt 속성이 있는지 확인한다.
2. 버튼과 링크를 구분한다 (button vs a).
3. 폼 요소에 label을 연결한다.
4. 헤딩 레벨(h1~h6)이 순서대로 사용됐는지 본다.
5. color 대비는 WCAG AA 이상인지 확인한다.
6. 키보드만으로 모든 인터랙션이 가능한지 점검한다.

두 스킬은 같은 "품질 점검" 주제지만, 환경에 따라 절차가 완전히 다르다.

5. Claude Code에 설치

저장 경로

범위	경로
프로젝트 전용	`.claude/skills/스킬명/`
개인 전역	`~/.claude/skills/스킬명/`

프로젝트 스킬은 Git에 커밋하면 팀원과 공유된다.

새로 만들기

mkdir -p .claude/skills/api-hook
touch .claude/skills/api-hook/SKILL.md

SKILL.md 내용을 채우면 바로 인식된다. Claude Code는 파일 변경을 감지해 세션 중에도 반영한다.

.skill 파일로 배포된 스킬 설치

cp code-quality.skill code-quality.zip
unzip code-quality.zip -d .claude/skills/code-quality

스킬 목록 확인

Claude Code에서 슬래시 커맨드 입력창에 /를 쳤을 때 스킬 이름이 뜨면 정상 인식된 것이다.

트리거 방식

사용자 요청과 description이 매칭되면 자동으로 로드된다. 명시적으로 부르고 싶다면 슬래시 커맨드로 호출한다.

/api-hook

6. Gemini CLI에 설치

저장 경로

범위	경로
프로젝트 전용	`.gemini/skills/스킬명/`
개인 전역	`~/.gemini/skills/스킬명/`

SKILL.md 형식은 Claude Code와 완전히 동일하다. 같은 파일을 폴더만 바꿔서 쓸 수 있다.

새로 만들기

mkdir -p .gemini/skills/api-hook
touch .gemini/skills/api-hook/SKILL.md

Claude Code 스킬을 Gemini CLI로 옮기기

cp -r .claude/skills/api-hook .gemini/skills/api-hook

스킬 목록 확인

gemini

세션이 뜨면 입력창에 아래 명령어를 친다.

/skills

사용 가능한 스킬 목록이 표시된다.

트리거 방식 — Claude Code와의 차이

Gemini CLI는 한 단계 더 있다. 스킬이 매칭되면 사용자에게 확인 프롬프트를 띄운다. 사용자가 승인하면 그때 SKILL.md 본문이 로드된다.

[ Activate skill: api-hook? ]
  Purpose: TMDB 같은 외부 API용 커스텀 훅 작성
  Directory: .gemini/skills/api-hook/
  [Y/n]

7. 양쪽 도구에 동시 적용 — 심볼릭 링크

같은 스킬을 Claude Code와 Gemini CLI 양쪽에서 유지보수하려면, 한쪽을 원본으로 두고 다른 쪽을 심볼릭 링크로 건다.

# Claude Code를 원본으로
ln -s ../../../.claude/skills/api-hook .gemini/skills/api-hook

New-Item -ItemType SymbolicLink `
  -Path ".gemini\skills\api-hook" `
  -Target "..\..\..\.claude\skills\api-hook"

한쪽만 수정하면 양쪽에 반영된다.

스킬파일링크

https://drive.google.com/file/d/1Kna3bzBw1X5nIY9w24KAeXtzhVcHsD9e/view?usp=drive_link