Claude Code에는 「스킬 (Skill)」이라는 메커니즘이 있습니다. ~/.claude/skills/<name>/SKILL.md에 방법을 적은 폴더를 두면, Claude가 내용을 읽고 적절한 상황에서 알아서 발동해 주는—매주 같은 절차를 다시 설명할 필요가 없게 만드는 기능입니다.

저는 지난 반년 동안 저의 주간 운영(다이제스트 생성, 수신함 정리, KPI 기록, 정기 보고서…)을 전부 스킬로 구현하여 운영해 왔습니다. 10개를 작성하여 운영해 보니, 「작동하는 스킬」과 「3주 후에 고장 나는 스킬」의 차이가 명확하게 보이기 시작했습니다. 이 기사는 그 설계 패턴의 정리입니다. 마지막에 실제 사례 1개를 전문 그대로 첨부합니다.

스킬의 최소 구조

~/.claude/skills/
folder-tidy/
SKILL.md # 이것만 있어도 작동함
...

SKILL.md는 frontmatter + 본문 Markdown으로 구성됩니다:

---
name: folder-tidy
description: Organize a cluttered macOS folder ... Use when the user says "tidy my desktop", "organize downloads", ...
...

여기서부터 10개를 작성하며 정립된 4가지 패턴을 설명하겠습니다.

패턴 1: description이 전부다 (트리거 설계)

스킬이 발동할지 여부는 거의 frontmatter의 description에 의해 결정됩니다. Claude는 기동 시 스킬 목록의 description을 읽고, 사용자의 발화와 매칭하여 발동 여부를 판단하기 때문입니다. 본문이 아무리 친절해도 description이 모호하면 평생 호출되지 않습니다.

고장 나는 작성법:

description: 폴더를 정리하는 스킬

작동하는 작성법:

description: Organize a cluttered macOS folder (Desktop, Downloads) by file type
into subfolders, moving leftovers to Trash rather than hard-deleting.
Use when the user says "tidy my desktop", "organize downloads",
...

포인트는 두 가지입니다:

• 무엇을 하는가뿐만 아니라, 사용자가 어떻게 말했을 때 사용하는가(발화 예시)를 열거합니다. 「정리해 줘」, 「어질러져 있어」와 같은 모호한 표현일수록 적을 가치가 있습니다.
• 혼동하기 쉬운 유사한 스킬이 있다면 「~의 경우에는 사용하지 않는다」도 적습니다 (오발동은 발동하지 않는 것만큼이나 중요합니다).

패턴 2: CONFIGURE 블록으로 하드코딩을 격리한다

초기에는 경로(Path)나 토큰 이름을 본문의 절차에 직접 적었습니다. 이것이 3주 후에 고장 나는 전형적인 원인입니다. 폴더를 이동했거나 DB를 변경했을 때, 절차의 어느 부분을 수정해야 할지 스스로도 알 수 없게 됩니다.

지금은 모든 스킬에 ## CONFIGURE 섹션을 두어, 환경 의존적인 값을 그곳에 집약하고 있습니다:

## CONFIGURE

TARGET = "~/Downloads"
ROUTES = { Images: [jpg,png,gif,heic], Docs: [pdf,docx,xlsx,md],
Archives: [zip,tar,gz], Installers: [dmg,pkg] }
TRASH_JUNK = true
CONFIRM_BEFORE_MOVE = true

본문의 절차는 「## CONFIGURE의 TARGET을 읽어라」라고만 적습니다. 이렇게 하면:

• 환경이 바뀌어도 수정할 곳이 한 곳입니다.
• 타인(또는 다른 컴퓨터의 나)에게 배포할 때, CONFIGURE만 바꿔 쓰면 작동합니다.
• Claude 자신도 「어디가 설정이고 어디가 로직인지」를 오해하지 않게 됩니다.

참고로 API 토큰 종류는 CONFIGURE에도 적지 않습니다. macOS라면 Keychain에 넣어두고, 스킬에는 「security find-generic-password -s <service>로 취득하라」고 적습니다. SKILL.md는 평문으로 배포 및 백업되는 것이므로, 비밀 정보를 넣는 순간 패배하는 것입니다.

패턴 3: 본문에 안전장치를 명문화하기 (AI에게 전달하는 자동화의 작법)

스킬은 「AI가 읽는 운영 절차서」이므로, 인간용 절차서라면 생략할 법한 안전 위주의 지시를 명시적으로 작성해야 합니다. 제가 모든 스킬에 넣는 안전장치(Safety valve)는 3가지 종류가 있습니다.

1. 파괴적 조작 금지를 명문화하기

## Safety
- **Never `rm`.** Junk goes to `~/.Trash` (recoverable). Real files only move.

「삭제해 줘」라고 요청했을 때, AI가 「휴지통으로 이동(복구 가능)」을 기본값으로 설정하게 만듭니다. rm은 비가역적이며, 자동화 사고는 비가역적인 조작에서만 발생합니다.

2. dry-run + confirm을 기본값으로 하기

## Steps
2. Dry-run first: list what would move where. Ask for confirmation.

파일을 이동하거나 외부로 쓰는 종류의 스킬은, 먼저 「무엇을 할 것인지」를 출력하게 한 뒤 실행하게 합니다. 확인 과정을 생략하고 싶다면 CONFIGURE 플래그로 끌 수 있도록 해둡니다 (기본값은 안전 위주).

3. 「초안까지만, 게시하지는 않는다」 유형의 선 긋기

SNS 게시글을 작성하는 스킬에는 Drafts only. This never posts anywhere라고 적어둡니다. 생성과 공개 사이에 반드시 인간을 개입시킵니다. 공개 조작 자체를 자동화하고 싶어질 때도, 생성 스킬과는 별도의 스킬로 분리합니다.

이 3가지를 적어두면, 스킬을 배포받은 대상(동료나 미래의 자신)이 내용만 읽어도 「이것은 실행해도 안전하다」라고 감사(Audit)할 수 있습니다. 스킬을 짧게, 1개 파일로, 다 읽을 수 있는 사이즈로 유지하는 것도 이 때문입니다.

패턴 4: 정기 실행과 조합하기 (그리고 「성공의 날조」를 금지하기)

스킬이 본 실력을 발휘하는 것은 스케줄 실행(cron/launchd 또는 Claude Code의 scheduled tasks)과 조합했을 때입니다. 「매주 월요일 7시에 X를 하고 보고해」라는 명령이 설명 없이도 돌아가기 시작합니다.

여기서 10개 중 가장 큰 배움을 얻은 것이 바로 실패 시의 알림 설계입니다:

## Notes
- **Never notify "success" on failure.** Surface the error instead.
- Test the command manually before enabling the timer.

정기 작업(Periodic job)에서 최악인 상황은 「실패하고 있는데 성공 알림이 계속 오는」 상태입니다 (침묵보다 나쁩니다). 스킬에 「실패하면 에러를 그대로 보고해라, 성공을 날조하지 마라」라고 적어두는 것만으로도 이 사고는 거의 사라집니다. 아울러 「0건일 때 무엇을 보낼 것인가」(skip 알림을 낼 것인가, 침묵할 것인가)도 CONFIGURE에서 결정해 두면, 작업이 없는 주에 알림이 오지 않아 불안해지는 문제도 해결됩니다.

실제 사례 1개, 전문 공개: folder-tidy

패턴을 모두 넣은 실제 사례가 이것입니다. 그대로 ~/.claude/skills/folder-tidy/SKILL.md에 두면 작동합니다:

---
name: folder-tidy
description: 어지러운 macOS 폴더(데스크탑, 다운로드)를 파일 유형별로 하위 폴더에 정리하고, 남은 파일은 완전히 삭제하는 대신 휴지통으로 이동합니다. 사용자가 "tidy my desktop", "organize downloads", "clean up files" 또는 "my folder is a mess"라고 말할 때 사용하세요.
...

TARGET = "~/Downloads"
ROUTES = { Images: [jpg,png,gif,heic], Docs: [pdf,docx,xlsx,md],
Archives: [zip,tar,gz], Installers: [dmg,pkg], Media: [mp4,mov,mp3] }
TRASH_JUNK = true # 빈 파일 + 완료된 설치 프로그램은 휴지통으로 이동
CONFIRM_BEFORE_MOVE = true
```

실행 예시

"Tidy my Downloads" → 드라이 런 (dry-run) 미리보기 후, 유형별로 분류하고 설치 프로그램을 휴지통으로 이동합니다.

안전성

...

짧은 길이에 주목하세요. 스킬은 '포괄적인 문서'가 아니라 '**판단의 발판 (scaffolding for judgment)**'입니다. 긴 스킬은 Claude의 컨텍스트 (context)를 소모하며, 인간의 감사 가능성 (auditability)도 낮춥니다. 한 화면에 다 담기지 않는다면, 그것은 분할해야 한다는 신호라고 생각합니다.

## 요약

- **description에 발화 예시를 작성한다** (실행 여부는 여기서 결정됨)
- **CONFIGURE에 환경 의존성을 격리한다** (비밀 정보는 Keychain에 저장하고, SKILL.md에는 넣지 말 것)
- **안전장치를 명문화한다** (rm 금지 / dry-run + confirm / 초안만 작성)
- **정기 실행 시 성공을 조작하는 것을 금지한다** (실패 시에는 에러와 함께 보고)

이 4가지만 지켜도 스킬은 '데모에서만 작동하는 것'에서 '반년 동안 유지보수 없이 돌아가는 자산'이 됩니다.

### 홍보 (저자의 유료 템플릿입니다)

이 규격으로 작성된 10개(weekly-digest / notion-pusher / inbox-triage / folder-tidy / meeting-notes / content-drafter / page-watcher / kpi-logger / research-digest / scheduled-report)를 개인 환경의 값을 제거한 샌니타이즈 (sanitized) 버전 번들로 Gumroad에서 판매하고 있습니다. 본 기사의 folder-tidy는 그중 하나입니다.

- **Claude Skill Bundle: Productivity 10** — $49: https://claudeboost.gumroad.com/l/jkqahd
- 스킬이 아닌 MCP 서버를 작성하는 분들을 위한 프로덕션 패턴 7종이 포함된 **MCP Server Cookbook** — $29: https://claudeboost.gumroad.com/l/mcp-cookbook
- 개발자용 3종 팩 전체 포함 **The Complete Automation Studio** — $79: https://claudeboost.gumroad.com/l/studio

무료 버전으로는 학술 논문 검색을 위한 MCP 서버 scholar-mcp(npm: `@kak4343/scholar-mcp`)도 공개하고 있습니다. 질문은 댓글창에 남겨주세요.

### Discussion

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