Obsidian의 CEO kepano(Steph Ango)가 만든 5개의 Agent Skill 모음. 서버도, 플러그인 코드도, MCP도 없이 오직 Markdown 지시문 파일만으로 Claude Code·Codex·OpenCode 같은 AI 에이전트에게 "옵시디언 CLI를 호출하고, Markdown·Bases·JSON Canvas 같은 개방 포맷을 직접 읽고 쓰는 법"을 가르친다. 코드가 아니라 '잘 쓰인 설명서'가 곧 기능이라는 게 이 레포의 정체성. (저장소: kepano/obsidian-skills · 5 Skills · 100% Markdown · MIT · ★ 36.8k · TrendShift #19)
"AI에게 '내 옵시디언 금고를 읽고 쓰는 법'을 코드 없이 가르치는 설명서 묶음."
당신이 옵시디언(Obsidian)에 수백 개의 노트를 쌓아 뒀다고 하자. 이제 AI 에이전트에게 "오늘 할 일을 오늘 노트에 추가해", "이 책들로 독서 목록 표를 만들어", "이 아이디어들을 캔버스에 지도로 그려"라고 시키고 싶다. 문제는 AI가 옵시디언의 문법과 도구를 모른다는 것. obsidian-skills는 그 지식을 5개의 Markdown 설명서로 적어 두었다. 에이전트가 사용자의 요청을 보고 알맞은 설명서를 펼쳐 읽은 뒤, 자기 손(셸 명령·파일 쓰기)으로 옵시디언을 다룬다.
핵심은 "스킬(skill)에는 실행 코드가 없다"는 점이다. 보통 'AI에게 기능을 붙인다'고 하면 서버를 띄우거나 플러그인을 깔지만, 이 레포는 파일이라곤 마크다운 11개와 JSON 2개뿐이다. 스킬은 에이전트에게 건네는 '지시문 조각'일 뿐이고, 실제 동작은 에이전트가 가진 Bash(셸)·파일 편집 도구로 일어난다.
SKILL.md 한 장을 두는데, 맨 위 frontmatter(머리표)에 name(이름)과 description(언제 쓰는지)만 적는다. 에이전트는 사용자 요청을 이 description과 맞춰 보고 알맞은 스킬을 고른다. agentskills.io의 개방 표준이라 Claude Code·Codex·OpenCode에서 똑같이 동작한다.만든 사람은 kepano(Steph Ango) — Obsidian의 CEO이자 인기 테마 'Minimal'의 제작자다. 즉 이 레포는 옵시디언을 가장 잘 아는 사람이 직접 내놓은, 거의 1차 출처에 가까운 에이전트 연동 방식이다. 라이선스는 MIT, 별은 약 3만 7천 개(2026-06 기준).
"서버·MCP 없이 마크다운 한 장으로 — 가장 가벼운 옵시디언 자동화."
2026년 상반기 개발자 생태계의 가장 큰 흐름 중 하나가 Agent Skills(에이전트 스킬)다. "AI에게 도구 쓰는 법을 어떻게 가르칠까?"라는 질문에 대한 크로스 벤더 표준으로, TrendShift 일간 인기 토픽에서도 #AI skills가 상위에 늘 보인다. obsidian-skills는 그 흐름의 가장 눈에 띄는 실전 예제이자, 만든 이가 옵시디언 CEO라는 점에서 권위까지 갖췄다.
지금까지 'AI + 옵시디언' 연동의 정석은 MCP 서버(예: obsidian-mcp)였다. 로컬에 REST API 서버를 띄우고, 그 서버가 MCP(Model Context Protocol)라는 도구 규약으로 기능을 노출한다. 강력하지만 설치·실행·포트·인증을 신경 써야 하고, 특정 서버 구현에 묶인다. "노트 하나 추가하자고 서버를 돌려야 하나?"라는 부담이 있었다.
obsidian-skills는 정반대의 초경량 접근을 택했다. 실행 프로세스를 새로 띄우지 않고, 에이전트가 이미 가진 셸·파일 도구로 옵시디언 공식 명령줄 도구(CLI)를 부르거나 파일을 직접 쓴다. 설명서는 개방 표준(Agent Skills)이라 Claude Code·Codex·OpenCode 어디서나 그대로 동작한다. 벤더 종속이 없고, 설치라곤 스킬 폴더를 복사하는 게 전부다.
MCP 서버 = 통역사를 고용해 사무실에 상주시키기 — 강력하지만 사람을 뽑고, 자리를 주고, 월급을 줘야 한다.
obsidian-skills = 잘 쓰인 '사용 설명서'를 책상에 놓아두기 — 일꾼(에이전트)이 필요할 때 펼쳐 읽고 스스로 처리한다. 추가 인력도, 상주 비용도 없다.
| 구분 | 그냥 프롬프트로 시키기 | obsidian-mcp (MCP 서버) | obsidian-skills |
|---|---|---|---|
| 설치/실행 | 없음 | 서버 설치·상시 실행 | 스킬 폴더 복사뿐 |
| 정확도 | 들쭉날쭉(문법 환각) | 높음 | 높음(검증 체크리스트 내장) |
| 이식성 | 매번 설명 반복 | MCP 지원 앱에 한정 | 스킬 표준 지원 에이전트 모두 |
| 유지보수 | - | 서버 버전 관리 | 마크다운 수정이 끝 |
| 제작자 | - | 커뮤니티 | Obsidian CEO(kepano) |
또 하나의 타이밍 요소는 옵시디언 자체의 신기능이다. 최근 옵시디언에 공식 명령줄 도구(CLI)와 Bases(.base, 노트 위에 데이터베이스 뷰를 얹는 기능)가 들어왔다. obsidian-skills는 이 갓 나온 기능들의 사실상 표준 사용 설명서 역할을 하며, 신기능과 함께 주목을 받았다.
백엔드 서버가 '없다'. '기술'은 ① 스킬 포맷 ② 옵시디언 CLI ③ 개방 포맷 3종 ④ 보조 CLI다.
이 레포에는 컴파일되는 코드가 한 줄도 없다. GitHub 언어 막대는 사실상 100% Markdown이다. 그래서 '프론트엔드/백엔드/인프라'로 나누는 대신, ① 스킬을 담는 그릇(Agent Skills 포맷) ② 살아있는 옵시디언을 조종하는 도구(CLI) ③ 파일로 직접 쓰는 개방 포맷 3종 ④ 토큰을 아끼는 보조 CLI로 보는 게 머리에 잘 들어온다.
스킬은 name과 description 두 줄짜리 머리표를 가진 SKILL.md다. 길고 자세한 표·예시는 references/ 폴더의 별도 문서로 빼서, 에이전트가 필요할 때만 펼쳐 읽게 한다(이게 4절의 '점진적 공개' 패턴).
| 요소 | 역할 |
|---|---|
SKILL.md | 스킬 본문. 머리표(name/description) + 짧은 지시문 |
description | 에이전트가 "이 요청에 이 스킬을 쓸까?"를 판단하는 방아쇠 문장 |
references/*.md | 무거운 참조 표(속성·콜아웃·함수 사전 등). 필요 시에만 로드 |
.claude-plugin/ | Claude Code 플러그인·마켓플레이스 등록용 JSON 2개 |
obsidian)obsidian CLI는 실행 중인 옵시디언 앱에 명령을 보내는 공식 도구다(앱이 켜져 있어야 함). 노트 생성·검색·속성 설정·할 일·데일리 노트는 물론, 플러그인/테마 개발용 디버그 명령(JS 실행, 에러 조회, 스크린샷, DOM 검사)까지 있다.
| 명령 갈래 | 예시 |
|---|---|
| 노트 CRUD | obsidian create · search · open |
| 속성·태스크 | property:set · daily:append |
| 플러그인 개발 | eval · plugin:reload · dev:errors · dev:screenshot |
CLI 없이도, 에이전트가 파일을 직접 써서 다루는 옵시디언의 개방 포맷들이다. 모두 텍스트라 검증(유효한 YAML·JSON·링크)이 가능하다.
| 포맷 | 정체 | 쓰임 |
|---|---|---|
| Markdown(.md) | 옵시디언 확장 마크다운 | 위키링크 [[..]]·콜아웃·속성·임베드 |
| Bases(.base) | YAML 데이터베이스 뷰 | 필터·포뮬러로 노트를 표/카드/지도로 |
| JSON Canvas(.canvas) | 개방 JSON 스펙(v1.0) | 무한 캔버스·마인드맵(노드+엣지) |
nodes)과 선(edges)으로 마인드맵·플로우차트를 표현한다. 둘 다 옵시디언이 만든 개방 포맷이라 누구나 코드로 생성·편집할 수 있다.Defuddle은 kepano가 만든 또 다른 도구로, 웹페이지에서 광고·메뉴를 걷어내고 본문만 깨끗한 마크다운으로 뽑는다(defuddle parse <url> --md). 에이전트가 웹을 읽을 때 일반 WebFetch 대신 이걸 써서 토큰(=비용)을 아끼라고 스킬이 안내한다.
'요청 → 설명서 선택 → 손(CLI/파일)으로 실행 → 검증'의 단순하지만 영리한 흐름.
obsidian-skills의 설계 미덕은 세 가지 패턴으로 요약된다. 모두 "스킬은 코드가 아니라 지시문"이라는 한 가지 통찰에서 나온다.
스킬 파일은 스스로 아무것도 실행하지 않는다. 에이전트가 그 지시문을 읽고, 자기 도구로 행동한다 — 셸로 obsidian/defuddle을 부르거나, 파일 쓰기로 .md/.base/.canvas를 짠다.
모델은 읽은 글자만큼 비용을 낸다. 그래서 SKILL.md는 짧게 유지하고, 방대한 표(속성 종류·콜아웃·함수 사전)는 references/로 빼서 정말 필요할 때만 펼쳐 읽게 한다. 실제 커밋 기록에도 "스킬 품질 점수 개선"으로 이 구조를 다듬은 흔적이 있다.
스킬은 크게 두 종류다. (A) 파일을 직접 쓰는 포맷 스킬(markdown·bases·json-canvas)은 CLI 없이 파일을 짜고 검증한다. (B) 살아있는 앱을 다루는 스킬(obsidian-cli·defuddle)은 외부 바이너리를 셸로 부른다.
스킬은 요리책의 한 페이지다. 책 자체는 요리를 하지 않는다. 요리사(에이전트)가 주문(요청)을 보고 알맞은 페이지를 펼쳐(description 매칭), 재료와 불(CLI·파일 도구)을 자기 손으로 다룬다. 두꺼운 부록(references)은 그 요리를 할 때만 들춘다.
이 구조의 묘미는 '에이전트가 자기 출력물을 검증한다'는 점이다. JSON Canvas 스킬은 "모든 노드 ID가 유일한가, 엣지가 가리키는 노드가 실제로 있는가"를 8가지 체크리스트로 스스로 점검하게 한다. 단순 생성이 아니라 '검증까지가 스킬'인 셈이다.
파일 13개가 전부 — '스킬 폴더 + 배포용 JSON' 두 덩어리.
레포 전체가 마크다운 11개 + JSON 2개로 끝난다. 구조는 ① 배포용 설정(.claude-plugin/) ② 스킬 5개(skills/) 두 덩어리다. 각 스킬은 SKILL.md 한 장, 무거운 스킬만 references/를 곁들인다.
주목할 점은 스킬마다 깊이가 다르다는 것이다. defuddle은 41줄짜리 한 장이면 충분하지만, obsidian-bases는 본문만 약 500줄에 함수 사전까지 따로 둔다. 복잡도에 비례해 references를 붙이는 이 절제가 곧 좋은 스킬 작성의 표본이다.
# skills/json-canvas/SKILL.md 의 맨 위 (frontmatter)
---
name: json-canvas
description: Create and edit JSON Canvas files (.canvas) with nodes,
edges, groups, and connections. Use when working with .canvas files,
creating visual canvases, mind maps, flowcharts, or when the user
mentions Canvas files in Obsidian.
---
# ↑ description이 '언제 이 스킬을 쓸지'를 결정하는 방아쇠다"에이전트에게 도구 쓰는 법 가르치기"의 살아있는 교본 + 옵시디언 개방 포맷 4종.
name/description 계약과 점진적 공개(짧은 SKILL.md + 필요 시 references)는 "내 도구를 AI에게 가르치는" 모든 프로젝트의 본보기다. 어떤 CLI든 이 모양 그대로 복제하면 된다.
당신이 자주 쓰는 CLI(예: git, ffmpeg)를 골라 그것을 가르치는 SKILL.md를 obsidian-cli 스킬과 똑같은 형식으로 한 장 써 보라. description을 어떻게 적어야 에이전트가 제때 고르는지 감이 온다.
파라미터(key="값") vs 플래그 문법, 파일 지정(file= 위키링크식 vs path= 정확 경로), 개발용 명령(eval·dev:errors·dev:screenshot)을 익힌다.
데일리 노트 워크플로를 자동화해 보라: obsidian daily:append content="- [ ] ..."로 오늘 할 일을 넣고, 태스크 쿼리로 미완료를 모아 본다.
노드/엣지 스키마, z-순서(배열 순서), 16자리 hex ID, 그리고 줄바꿈은 \n(이중 \\n 아님) 같은 함정과 8가지 검증 항목까지. '데이터로 다이어그램을 생성'하는 좋은 연습이다.
할 일 목록을 받아 칸반 보드 .canvas를 프로그램으로 생성해 보라(컬럼=그룹 노드, 카드=텍스트 노드). 옵시디언에서 열어 모양을 확인.
YAML 구조(filters/formulas/views), 재귀적 and/or 필터, 그리고 악명 높은 Duration 함정 — 날짜끼리 빼면 'Duration'이 나오므로 .round() 전에 .days를 먼저 꺼내야 한다.
# Bases 포뮬러: 마감까지 남은 일수
formulas:
days_until_due: 'if(due, (date(due) - today()).days, "")'
# 맞음: (now() - file.ctime).days.round(0) ← .days 먼저, 그 다음 round
# 틀림: ((date(due) - today()) / 86400000).round(0) ← Duration엔 안 통함위키링크 vs 일반 링크(옵시디언은 [[..]] 이름 변경을 자동 추적), 블록 ID, 콜아웃, frontmatter 타입을 익히면 노트를 코드로 다룰 수 있다. 그리고 언제 WebFetch 대신 Defuddle을 쓸지(단, .md URL은 defuddle 금지)도 실전 비용 감각으로 배운다.
특별한 하드웨어 0. 핵심 전제는 '옵시디언이 켜져 있을 것'과 '스킬 지원 에이전트'.
서버도 GPU도 필요 없다. 전부 내 컴퓨터에서 로컬로 돈다. 진짜 전제 조건은 두 가지 — CLI/Bases를 포함한 최신 옵시디언과 스킬을 읽을 줄 아는 에이전트다. 특히 obsidian CLI는 옵시디언 앱이 실제로 실행 중일 때만 살아있는 금고 명령이 통한다.
| 항목 | 필요 | 비고 |
|---|---|---|
| 옵시디언 | CLI·Bases 포함 최신판 | 최소 버전은 공식 문서 기준(둘 다 신기능) |
| 에이전트 | Claude Code · Codex · OpenCode | Agent Skills 표준 지원 클라이언트 |
| Node/npm | 선택 | npx skills 설치, Defuddle 설치 시 |
| Defuddle | 선택 | npm i -g defuddle (웹 읽기 스킬용) |
| Maps 플러그인 | 선택 | Bases의 map 뷰를 쓸 때만 |
| GPU/서버 | 불필요 | 모두 로컬 파일·CLI 조작 |
# Claude Code 마켓플레이스
/plugin marketplace add kepano/obsidian-skills
/plugin install obsidian@obsidian-skills
# skills CLI 로
npx skills add git@github.com:kepano/obsidian-skills.git
# Codex / OpenCode 는 폴더 복사
cp -r skills/* ~/.codex/skills/
git clone https://github.com/kepano/obsidian-skills ~/.opencode/skills/obsidian-skills"설치 → 첫 호출 → 내 스킬 작성 → 포맷 생성 → 나만의 스킬 팩 배포"로 난이도 상승.
Claude Code에서 /plugin marketplace add kepano/obsidian-skills로 설치한 뒤, 옵시디언을 켜 두고 "오늘 데일리 노트에 '우유 사기' 할 일을 추가해"라고 시켜 본다. 에이전트가 obsidian-cli 스킬을 골라 처리하는 걸 관찰.
skills/defuddle/SKILL.md(가장 짧음)를 본떠, 당신이 쓰는 CLI 하나를 가르치는 한 장짜리 스킬을 만든다. description만 잘 적어도 에이전트가 알아서 트리거하는 걸 확인.
"To Do / Doing / Done 3개 컬럼에 카드 5장을 배치한 캔버스를 만들어"라고 시켜, 생성된 .canvas를 옵시디언에서 연다. 노드 ID 유일성·엣지 유효성 검증이 어떻게 도는지 본다.
책 노트들에 status·rating 속성을 달고, 그것을 표 뷰로 모으는 .base를 만들게 한다. Duration 함정을 일부러 건드려(마감까지 남은 일수 계산) 올바른 포뮬러를 체득.
특정 주제(예: '내 회사 위키 규칙')용 스킬 2~3개를 한 폴더로 묶고, .claude-plugin/plugin.json·marketplace.json을 작성해 마켓플레이스로 배포 가능한 플러그인으로 만든다. obsidian-skills 구조를 그대로 베끼면 된다.
'옵시디언 기초 → 에이전트 스킬 → 개방 포맷 → 에이전트 통합'의 4주 코스.
| 주차 | 주제 | 학습 내용 & 레포 연결 |
|---|---|---|
| 1주차 | 옵시디언 & CLI 기초 | 금고·마크다운·속성·위키링크. 공식 obsidian CLI를 설치해 노트 생성·검색을 손으로 돌려 본다. obsidian-cli/SKILL.md 정독. |
| 2주차 | Agent Skills 포맷 | agentskills.io 스펙, frontmatter 계약, 점진적 공개. 5개 스킬을 읽으며 "왜 references로 뺐나"를 분석. 내 스킬 1개 작성. |
| 3주차 | 개방 포맷(Bases·JSON Canvas) | Bases YAML 포뮬러·뷰, JSON Canvas 스펙. references/의 함수 사전·예제를 보며 표/캔버스를 코드로 생성. |
| 4주차 | 에이전트 통합 & 배포 | Claude Code/Codex/OpenCode에 스킬 연결, 마켓플레이스 배포. MCP 서버 방식과 비교해 장단점을 정리. |
이 레포는 짧아서 전부 읽을 수 있다. 1) 5개 SKILL.md를 통독해 '좋은 스킬의 형태'를 머리에 새기고 → 2) 그 형태로 내 도구용 스킬을 흉내 내고 → 3) .claude-plugin/을 붙여 배포 가능한 플러그인으로 완성하면, "AI에게 도구를 가르치는" 전 과정을 한 바퀴 돈다.
레포 문서에 반복되는 용어를 한 곳에.
name+description 머리표와 본문으로 구성되며, 개방 표준(agentskills.io)이라 여러 에이전트에서 공통으로 쓰인다.name과 description만 쓰며, description이 곧 '언제 이 스킬을 발동할지'의 방아쇠가 된다.references/로 빼서 필요할 때만 로드하는 설계. 컨텍스트(토큰) 낭비를 줄이는 스킬 작성의 핵심 원칙.obsidian)nodes[](text/file/link/group)와 edges[]로 마인드맵·플로우차트를 표현.[[노트 이름]]은 노트 간 내부 링크로, 이름을 바꿔도 자동 추적된다. 콜아웃 > [!note]은 강조 박스로, 접고 펼 수 있다.공식 저장소·스펙·문서.
GitHub 저장소 · github.com/kepano/obsidian-skills — 5개 스킬 원본. skills/ 폴더부터 읽으면 좋다.
Agent Skills 스펙 · agentskills.io — SKILL.md 포맷의 개방 표준(name/description/references).
옵시디언 CLI 문서 · help.obsidian.md/cli — 명령 전체 목록·옵션.
JSON Canvas 스펙 · jsoncanvas.org — 노드/엣지 개방 표준(옵시디언 발).
Defuddle · github.com/kepano/defuddle — 웹→마크다운 추출 CLI.
제작자 · stephango.com — kepano(Steph Ango), Obsidian CEO.
TrendShift · trendshift.io/repositories/23353