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

ALT

Azure Portal의 스크린샷

"Claude한테 옵시디언 노트를 정리해달라고 했더니 [[위키링크]] 대신 일반 마크다운 링크로 써놨더라" — 한 번쯤 겪어본 일이죠?

옵시디언을 쓰면서 Claude Code나 Codex CLI로 자동화하려는 분이라면 답답한 순간이 분명 있어요. AI는 표준 마크다운은 잘 쓰지만 옵시디언만의 [[wikilinks]], 콜아웃, Bases, Canvas 같은 고유 문법은 모릅니다. 결국 일일이 다시 손봐야 했어요.

그런데 며칠 전, 옵시디언 CEO 본인이 직접 만든 스킬 묶음이 GitHub에 공개됐습니다. 별 29.1k, 포크 2k가 단 몇 주 만에 붙은 화제의 저장소예요. 오늘은 obsidian-skills의 5가지 스킬을 어떻게 쓰면 좋은지 정리합니다.

obsidian-skills가 뭔가요?

ALT

모자를 쓴 남자가 노란색과 검은색 배경 앞에서 웃고 있다

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는 일반 마크다운만 학습했지, 옵시디언 고유 확장 문법을 따로 배운 적이 없거든요.

옵시디언 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가지 설치 방법 — 본인 환경에 맞게 고르세요

가장 추천하는 건 Claude Code 통합입니다. 옵시디언 볼트 루트에 .claude/ 폴더 만들고 거기에 스킬들을 넣으면, Claude Code가 그 볼트에서 작업할 때마다 자동으로 옵시디언 문법을 적용합니다. 별도 설정도 필요 없어요.

알아두면 좋은 한계점

obsidian-skills가 만능은 아닙니다. 실제로 써보기 전에 알아두면 좋을 것들:

1. 에이전트가 Agent Skills 사양을 지원해야 함: ChatGPT 같은 일반 챗봇에서는 그대로 쓸 수 없어요. Claude Code, Codex CLI, OpenCode처럼 스킬을 로드할 수 있는 에이전트가 필요합니다.

2. defuddle은 별도 설치 필요: defuddle CLI 자체는 npm으로 따로 설치해야 합니다. 스킬은 사용법만 가르치는 거예요.

3. Bases는 옵시디언 1.7+ 필수: .base 파일 기능 자체가 비교적 최근에 들어와서, 구버전 옵시디언에서는 작동하지 않습니다.

4. 한국어 설명이 부족함: 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에 맞춰 코드를 작성합니다.

참고

• kepano/obsidian-skills GitHub — 본 글의 원본 저장소

• lucas_flatwhite의 X 트윗 — 한국어 소개 트윗

• Steph Ango (kepano) Twitter — CEO의 첫 발표 트윗

• Obsidian's Official Skills Are Here — Medium

• Obsidian Agent Skills 2026 Setup Guide — AI Money Tools