🚀 서론

Claude Code를 매일 사용하다 보니, "항상 똑같은 지시를 하고 있네", "똑같은 절차를 밟고 있네"라고 느껴지는 상황이 늘어났습니다.

그래서 Claude Code의 커스텀 스킬 (Custom Skill) 기능을 사용하여 개인 워크플로우를 17개 정도 만들었더니, 상상 이상으로 없어서는 안 될 존재가 되었습니다. 이에 설계 방침과 실례를 정리해 봅니다.

🧩 커스텀 스킬이란

Claude Code는 ~/.claude/skills/<skill-name>/SKILL.md에 Markdown을 두면, 그것을 스킬 (≒ 파라미터가 포함된 정형 프롬프트 + 도구 권한)로서 호출할 수 있습니다.

~/.claude/skills/
└── my-skill/
└── SKILL.md

SKILL.md의 서두에 프런트매터 (Frontmatter)를 작성하는 것만으로, 슬래시 명령어 (/my-skill)로 호출하거나 자연어 트리거로 자동 발화(Auto-invocation)시킬 수 있습니다.

---
name: my-skill
description: "무엇을 하는 스킬인지 (자동 발화의 트리거로도 사용됨)"
...

포인트는 description입니다. 이 문장을 바탕으로 Claude가 "지금 이 스킬을 호출해야 하는가"를 판단하기 때문에, 트리거 조건은 명시적으로 작성해야 합니다.

📂 dotfiles에 올려서 배포

스킬은 개인 자산이므로, .claude/ 폴더째로 dotfiles에 넣고 GNU Stow를 사용하여 심볼릭 링크 (Symbolic Link)를 걸기만 하면 됩니다.

~/.dotfiles/settings/claude/.claude/
├── settings.json ← 권한(permissions) 등
└── skills/
...

stow -d ~/.dotfiles/settings -t $HOME claude

git pull을 하는 것만으로 모든 머신에 새로운 스킬이 전달됩니다. Stow를 이용한 dotfiles 관리는 이미 알려진 기사가 많으므로, 자세한 내용은 공개 리포지토리 (Public Repository)를 참조해 주세요.

🏷️ Claude Code 고유의 디렉토리 관습

스킬을 늘려가면서 깨달은, Claude Code만의 설계 노하우를 소개합니다.

d- 접두사로 네임스페이스 만들기

필자는 직접 만든 모든 스킬에 d- 접두사 (GitHub ID ugdark의 "d"에서 유래)를 붙이고 있습니다.

~/.claude/skills/
├── code-review/ ← 내장 또는 플러그인
├── deep-research/ ← 위와 동일
...

이렇게 하면 /d-를 입력했을 때 자신의 스킬만 보완 후보(Completion candidate)로 나타납니다. 내장 기능이나 다른 플러그인과의 충돌을 방지할 수 있을 뿐만 아니라, 프로젝트 고유 스킬과의 중복도 피할 수 있다는 점이 은근히 효과적입니다.

예를 들어 필자는 개인용 d-pre-review (로컬 코드 리뷰)를 가지고 있지만, 프로젝트 측에도 pre-review라는 동일한 스킬이 존재할 수 있습니다.

d- 접두사 덕분에 "프로젝트의 스킬을 덮어쓰지 않고, 개인용 버전으로서 공존할 수 있습니다". 프로젝트에 참여하고 있는 다른 멤버들에게 영향을 주지 않으면서, 자신만 개인 스킬을 병용할 수 있는 것입니다.

수동 / 자동 발화의 구분 사용

프런트매터의 두 가지 플래그에 따라 동작이 달라집니다.

"/d-magi는 명시적으로 호출하고 싶을 때만 동작했으면 좋겠다"와 같은 제어는 이 방식으로 수행합니다. description...

가 너무 좋으면 의도치 않게 발화(trigger)될 수 있으므로, 이를 억제하고 싶다면 disable-model-invocation: true를 설정합니다.

allowed-tools로 권한 최소화

스킬마다 사용할 수 있는 도구(tool)를 제한할 수 있습니다.

# 읽기 전용 스킬
allowed-tools: Read, Glob, Grep
# plan을 수정하는 스킬
...

"d-note가 실수로 rm을 실행하는" 것과 같은 사고를 구조적으로 방지할 수 있습니다.

settings.json도 dotfiles에 포함하기

스킬만 갖춰 놓아도, Bash(rm:*)를 허용할지 확인할지 등의 설정은 settings.json 측에서 담당합니다. 이것도 함께 dotfiles에 올려두면 완벽합니다.

{
  "permissions": {
    "allow": ["Read", "Glob", "Grep", "Bash(git status:*)", "Bash(git diff:*)"],
    ...
  }
}

필자는 Read/Glob/Grep은 전체 허용, Edit/Write는 경로 제한, Bash는 패턴별 개별 허용, 파괴적인 작업은 deny로 명시하는 방침을 세웠습니다.

🔁 실례 1: Plan 주도 시리즈 — 장기 태스크를 Claude에게 맡기는 5가지 기둥

가장 많이 사용하는 것이 Plan 주도 시리즈입니다.

plan 파일 자체는 단순한 Markdown이지만,

## 대응 상황
- [ ] 테이블 생성 migration 추가
- [ ] repository 계층 구현
...

이 체크박스를 하나씩 구현 → 사용자 확인 → 체크 → 다음 단계라는 흐름으로 고정함으로써, "Claude가 폭주하여 10개의 파일을 한꺼번에 수정하는" 사고가 급격히 줄었습니다.

💡 d-plan-resume을 사용하면, 다른 날에 작업을 재개하더라도 어디서부터 계속해야 할지 헤매지 않습니다. Claude 스스로가 active plan을 읽고 "다음은 이 태스크군요"라고 제안해 줍니다.

⚡ 실례 2: 원샷 계열 — "항상 하는 작업"을 한 번의 명령어로

📝 d-note: 가벼운 메모 추가

"이거 메모해 둬"

라고 말하는 것만으로 ~/.dotfiles/vault/note.md의 끝에 직전 대화의 요점을 3~10줄로 요약하여 추가합니다. "plan으로 만들기에는 애매하지만 잊고 싶지 않은 이야기" 전용 보관소입니다.

🗄️ d-sql: Sequel Ace 연결을 활용하여 MySQL 호출하기

Mac에서 MySQL 클라이언트라고 하면 Sequel Ace를 떠올리지만, 접속 정보를 CLI에서도 사용하고 싶습니다. Sequel Ace의 Favorites를 읽어 래퍼 스크립트(wrapper script)를 통해 접속하도록 설정했더니, Claude에게 "localdb의 users 테이블 보여줘"라고 말하는 것만으로 결과를 받을 수 있게 되었습니다.

📅 d-daily-start: 일보(Daily Report) 자동 준비

"일보 작성"

이라는 한마디로:

여기서 핵심은 Claude Code의 MCP (Model Context Protocol) 연동입니다. mcp__claude_ai_Google_Calendar__list_events를 allowed-tools에 작성해 두면, 스킬에서 직접 캘린더 API를 호출할 수 있습니다.

🎭 실례 3: 재미 요소 계열 — 하지만 실용적인

d-persona: 인격 전환 (人格切り替え)

/d-persona louise # 루이즈 (츤데레 독설, 직설적인 지적형)
/d-persona gendou # 이카리 겐도 (부정적인 관점에서 문제를 파고듦)

농담처럼 들리겠지만, 이것이 의외로 효과적입니다.

"무르다고. 그 정도 고려로는 실전에서 죽을걸."

애매한 설계를 가져가면 이렇게 대답해 주는 장치로서 기능합니다. AI의 사양(遠慮)을 강제적으로 깎아내는 것이 목적입니다.

d-magi: 3개 병렬 에이전트를 통한 다수결 판정

에반게리온의 MAGI 시스템을 모티브로 한 스킬입니다. Agent 툴을 통해 3개의 서브 에이전트(Sub-agent)를 병렬로 기동하여 서로 다른 관점(공격/방어/밸런스)에서 분석하게 하고, 다수결로 결론을 도출합니다.

기술 선정이나 설계 판단 시 "내 편견이 아닌지 확인하고 싶을 때" 사용합니다. 3개의 에이전트가 서로 다른 결론을 내놓으면 "아, 이거 정말 어려운 문제구나"라고 깨달을 수 있습니다.

📐 설계의 3원칙

17개를 만들어보며 알게 된, 범용 스킬로 만들어야 할 것과 프로젝트 고유 사항으로 남겨야 할 것의 구분 기준입니다.

1️⃣ 프로덕트 및 언어에 의존하지 않기

d-plan-implement에 sbt format이나 npm test를 하드코딩(Hard-code)하지 않습니다. 테스트 명령어는 프로젝트의 CLAUDE.md에 작성하게 하고, 스킬은 그것을 참조합니다.

2️⃣ 프로젝트 고유 사항은 CLAUDE.md에 위임

각 리포지토리(Repository)의 CLAUDE.md가 스킬에 대한 설정 파일 역할을 합니다. 스킬 측에는 "CLAUDE.md의 설정을 확인하고 실행"이라고만 작성합니다.

3️⃣ 템플릿은 심플하게

Plan 템플릿에 "결론", "배경", "대안", "리스크"와 같은 헤더를 난립시키지 않습니다. 구조만 배치하고, 구체적인 내용은 리뷰(Review) 시 Claude가 채우도록 합니다.

🐛 빠졌던 함정

🎁 요약

"Claude Code를 사용하고 있지만, 매번 똑같은 지시를 하고 있는 것 같다"라고 느끼는 분들은, 그 반복되는 부분을 스킬화하는 것부터 시작해 보세요.

필자의 dotfiles: https://github.com/ugdark/dotfiles

Discussion