옵시디언(Obsidian)은 내 컴퓨터 폴더 안에 있는 마크다운 파일을 검색·연결·확장 가능한 지식 시스템으로 바꿔주는 앱입니다. 2026년 2월 공개된 Obsidian CLI 덕분에 이제 AI 에이전트(Claude Code, Codex CLI 등)와 결합하면 더 강력한 자동화가 가능해졌습니다. 메모 앱으로 시작해 업무 문서, 회의록, 개발 노트까지 한 곳에서 관리하면서 AI가 직접 노트를 생성·검색·수정하게 할 수 있습니다.
Obsidian CLI가 뭐길래 AI 에이전트와 궁합이 좋을까
Obsidian CLI는 터미널에서 옵시디언을 조작할 수 있게 해주는 공식 커맨드라인 인터페이스입니다. 기존에는 옵시디언 앱 안에서만 가능했던 작업을 이제 스크립트와 외부 도구로 연결할 수 있게 되었습니다.
- 단발 명령과 TUI 모두 지원: 한 번 실행하고 끝내는 명령도 되고,
obsidian만 입력해 TUI 모드로 들어가 연속 입력도 가능 - 개발자 명령 포함: 개발자 도구 열기, 플러그인 리로드, 스크린샷, 콘솔 실행 등이 가능해 에이전트 기반 디버깅/테스트에 활용할 수 있음
- 클립보드 복사 기능: 어떤 명령이든
--copy를 붙이면 출력 결과를 클립보드로 복사해 AI에 바로 붙여넣기 가능
설치 전에 운영체제별 조건을 확인해야 합니다. macOS는 -/.zprofile에 PATH가 추가되며, zsh가 아닌 쉘을 쓰면 수동 설정이 필요할 수 있습니다. Linux는 심볼릭 링크 방식, Windows는 터미널 입출력을 위한 별도 리다이렉터가 필요한 경우가 있습니다.
AI 에이전트가 옵시디언을 이해하게 만드는 obsidian-skills
옵시디언 CEO Steph Ango(kepano)가 직접 만든 obsidian-skills는 AI 코딩 에이전트가 옵시디언의 고유 문법을 미리 학습할 수 있게 도와주는 5종 스킬 패키지입니다. 별 29.1k, 포크 2k가 단 몇 주 만에 붙은 화제의 저장소입니다.
5가지 스킬의 핵심 기능
| 스킬 | 설명 |
|---|---|
| markdown | 위키링크([[]]), 콜아웃(13가지 타입), 프론트매터(aliases, cssclasses), 계층 태그(#nested/tag) 등 옵시디언 고유 문법을 AI가 정확히 구사하게 함 |
| bases | .base 파일을 표/카드/리스트/지도 뷰로 보여주는 데이터베이스 기능. Duration 계산 시 .days 필드 접근, 속성 비어있을 때 if 처리 등까지 학습 |
| json-canvas | 마인드맵, 플로우차트, 연결 다이어그램을 만드는 캔버스. 각 노드의 16자 hex ID 생성 규칙, 엣지 양쪽 노드 참조 검증, 색상 프리셋(1-6)까지 정확히 구현 |
| cli | Obsidian CLI를 통한 노트 생성·검색·메타데이터 변경·플러그인 패키징 명령을 AI가 정확히 실행 |
| defuddle | 웹페이지 내용을 광고/네비게이션 없이 깔끔한 마크다운으로 추출하는 CLI 도구 |
설치 방법은 간단합니다. Claude Code를 사용한다면 볼트 루트에 .claude/ 폴더를 만들고 거기에 스킬들을 넣으면, Claude Code가 그 볼트에서 작업할 때마다 자동으로 옵시디언 문법을 적용합니다.
npx skills add [email protected]:kepano/obsidian-skills.git
Codex CLI나 OpenCode를 쓴다면 각각 .codex/나 -/.opencode/skills/obsidian-skills/ 경로에 저장하면 됩니다.
실전 활용법 1 AI가 직접 노트를 작성하고 정리한다
가장 기본적이면서도 강력한 활용법입니다. AI 에이전트에게 "오늘 회의 내용을 옵시디언 노트로 정리해줘"라고 지시하면, CLI를 통해 노트를 생성하고 위키링크와 콜아웃까지 적용해 돌려줍니다.
- RAG의 로컬 버전처럼 동작: 옵시디언 노트는 텍스트 파일이라 AI가 읽고 요약·비교·분류하기에 최적. CLI가 검색과 태그 추출을 자동화
- 컨텍스트 윈도우 절약: 회의록 10개를 통째로 넣는 대신, CLI로 검색해 관련 부분만 뽑아서 AI에 전달하면 훨씬 정확한 결과를 얻을 수 있음
- 일관된 노트 구조 유지: 프론트매터(날짜, 태그, 별칭)와 콜아웃(note, tip, warning 등)을 AI가 자동으로 적용
예를 들어 "지난주 장애 대응 노트를 검색해서 핵심 타임라인을 요약해줘"라고 하면, CLI가 search query="장애 대응" 결과를 가져오고 AI가 그걸 바탕으로 요약을 생성합니다.
실전 활용법 2 작업 종료 시 자동으로 로그를 남긴다
많은 사람이 기록을 못 하는 이유는 의지가 약해서가 아니라 귀찮아서입니다. 작업이 끝나는 순간 자동으로 로그가 남는다면 어떨까요?
- CI/CD 파이프라인과 연동: 배포가 완료되면 스크립트가 자동으로 Obsidian CLI를 호출해 배포 노트 생성
- 장애 대응 자동 기록: AI 에이전트가 장애 대응 과정을 요약해서 런북에 반영. CLI로 검색/삽입을 자동화하면 업데이트 장벽이 확 낮아짐
- 코드 변경 사유 기록: "왜 이렇게 바꿨죠?"라는 질문에 답할 수 있도록, AI가 코드 변경과 함께 의사결정 기록을 노트로 생성
이렇게 하면 나중에 "내가 왜 이 코드를 썼는지"가 명확해집니다. 미래의 내가 과거의 나를 미워하지 않게 되는 흔치 않은 길입니다.
실전 활용법 3 개인 지식 베이스를 AI가 실시간 검색한다
AI 에이전트가 답을 만들기 전에 먼저 옵시디언 볼트에서 관련 정보를 검색(리트리벌)하고, 그걸 바탕으로 생성하게 할 수 있습니다. 쉽게 말해 "기억력 보정 + 근거 기반 답변"입니다.
- 의미 기반 검색: 임베딩 기술로 "의미가 비슷한 문장"을 찾아내 키워드 매칭 이상의 정확도 확보
- MCP(모델 컨텍스트 프로토콜) 활용: AI 도구가 로컬 옵시디언 데이터에 안전하고 표준화된 방식으로 연결
- 에이전트가 직접 파일 읽기/수정: 사람 대신 AI가 목표를 달성하기 위해 스스로 계획을 세우고, 파일을 읽고, 수정하고, 명령을 실행
예: "Redis 타임아웃 관련 내 노트를 찾아서 해결 방법을 알려줘" → CLI가 검색 → AI가 결과 분석 → 해결책 제시
실전 활용법 4 코드 리뷰에 의사결정 내역을 자동 첨부
코드 리뷰에서 가장 자주 나오는 질문은 "왜 이렇게 바꿨죠?"입니다. AI 에이전트는 코드 변경과 테스트까지는 잘하지만, 의사결정 기록은 사람이 놓치기 쉽습니다.
- 변경 사항과 함께 노트 생성: AI가 코드를 수정할 때마다 "왜 이렇게 수정했는지"를 옵시디언 노트로 자동 저장
- CLI로 쉽게 박아 넣기:
obsidian note create "PR #123 의사결정" --content "..."형태로 명령어 한 줄이면 끝 - 참조 링크 자동 연결: 관련 이슈, 커밋, 다른 노트와의 링크를 AI가 자동으로 생성
이렇게 쌓인 의사결정 기록은 나중에 비슷한 문제를 다시 만났을 때 "사고의 경로"를 따라가며 복기하게 해줍니다.
실전 활용법 5 웹 콘텐츠를 자동 수집해 RAG 파이프라인 구축
defuddle 스킬을 활용하면 웹페이지 내용을 광고와 네비게이션 없이 깔끔한 마크다운으로 추출할 수 있습니다. 이걸 옵시디언 볼트에 자동 저장하는 RAG 파이프라인을 만들 수 있습니다.
- 블로그 글을 raw 폴더로 자동 저장: 정기적으로 읽는 블로그나 문서 사이트를 구독하는 스크립트 작성 가능
- Web Clipper 대체: 옵시디언 Web Clipper와 유사한 기능을 CLI로 구현
- 검색 가능한 개인 아카이브: 수집된 모든 콘텐츠가 옵시디언 검색과 AI 검색의 대상이 됨
단, defuddle CLI 자체는 npm으로 따로 설치해야 하고, 스킬은 사용법만 가르치는 역할을 합니다.
Q. obsidian-skills는 무료인가요?
네, MIT 라이선스로 완전히 무료입니다. GitHub에서 누구나 클론하거나 포크해서 자유롭게 쓸 수 있습니다.
Q. 일반 ChatGPT에서도 사용할 수 있나요?
아니요. ChatGPT 같은 일반 챗봇에서는 그대로 쓸 수 없습니다. Claude Code, Codex CLI, OpenCode처럼 스킬을 로드할 수 있는 에이전트가 필요합니다.
Q. 설치할 때 주의할 점이 있나요?
Bases 기능은 옵시디언 1.7+ 버전이 필요합니다. 구버전에서는 작동하지 않습니다. 또한 SKILL.md가 영어로만 작성되어 있어, 한국어 프롬프트로 자연스럽게 호출하려면 약간의 학습이 필요할 수 있습니다.