Skill 직접 만들기

Skill이란?

Skill은 특정 작업이 발생할 때 Claude가 자동으로 참조하는 마크다운 파일입니다. 본문에 절차·규칙·점검 항목을 적어두면 Claude가 그 절차대로 작업합니다.

코드 실행이 필요한 워크플로는 Plugin, 단순한 절차·규칙 표준화는 Skill이 적합합니다.

파일 구조

~/.claude/skills/<skill-name>/
├── SKILL.md          # 필수 — frontmatter + 본문
└── (보조 파일)        # 선택 — 참고 자료, 템플릿 등

SKILL.md 기본 형식

---
name: <skill-name>
description: <Claude가 이 Skill을 호출할 조건을 구체적으로 명시>
---

# Skill 제목

## 언제 사용하나
이 Skill이 호출되어야 하는 상황 명시.

## 절차
1. 첫 단계
2. 두 번째 단계
3. ...

## 점검 항목
- [ ] 항목 1
- [ ] 항목 2

description의 중요성

description은 Claude가 Skill을 호출할지 결정하는 핵심 신호입니다. 좋은 description의 특징:

• 트리거 조건 명시 — “X 작업 시”, “Y 파일을 다룰 때”
• 기능명·키워드 포함 — 사용자가 실제로 쓸 표현
• 부정 조건도 명시 (선택) — “단, Z인 경우는 제외”

좋은 예

description: |
  Use when creating or modifying SQL migration files in db/migrations/.
  Enforces naming convention (timestamp_description.sql), reversibility,
  and schema review checklist. Skip for read-only queries.

나쁜 예

description: Database stuff  # 너무 일반적, 호출 조건 불명확

본문 작성 원칙

1. 절차는 번호 매겨 명시

Claude는 번호 매겨진 절차를 더 정확히 따릅니다.

2. 금지 사항은 굵게

**절대 하지 말 것**:
- 마이그레이션 파일을 직접 삭제
- ALTER TABLE 없이 컬럼 변경

3. 검증 단계 포함

## 검증
- 마이그레이션 적용 후 `npm test`
- 롤백 테스트: `npm run db:rollback && npm run db:migrate`

4. 외부 링크는 절대 경로

본문에 다른 Skill이나 문서를 참조할 때 명확히 표시합니다.

실전 예: 콘텐츠 검토 Skill

---
name: review-content
description: |
  Use when reviewing or modifying content files in src/content/.
  Checks frontmatter schema, ko/en pair consistency, link validity,
  and applies the project quality rules.
---

# Content Review

## 실행 시점
- 콘텐츠 파일을 생성·수정한 후
- 배포 전 최종 검토

## 절차
1. frontmatter 스키마 위반 확인
2. ko/en 페어 정합성 (slug, dates 동일)
3. 외부 링크 유효성
4. 본문 톤 일관성

## 검증
\```bash
npm run build
\```

사용자 단위 vs 플러그인 단위

위치	적용 범위	배포
~/.claude/skills/<name>/SKILL.md	본인만	수동
플러그인 내 skills/<name>/SKILL.md	플러그인 사용자 전체	마켓플레이스

팀이나 공개 배포가 필요하면 플러그인으로 묶어 마켓플레이스에 등록합니다.

흔한 실수

• ❌ description이 너무 짧음 — Claude가 트리거 못함
• ❌ 본문이 산문(에세이) 스타일 — 절차로 분리 필요
• ❌ 너무 광범위한 Skill — 한 Skill = 한 절차 원칙
• ❌ 다른 Skill과 트리거 조건 충돌 — 명확히 구분

다음 단계

• Superpowers 내장 Skills를 코드로 직접 읽어 구조 학습
• Obsidian Skills — 잘 설계된 Skill 모음 사례
• CLAUDE.md 잘 쓰는 법 — Skill과 CLAUDE.md의 역할 분리