.claude/
└── skills/
└── <스킬명>/ ← 이곳을 신규 생성
...

---
name: <스킬명>
description: <Claude Code가 "언제 호출할지"를 판단하는 설명문>
...

---
name: zenn-article-generator
description: Zenn 기사 생성 지시서를 작성한다. "Zenn 기사를 써줘", "기사 생성 지시서를 만들어줘", "Series C 기사를 작성해줘", "다음 기사의 지시서를 만들어줘"라고 말하면 반드시 사용한다.
...

- 사용 가능 문자: 반각 영숫자(a-z0-9)・하이픈(-)・언더스코어(_)
- 글자 수: 12~50자
- 대문자 금지
...
```markdown
# Zenn 기사 생성 지시서: <시리즈><번호>
> 대상자: Claude Code
> 작업 리포지토리 (Repository): <article-repo>
> 작업 폴더 (Workdir): <workdir>
## 목적
## 참조할 파일 (agent01 리포지토리)
## 작업 내용
### 1. 기사 파일 신규 생성
### 2. 프런트매터 (Frontmatter) 설정
### 3. 기사의 구성
## 완료 조건
## 커밋 (Commit)

## 시리즈 링크 (Series C)
| 기사 | 제목 |
|---|---|
| C1 | [SKILL이란 무엇인가](https://zenn.dev/pekopugu/articles/agent01-c1-skill-intro) |
| ... |

시리즈 구성·슬러그 (Slug) 규칙·공통 규칙을 SKILL.md 내에서 일원 관리함으로써, Claude Code가 매번 동일한 품질의 지시서를 생성할 수 있게 되었습니다. 기사마다 개별적인 지시서를 만드는 수고는 남지만, 골격이 되는 포맷은 SKILL이 보유하고 있기 때문에 지시서 작성 비용을 대폭 절감할 수 있습니다.

## 막혔던 점·깨달은 점

파일을 두기만 해도 인식되지만, 설명(description)이 모호하면 Claude Code는 호출 여부를 판단할 수 없습니다. "무엇을 하는 스킬인가"뿐만 아니라 "어떤 말로 불렸을 때 동작하는가"를 description에 명시하는 것이 중요합니다. 또한 SKILL.md의 본문은 마크다운 (Markdown)으로 작성할 수 있으므로, 표·코드 블록·리스트를 활용하면 지시를 전달하기 쉬워집니다.

스킬 이름(디렉토리 이름)은 하이픈으로 구분된 반각 영숫자를 권장합니다. 공백이나 일본어는 트러블의 원인이 됩니다. CLAUDE.md와 SKILL.md의 용도 구분(상시 적용 vs 호출형)은 처음에 정리해 두어야 혼란을 방지할 수 있습니다. 이번 `zenn-article-generator`는 "명시적으로 호출하는 태스크 전용 지시서"이므로 SKILL.md에 작성하였고, 프로젝트 전체의 금지 사항이나 코딩 규약은 CLAUDE.md에 작성했습니다.

**claude.ai로의 설치는 Plugin validation failed로 실패함**

claude.ai의 Settings > Capabilities > Skills에서 zip 파일을 업로드하여 설치를 시도했으나, "Plugin validation failed."라는 에러가 반복해서 표시되었습니다. SKILL.md의 내용·글자 수·zip 구조를 변경해도 해결되지 않았습니다. 최소 구성(3줄의 SKILL.md)에서도 동일한 에러가 발생했기 때문에, SKILL.md의 내용보다는 이쪽의 구성이나 절차에서 기인한 문제일 가능성을 먼저 의sus했습니다.

GitHub의 issue에도 유사한 보고가 있어, 동일한 에러가 다른 요인으로 발생할 가능성도 있습니다. claude.ai로 설치를 시도할 경우에는 zip 구조와 파일 내용, 절차의 재검토를 포함하여 원인을 분리해 나갈 필요가 있습니다. 이번에는 원인 특정과 해결에 이르지 못하여, claude.ai로의 설치는 여기서 단념했습니다. 참고로, Claude Code로의 설치(`.claude/skills/`에 배치하는 방법)에서는 정상적으로 동작함을 확인했습니다.

## 요약

SKILL 설치는 "디렉토리를 만들고 SKILL.md를 두기만 하면" 됩니다. 특별한 설정이나 커맨드는 필요 없으며, 파일을 저장하는 순간부터 Claude Code가 인식합니다.

다만, description(설명)의 질이 SKILL의 사용 편의성을 결정합니다. 트리거 문구(trigger phrase)를 구체적으로 나열하고, "반드시 사용"과 같은 강한 표현을 넣어두는 것이 실용적인 포인트입니다.

다음 회차(C3)에서는 CLAUDE.md를 육성하여 Claude Code의 프로젝트 전체 동작을 커스터마이징(customizing)하는 방법을 해설합니다.

## 시리즈 링크 (Series C)

| 기사 | 제목 |
|---|---|
| C1 | SKILL.md란 무엇인가 · 구조를 이해하기 |
| ... |
### Discussion

![](https://static.zenn.studio/images/drawing/discussion.png)