AI Skill 수기 가이드: Claude Code로 재사용 가능한 능력 모듈 만들기

「AI에게 똑같은 설명을 반복하고 있다」

기술 블로그를 쓸 때마다, 코드 리뷰를 요청할 때마다, 문서를 정리할 때마다——비슷한 지시를 반복하고 있지는 않은가. 「정중하게 써줘」, 「일본어로」, 「코드 블록을 잊지 마」. 이것들은 일시적인 프롬프트(Prompt)가 아니라, AI에게 정착시키고 싶은 「습관」이다.

Claude Code의 Skill은 이 「습관」을 모듈화하는 메커니즘이다. 한 번 작성해 두면, 다음부터는 이름만으로 호출할 수 있다. 하지만 여기서 많은 사람이 빠지는 함정이 있다. 바로 「지시」를 쓰는 것만으로 만족해 버리는 것이다.

「정중하게 써줘」는 원칙이다. Skill은 원칙을 쓰는 곳이 아니다. 절차를 쓰는 곳이다. 이 차이를 이해하지 못한 채 Skill을 만들면, AI는 동작하지 않는다. 동작하지 않으니 계속 사용하지 않게 된다. 계속 사용하지 않으니 존재조차 잊게 된다.

본 기사에서는 Claude Code에서 「동작하는 Skill」을 수기로 작성하는 방법을 해설한다. 처음 배우는 것이라면 직접 쓰는 것이 가장 빠르다. skill-creator라는 자동 생성 도구도 있지만, 처음에는 구조를 이해하기 위해 한 번쯤 직접 써보는 것을 추천한다.

항목	내용
명칭	Claude Code Skill
구성 요소	SKILL.md (필수) + scripts/ / references/ / assets/ (선택)
배치 장소	.claude/skills/skill-name/
호출 방법	/skill-name 또는 자연어로 자동 트리거
학습 비용	수기 작성: 처음에는 30분 정도. 이해 후에는 5분 내로 신규 생성 가능
대상 사용자	Claude Code 사용자 (CLI 환경에서 AI 에이전트를 이용하는 사용자)

Skill은 「마법의 프롬프트」가 아니다. 디렉토리에 정리된 파일군이다. 호출하는 측에서 /skill-name을 입력하기만 하면, Claude Code가 해당 디렉토리의 내용을 읽어 들여 그 태스크 전용 「모드」로 진입한다.

skill-name/
└── SKILL.md # 필수: 트리거 조건 + 실행 절차

skill-name/
├── SKILL.md # 필수: 트리거 조건 + 실행 절차
├── scripts/ # 선택: 재실행 가능한 스크립트
...

파일/폴더	역할	예시
SKILL.md	트리거 조건(언제 발동할지)과 실행 절차(무엇을 할지)를 정의	「사용자가 기술 기사를 쓰려고 할 경우, 이 Skill을 제안」
scripts/	재실행 가능한 쉘 스크립트(Shell Script)나 Python 코드	setup.sh: 프로젝트 초기화, validate.py: 출력 체크
references/	긴 가이드라인이나 사양서	코딩 규약, API 사양, 포맷 요구사항
assets/	템플릿이나 이미지 리소스	기사 템플릿, 도표 샘플

SKILL.md만으로도 동작한다. 다만 내용이 길어지면 읽어 들이는 것이 무거워지므로, 적절히 분할하는 것이 바람직하다.

SKILL.md는 YAML의 frontmatter와 실행 절차 본문으로 구성된다.

---
name: tech-blog-writer
description: "기술 블로그 기사를 작성·편집한다. Zenn/Qiita 형식에 대응."
...

항목	필수 여부	설명
name	✅	Skill을 호출할 때의 식별자. 디렉토리명과 일치시켜야 함
description	✅	여기가 트리거의 핵심. 자연어로 Skill이 자동 발동되는 판정 기준이 됨

description이 부적절하면 Skill은 호출되지 않는다. 범위가 너무 넓으면 오작동하고, 너무 좁으면 발동하지 않는다.

description: "기사를 쓴다" # 너무 넓음. 어떤 기사?
description: "Zenn 기사 중, 제목이 20자 이상일 경우 카테고리가 tech라면..." # 너무 좁음

description: "기술 블로그 기사를 작성·편집한다. Zenn/Qiita 형식에 대응."
description: "PR 리뷰 요청 메시지를 생성한다. 일본어·경어체로 통일."

Skill은 「AI를 위한 지시서」이지만, 추상적인 지시는 기능하지 않는다.

실행 절차

1. 기사를 정중하게 작성해 주세요
2. 코드 블록을 적절하게 사용해 주세요
   ...

「정중하게」, 「적절하게」, 「배려」——AI는 이를 해석할 수 없다. 인간이라면 문맥으로 보완할 수 있지만, AI에게는 「어떻게?」라는 의문이 남는다.

## 실행 절차
1. 헤딩 구조를 확인한다 (H1은 기사 제목만, H2 이하는 절)
2. 코드 블록에는 언어 지정(Language specification)을 붙인다 (```python 등)
3. 전문 용어의 첫 등장 시에는 괄호로 영어 표기를 병기한다
4. 각 절의 끝에 「요약」을 두지 않는다 (마지막에 전체 요약을 하나만 작성)
5. 공개 전에 링크 깨짐을 확인한다

구체적이고, 검증 가능하며, AI가 기계적으로 실행할 수 있는 절차. 이것이 Skill을 작동시키는 열쇠다.

...

## 금지 사항
- 허구의 데이터나 케이스 스터디를 만들지 않는다
- 출처가 없는 통계나 숫자를 사용하지 않는다
- 「~라고 할 수 있습니다」, 「~라고 생각됩니다」 등의 모호한 표현을 사용하지 않는다
- 사용자가 제공하지 않은 정보를 보완하지 않는다

금지 사항은, AI가 저지르기 쉬운 행동을 나열한다. Claude Code 사용자라면 「멋대로 파일을 수정했다」거나 「허구의 API 엔드포인트를 날조했다」와 같은 경험이 있을 것이다. 이를 방지하는 것이 금지 사항 섹션이다.

...

mkdir -p .claude/skills/tech-blog-writer
cd .claude/skills/tech-blog-writer

---
name: tech-blog-writer
description: "기술 블로그 기사를 작성·편집한다. Zenn/Qiita 형식에 대응."
---

## 트리거 조건
사용자가 다음과 같은 발언을 했을 경우 발동:
- 「기사를 쓰고 싶어」, 「블로그 써줘」
- 「Zenn에 게시할 거야」, 「Qiita 기사」
- 「기술 기사 템플릿」
## 실행 절차
1. 기사의 테마를 사용자에게 확인한다
2. 다음 구조로 드래프트(Draft)를 작성한다:
- 제목 (H1)
- 서론 (200자 정도)
- 본문 (H2 섹션 여러 개)
- 요약 (300자 정도)
3. 코드 블록에는 언어 지정을 붙인다
4. 전문 용어의 첫 등장 시에는 영어 표기를 괄호로 병기한다
5. 링크 깨짐을 확인한 후 완성한다
## 금지 사항
- 허구의 데이터나 케이스를 만들지 않는다
- 출처가 없는 통계를 사용하지 않는다
- 사용자가 제공하지 않은 정보를 보완하지 않는다

Claude Code에서 다음과 같이 입력:

기술 기사를 쓰고 싶어. 테마는 「Docker 입문」.

description

...

tech-blog-writer/
├── SKILL.md
└── references/
├── zenn-format.md # Zenn 고유의 포맷 요구사항
└── qiita-format.md # Qiita 고유의 포맷 요구사항

Skill은 AI에게 「습관」을 정착시키는 메커니즘이다. 하지만, 원칙을 써도 작동하지 않는다. 「정중하게」, 「적절하게」는 인간을 향한 지시다. AI에게 전달하는 것은 기계적으로 실행 가능한 절차다.

이 글의 요점:

항목	내용
Skill의 정체	디렉토리에 정리된 파일군
필수 파일	SKILL.md (frontmatter + 실행 절차)
트리거의 열쇠	description (너무 넓지도 좁지도 않게)
절차 작성법	구체적·검증 가능·금지 사항을 포함할 것
초보자 추천	한 번 직접 손으로 써보며 구조를 이해할 것

한 번 작성한 Skill은 다음부터 /skill-name만으로 호출할 수 있다. AI에게 같은 설명을 몇 번이고 반복하고 있다고 느껴진다면, Skill을 작성해 보자. 30분의 투자가 향후 몇 시간을 절약해 줄 것이다.

Claude Code로 Skill을 작성해 본 적이 있나요? 어떤 태스크를 Skill로 만드셨나요? 댓글로 알려주세요.