작성 전 준비Skill 작성기본 구조frontmatter 필드실전 예시: 커밋 도우미 Skilldescription 작성 팁Subagent 작성파일 구조frontmatter 필드실전 예시: 코드 리뷰어 에이전트실전 예시: 읽기 전용 탐색 에이전트호출 테스트흔한 실수와 해결마무리
aiclaude-codeagentskill

Claude Code Skill / Agent 직접 작성하기

· 읽기 10분

작성 전 준비

Skill과 Subagent 모두 Markdown 파일 + YAML frontmatter 조합입니다. 별도의 빌드나 컴파일이 없어 에디터에서 저장만 하면 다음 세션부터 Claude Code가 인식합니다.

저장 위치는 두 스코프로 나뉩니다.

스코프SkillSubagent
사용자 전역~/.claude/skills/{name}/SKILL.md~/.claude/agents/{name}.md
프로젝트.claude/skills/{name}/SKILL.md.claude/agents/{name}.md

프로젝트 스코프는 Git에 커밋되어 팀원과 공유됩니다.

Skill 작성

기본 구조

Skill은 디렉터리로 관리됩니다. 폴더 이름이 Skill 이름이 되며 내부에 SKILL.md가 있어야 합니다.

.claude/skills/commit-helper/
├── SKILL.md          # 필수: 지시문
├── templates/        # 선택: 참고 템플릿
│   └── message.txt
└── scripts/          # 선택: 실행 스크립트
    └── build.sh

frontmatter 필드

---
name: commit-helper               # 필수: 소문자·하이픈, 최대 64자
description: >                    # 필수: 3인칭, 언제 쓰는지 명확히
  Conventional Commits 규칙에 맞춰 커밋 메시지를 작성합니다.
  사용자가 변경 내용을 커밋하려 할 때 호출됩니다.
allowed-tools: ["Read", "Bash"]   # 선택: 도구 제한
license: "MIT"                    # 선택
---
필드필수설명
name✅슬래시 커맨드로 호출되는 이름 (/commit-helper)
description✅자동 호출의 정확도를 좌우하는 가장 중요한 필드
allowed-tools❌비워 두면 부모 세션 도구 전체 사용
license / compatibility❌배포 시 메타데이터

실전 예시: 커밋 도우미 Skill

---
name: commit-helper
description: >
  Conventional Commits 형식으로 커밋 메시지를 작성합니다.
  사용자가 "커밋해줘" 또는 /commit-helper 로 호출합니다.
allowed-tools: ["Bash"]
---

# Commit Helper

## 절차

1. `git status --short` 로 변경 파일 확인
2. `git diff --staged` 로 스테이지된 변경 확인
3. 변경 규모에 따라 타입 결정:
   - 새 기능 → `feat`
   - 버그 수정 → `fix`
   - 리팩토링 → `refactor`
   - 문서만 변경 → `docs`
4. 50자 이내 한 줄 요약 + 선택적 본문 작성
5. `git commit -m "..."` 실행

## 형식

```
<type>(<scope>): <요약>

<본문 - 선택>
```

## 주의

- 여러 타입이 섞이면 커밋을 분리하도록 제안
- 시크릿이 포함된 파일은 커밋하지 말고 사용자에게 경고

description 작성 팁

description은 Claude가 Skill을 자동 호출할지 판단하는 유일한 근거입니다. 다음 원칙을 따릅니다.

나쁜 예좋은 예
”커밋 관련""사용자가 변경 내용을 커밋하려 할 때 Conventional Commits 규칙으로 메시지를 작성합니다"
"테스트""Jest 기반 유닛 테스트를 작성하고 커버리지 80% 이상을 유지합니다"
"코드 리뷰""방금 작성한 코드를 보안·가독성 관점에서 점검합니다. 코드 수정 직후 자동 호출됩니다”

나쁜 예는 너무 짧아 언제 써야 하는지 정보가 없습니다.

Subagent 작성

파일 구조

Subagent는 단일 .md 파일입니다. 디렉터리가 아닙니다.

.claude/agents/
├── code-reviewer.md
├── security-auditor.md
└── test-writer.md

frontmatter 필드

---
name: code-reviewer               # 필수
description: >                    # 필수
  방금 변경된 코드를 품질·보안 관점에서 리뷰합니다.
  코드 수정 후 즉시 사용하세요.
tools: Read, Grep, Glob, Bash     # 선택: 사용 가능 도구 (쉼표 구분)
model: sonnet                     # 선택: haiku | sonnet | opus | inherit
---
필드필수설명
name✅에이전트 식별자, 호출 시 사용
description✅자동 호출 판단 근거
tools❌생략 시 부모 세션 도구 전체 상속. 쉼표 구분으로 제한 가능
model❌생략 시 부모 모델 상속

model 선택 가이드는 이렇습니다.

모델언제
haiku단순 조회·요약 (빠르고 저렴)
sonnet일반 코드 작업 (균형)
opus복잡한 설계·디버깅 (깊은 추론)
inherit부모 세션과 동일 모델

실전 예시: 코드 리뷰어 에이전트

---
name: code-reviewer
description: >
  코드 변경 직후 호출되는 코드 리뷰어. 보안, 가독성, 성능, 테스트
  커버리지를 점검하여 CRITICAL/HIGH/MEDIUM/LOW로 분류하여 보고합니다.
tools: Read, Grep, Glob, Bash
model: sonnet
---

# Code Reviewer

당신은 10년 경력의 시니어 개발자입니다. 방금 변경된 코드를
점검하고 이슈를 레벨별로 정리하여 보고합니다.

## 리뷰 체크리스트

### CRITICAL
- 하드코딩된 시크릿, API 키
- SQL 인젝션, XSS, 명령어 인젝션
- 인증·인가 누락

### HIGH
- 에러 핸들링 누락 (빈 catch 등)
- 리소스 누수 (파일/DB 연결 미해제)
- 무한 루프 가능성

### MEDIUM
- 긴 함수 (50줄 초과)
- 깊은 중첩 (4레벨 초과)
- 매직 넘버

### LOW
- 네이밍 일관성
- 주석 품질

## 출력 형식

파일:줄번호 형식으로 이슈 위치를 명확히 표기합니다.
발견 이슈가 없으면 "이슈 없음"으로 짧게 보고합니다.

실전 예시: 읽기 전용 탐색 에이전트

---
name: explorer
description: >
  코드베이스 탐색 전용 에이전트. 파일 구조·의존성·주요 엔드포인트를
  파악하여 요약만 반환합니다. 쓰기 권한 없음.
tools: Read, Grep, Glob
model: haiku
---

# Explorer

## 임무

1. 프로젝트 루트부터 디렉터리 트리 파악
2. 패키지 매니저 파일(package.json / requirements.txt 등)로 의존성 확인
3. 주요 진입점 (main, index, app 등) 식별
4. 200단어 이내 요약 반환

## 제약

- 파일 수정 금지 (tools에 Write/Edit 없음)
- 3분 이내 완료를 목표

Haiku 모델 + 읽기 도구만으로 빠르고 저렴하게 탐색합니다.

호출 테스트

작성이 끝나면 Claude Code를 재시작한 뒤 확인합니다.

# Claude Code CLI 안에서
/commit-helper                    # Skill 직접 호출

# 또는 자연어로 자동 호출 유도
"방금 바꾼 파일들 커밋 메시지 만들어줘"

에이전트는 Claude에게 “code-reviewer 에이전트로 리뷰해줘” 같은 자연어 지시로 호출하거나, Claude가 description 매칭으로 자동 호출합니다.

흔한 실수와 해결

실수해결
description이 “도움 도구”처럼 모호”~할 때 호출됩니다” 구체적 조건 포함
에이전트 tools에서 필요한 도구 누락작업 흐름을 따라가며 필요한 도구 모두 나열
Skill을 프로젝트에 두고 커밋 누락.claude/skills/를 .gitignore에 넣지 말 것
같은 이름의 Skill이 전역/프로젝트에 중복스코프 우선순위(Enterprise/Personal/Project)를 확인하고 의도에 맞게 정리

마무리

Skill과 Subagent 작성은 결국 명확한 description 과 적절한 권한 경계의 문제입니다. 규칙을 책처럼 만들 것이냐, 동료에게 맡길 것이냐를 먼저 정하고, allowed-tools 또는 tools로 필요한 최소 권한만 주는 것이 실전 팁입니다. 팀 단위로 .claude/ 디렉터리를 리포지토리에 커밋하면 모든 팀원이 같은 AI 보조자를 공유하게 됩니다.

이 글이 도움이 되었나요?