스킬 최적화 설계¶

한 줄 정의¶

스킬을 만들기 쉽고, 관리하기 쉽고, 재활용하기 쉽게 설계하는 방법.

비유¶

프랜차이즈 매뉴얼 시스템. 각 매장(스킬)마다 따로 매뉴얼을 만들지 않고, 본사 공통 매뉴얼(공통 모듈)을 두고 매장별 특화 매뉴얼만 추가하는 방식.

1. 통합 폴더 구조¶

모든 스킬을 한 폴더에 모아 관리한다.

C:\Projects\my-skills\                ← 스킬 본사
├── .claude-plugin\
│   └── marketplace.json              ← 등록부 (1개)
├── _shared\                          ← 공통 매뉴얼
│   ├── notion-upload.md
│   ├── seo-rules.md
│   └── instagram-post.md
├── lecture-content\SKILL.md          ← 매장 A
├── youtube-ppt\SKILL.md             ← 매장 B
├── youtube-content\SKILL.md         ← 매장 C (예정)
└── README.md

왜 이 구조가 좋은가¶

비교 항목	개별 등록 (예전)	통합 관리 (지금)
새 스킬 추가	5개 파일 수정	SKILL.md + marketplace.json 1줄
스킬 찾기	여러 프로젝트 돌아다님	`my-skills` 하나만 봄
공통 규칙 수정	스킬마다 일일이 수정	`_shared/` 한 곳만 수정
Junction 링크	스킬마다 1개씩	전체 통틀어 1개
백업	폴더마다 따로	폴더 1개만

2. 공통 모듈 (`_shared/`) 패턴¶

개념¶

여러 스킬에서 반복되는 규칙을 별도 파일로 분리한 것. SKILL.md에서 "이 파일을 참조하라"고 적으면 Claude가 해당 파일을 읽고 따른다.

현재 공통 모듈¶

파일	내용	사용하는 스킬
`notion-upload.md`	노션 MCP 업로드 규칙 (DB ID, 속성, 참조 글)	lecture-content, (향후) youtube-content
`seo-rules.md`	SEO 규칙 (메타태그, 파일명, alt text)	lecture-content, (향후) 모든 글쓰기 스킬
`instagram-post.md`	인스타 포스팅 문구 규칙	lecture-content, (향후) youtube-content

SKILL.md에서 참조하는 방법¶

## 공통 참조
- SEO 규칙: `_shared/seo-rules.md` 참조
- 노션 업로드 규칙: `_shared/notion-upload.md` 참조

언제 공통 모듈로 분리하는가¶

"이 규칙이 다른 스킬에서도 쓰일까?"
  ├─ YES → _shared/로 분리
  └─ NO  → SKILL.md에 직접 작성

예시: - 노션 업로드 절차 → 강의, 유튜브, 책 등 여러 스킬에서 사용 → 분리 - 강의 사진 선별 기준 → 강의 스킬에서만 사용 → SKILL.md에 직접 - PPT 디자인 스펙 → youtube-ppt에서만 사용 → references/ 폴더에

3. SKILL.md 잘 쓰는 법¶

기본 원칙¶

단계별로 번호 매기기 — Claude가 순서대로 따라감
결과물 형식 명시 — "500~800자", "파일명.md로 저장" 등
판단 기준 제시 — "5장을 선별하되, 비슷한 구도는 1장만"
사용자 확인 시점 명시 — "3단계 완료 후 사용자에게 수정 여부 확인"
공통 모듈 참조 — 중복 내용은 _shared/ 참조

구조 템플릿¶

---
name: 스킬-이름
description: >
  어떤 상황에서 이 스킬을 실행해야 하는지 설명.
  "이런 말", "저런 말" 등의 요청에 사용.
argument-hint: "[입력 힌트]"
---

# 스킬 제목

## 공통 참조
- (필요한 공통 모듈 나열)

## 개요
(전체 흐름 한 줄 요약)

## 입력
(사용자가 제공하는 정보)

## 1단계: ...
(상세 지시)

## 2단계: ...

## 완료 보고
(결과물 형식)

SKILL.md vs references/ vs _shared/ 구분¶

어디에 넣나	기준	예시
SKILL.md 본문	이 스킬의 핵심 워크플로우	사진 선별 기준, 글 구성 순서
references/	이 스킬에만 쓰이는 참조 문서	PPT 디자인 스펙, 슬라이드 패턴
_shared/	여러 스킬이 공유하는 규칙	노션 업로드, SEO, 인스타 규칙

4. 새 스킬 추가 절차 (3단계)¶

1단계: 스킬 폴더 + SKILL.md 생성¶

C:\Projects\my-skills\새스킬이름\
└── SKILL.md

2단계: marketplace.json에 1줄 추가¶

"skills": [
  "./lecture-content",
  "./youtube-ppt",
  "./새스킬이름"          ← 이 줄만 추가
]

3단계: Claude Code 재시작¶

끝. Junction 링크, 레지스트리 수정 등은 이미 통합 등록이 되어 있으므로 필요 없다.

5. 실전에서 배운 팁¶

이미지 플레이스홀더¶

노션 MCP로는 이미지를 직접 업로드할 수 없다. [이미지N: 파일명.jpg] 텍스트를 본문에 넣고, 사용자가 노션에서 드래그앤드롭한다.

사용자 편집 단계¶

글을 .md 파일로 저장해서 사용자가 직접 편집할 수 있게 하면, 수정 요청을 주고받는 것보다 훨씬 빠르다.

ogImage¶

우피(Oopy) 플랫폼에서 og:image 메타태그가 외부 크롤러에 전달되지 않는 문제가 있다. 현재로서는 ogImage를 빈 값(" ")으로 두는 것이 현실적.

Windows 한글 파일명¶

bash cp 명령이 한글 파일명에서 실패할 수 있다. PowerShell Copy-Item을 사용하면 해결된다.

참고¶

스킬 기본 개념: 01-skill.md
스킬 통합 폴더: C:\Projects\my-skills\
스킬 목록/사용법: C:\Projects\my-skills\README.md
글로벌 CLAUDE.md의 "커스텀 스킬 통합 관리" 섹션