옵시디언 스킬 완벽 정리 — 옵시디언 CEO가 직접 만든 Claude Code 스킬 5종 사용법
2026.05.06

"Claude한테 옵시디언 노트를 정리해달라고 했더니 [[위키링크]] 대신 일반 마크다운 링크로 써놨더라" — 한 번쯤 겪어본 일이죠?
옵시디언을 쓰면서 Claude Code나 Codex CLI로 자동화하려는 분이라면 답답한 순간이 분명 있어요. AI는 표준 마크다운은 잘 쓰지만 옵시디언만의 [[wikilinks]], 콜아웃, Bases, Canvas 같은 고유 문법은 모릅니다. 결국 일일이 다시 손봐야 했어요.
그런데 며칠 전, 옵시디언 CEO 본인이 직접 만든 스킬 묶음이 GitHub에 공개됐습니다. 별 29.1k, 포크 2k가 단 몇 주 만에 붙은 화제의 저장소예요. 오늘은 obsidian-skills의 5가지 스킬을 어떻게 쓰면 좋은지 정리합니다.
obsidian-skills가 뭔가요?

obsidian-skills는 옵시디언 CEO Steph Ango(kepano)가 직접 만들어 공개한 Agent Skills 모음입니다. Claude Code, Codex CLI, OpenCode 같은 AI 코딩 에이전트가 옵시디언의 고유 문법(.md, .base, .canvas, CLI)을 미리 학습할 수 있도록 도와주는 스킬 5종 패키지예요.
핵심 가치는 단순합니다. AI에게 "옵시디언처럼 행동하는 법"을 한 번에 가르쳐 두는 것. Agent Skills 사양을 따르기 때문에 호환되는 어떤 에이전트에서도 쓸 수 있고, 에이전트가 SKILL.md의 이름·설명만 먼저 읽고 진짜 필요할 때 전체 내용을 로드합니다. 토큰도 아끼고 정확도도 올라가는 구조예요.
왜 옵시디언 CEO가 직접 만들었을까?
ChatGPT나 Claude한테 옵시디언 노트를 만들어 달라고 하면 결과가 어색한 이유가 있어요. AI는 일반 마크다운만 학습했지, 옵시디언 고유 확장 문법을 따로 배운 적이 없거든요.
옵시디언 고유 문법 | AI의 기본 출력 (틀림) | 옵시디언 정답 |
|---|---|---|
위키링크 |
|
|
임베드 | 별도 첨부 안내 |
|
콜아웃 | 일반 인용 |
|
블록 링크 | 무시 |
|
Bases 데이터베이스 | 모름 |
|
Canvas 다이어그램 | 모름 |
|
옵시디언 CEO 본인이 이걸 가장 답답해했고, 결국 권위 있는 출처에서 직접 정답을 공개한 셈이에요. 이전에는 Karpathy의 LLM Wiki 같은 비공식 가이드뿐이었는데, 이제는 공식 레퍼런스가 생긴 거죠.
obsidian-skills 5종 — 각각 뭘 가르치나요?
1. obsidian-markdown — 위키링크부터 콜아웃까지
가장 기본이자 가장 많이 쓰는 스킬이에요. AI가 옵시디언 노트를 작성·편집할 때 다음을 자동으로 적용해줍니다.
[[Note Name]] ← 기본 위키링크
[[Note Name|표시 텍스트]] ← 별칭 링크
[[Note#Heading]] ← 헤딩 링크
[[Note#^block-id]] ← 블록 링크
![[image.png|300]] ← 너비 지정 이미지 임베드
> [!warning] 커스텀 제목
> [!faq]- 접힌 FAQ 콜아웃
==하이라이트== %%숨김 텍스트%% $LaTeX$콜아웃 유형도 13가지(note, tip, warning, info, example, quote, bug, danger, success, failure, question, abstract, todo)를 모두 알고 있고, frontmatter의 aliases, cssclasses, 계층 태그(#nested/tag)까지 정확히 다룹니다.
2. obsidian-bases — 노트를 데이터베이스처럼
.base 파일은 옵시디언 노트들을 표/카드/리스트/지도 뷰로 보여주는 데이터베이스 기능입니다. 이 스킬은 다음을 가르쳐요.
filters:
- tag: project
- status != "done"
formulas:
is_done: 'if(done, "✅", "⏳")'
days_left: '(date(due_date) - today()).days'
views:
- type: table
properties: [title, status, days_left]
summary:
days_left: average핵심 규칙도 정확히 알려줘요: 수식에 큰따옴표가 들어가면 작은따옴표로 감싸야 한다, Duration 계산 시 .days 같은 숫자 필드를 먼저 접근한다, 속성이 비어있을 수 있으면 if로 감싼다 — 이런 함정까지 미리 학습돼 있습니다.
3. json-canvas — 시각적 다이어그램
.canvas 파일은 마인드맵, 플로우차트, 연결 다이어그램을 만드는 옵시디언의 비주얼 캔버스예요. 이 스킬을 쓰면 AI가 노드/엣지를 정확한 JSON 구조로 생성합니다.
{
"nodes": [
{"id": "a1b2c3d4e5f6g7h8", "type": "text",
"x": 0, "y": 0, "width": 300, "height": 100,
"color": "1", "text": "## 핵심 아이디어"},
{"id": "x9y8z7w6v5u4t3s2", "type": "file",
"x": 400, "y": 0, "width": 300, "height": 200,
"file": "notes/related.md"}
],
"edges": [
{"id": "edge1", "fromNode": "a1b2c3d4e5f6g7h8",
"toNode": "x9y8z7w6v5u4t3s2",
"fromSide": "right", "toSide": "left",
"label": "참고"}
]
}각 노드의 16자 hex ID 생성 규칙, 엣지 양쪽 노드 참조 검증, 색상 프리셋(1~6) 같은 세부 사항까지 다 학습돼 있어 AI가 만든 캔버스가 옵시디언에서 바로 열립니다.
4. obsidian-cli — 볼트 자동화 + 플러그인 개발
옵시디언 CLI를 통해 AI가 볼트를 자동으로 조작하거나 플러그인/테마를 개발할 때 쓰는 스킬입니다. 노트 생성, 검색, 메타데이터 변경, 플러그인 패키징 같은 명령을 정확히 알아서 실행해요.
특히 옵시디언 플러그인을 만들고 싶은데 TypeScript에 익숙하지 않은 분에게 유용합니다. AI가 Obsidian Plugin API를 알고 있다는 전제로 코딩을 도와주거든요.
5. defuddle — 웹페이지를 깨끗한 마크다운으로
이건 좀 특이한 스킬이에요. 웹페이지 내용을 광고/네비게이션 없이 깔끔한 마크다운으로 추출하는 CLI 도구를 AI가 알아서 쓰게 해줍니다.
defuddle parse <url> --md # 마크다운 출력
defuddle parse <url> --md -o content.md # 파일로 저장
defuddle parse <url> -p title # 제목만
defuddle parse <url> -p description # 설명만WebFetch로 가져오면 광고와 메뉴까지 들어와서 토큰을 잡아먹는데, defuddle은 본문만 깔끔히 뽑아냅니다. 옵시디언 Web Clipper와 같은 결을 가진 도구예요. 블로그 글을 raw/ 폴더로 자동 저장하는 RAG 파이프라인 만들 때 핵심이 될 수 있습니다.
5가지 설치 방법 — 본인 환경에 맞게 고르세요
환경 | 명령어 |
|---|---|
옵시디언 플러그인 |
|
npx skills 도구 |
|
Claude Code | 저장소 내용을 볼트의 |
Codex CLI |
|
OpenCode | 저장소 전체를 |
가장 추천하는 건 Claude Code 통합입니다. 옵시디언 볼트 루트에 .claude/ 폴더 만들고 거기에 스킬들을 넣으면, Claude Code가 그 볼트에서 작업할 때마다 자동으로 옵시디언 문법을 적용합니다. 별도 설정도 필요 없어요.
알아두면 좋은 한계점
obsidian-skills가 만능은 아닙니다. 실제로 써보기 전에 알아두면 좋을 것들:
에이전트가 Agent Skills 사양을 지원해야 함: ChatGPT 같은 일반 챗봇에서는 그대로 쓸 수 없어요. Claude Code, Codex CLI, OpenCode처럼 스킬을 로드할 수 있는 에이전트가 필요합니다.
defuddle은 별도 설치 필요: defuddle CLI 자체는 npm으로 따로 설치해야 합니다. 스킬은 사용법만 가르치는 거예요.
Bases는 옵시디언 1.7+ 필수:
.base파일 기능 자체가 비교적 최근에 들어와서, 구버전 옵시디언에서는 작동하지 않습니다.한국어 설명이 부족함: SKILL.md가 영어로만 작성돼 있어서, 한국어 프롬프트로 자연스럽게 호출하려면 약간의 학습이 필요할 수 있어요.
자주 묻는 질문
obsidian-skills는 무료인가요?
네, MIT 라이선스로 완전히 무료입니다. GitHub에서 누구나 클론하거나 포크해서 자유롭게 쓸 수 있어요.
옵시디언 없어도 쓸 수 있나요?
defuddle 스킬은 단독으로도 유용합니다. 나머지 4개 스킬(markdown, bases, json-canvas, cli)은 옵시디언 볼트에서 작업할 때 진가가 나옵니다.
Claude Code 외에 어떤 에이전트에서 쓰나요?
Codex CLI(OpenAI), OpenCode 같은 Agent Skills 호환 에이전트면 어디서나 작동합니다. 사양 자체가 표준화돼 있어서 앞으로 더 많은 에이전트가 호환될 거예요.
Karpathy의 옵시디언 RAG와 같이 쓰면 어떤가요?
시너지가 큽니다. Karpathy 방식은 raw/ + wiki/ + CLAUDE.md로 AI가 알아서 정보를 정리하는 구조인데, obsidian-skills를 더하면 AI가 옵시디언 고유 문법으로 정리해줍니다. 결과물의 품질이 한 단계 올라가요.
옵시디언 플러그인 개발도 도와주나요?
네, obsidian-cli 스킬에 플러그인·테마 개발 가이드가 포함돼 있습니다. AI가 Obsidian Plugin API에 맞춰 코드를 작성합니다.
참고

editor_소연님, Claude가
[[위키링크]]대신[Note](note.md)로 써서 다시 고치던 문제를 kepano obsidian-skills 5종(markdown·bases·json-canvas·cli·defuddle)으로 정리해 주셔서 설치 경로를 바로 따라가 볼 수 있었습니다. 볼트.claude/에 넣어 Claude Code가 옵시디언 문법을 쓰게 하는 추천과, Agent Skills 미지원 챗봇·defuddle 별도 설치·Bases 1.7+ 한계까지 한곳에 모아 둔 점이 실무에 바로 연결됩니다. Karpathy식 raw/wiki 정리와 같이 쓰면 문법까지 맞춰진다는 FAQ도 운영 설계에 도움이 됩니다.