Obsidian 에이전트 스킬 지원 범위와 검수: 파일 생성부터 실제 동작 확인까지

Obsidian 에이전트 스킬은 Markdown·Bases·Canvas 파일 작성, CLI를 통한 보관함 조작, 웹 본문 추출, 템플릿 생성을 지원합니다. 검수할 때는 스킬 패키지의 형식과 생성된 파일의 동작을 따로 봐야 해요. 메타데이터 검사를 통과해도 노트 안의 링크나 화면 표시까지 확인된 건 아니기 때문에, 구문 → 참조 → 실제 표시 순서로 점검하길 권합니다.

먼저 용어부터 짚겠습니다. Agent Skills는 작업 지침과 YAML 메타데이터를 담은 SKILL.md를 중심으로, 필요한 스크립트와 참고 자료를 한 디렉터리에 묶어 제공하는 형식입니다. 그래서 어떤 스킬이 무엇을 지원하는지 판단하려면 이름만 볼 게 아니라 연결된 도구와 실행 환경까지 함께 봐야 해요.

여섯 스킬은 각각 무엇을 하고, 무엇이 있어야 돌아가나

kepano/obsidian-skills README에는 여섯 스킬이 소개되어 있습니다. 세 개는 파일을 직접 쓰고 고치는 스킬이에요. obsidian-markdown은 위키링크·임베드·콜아웃·속성을 포함한 .md 파일을, obsidian-bases는 뷰·필터·수식·요약을 포함한 .base 파일을, json-canvas는 노드·연결선·그룹을 포함한 .canvas 파일을 작성하고 수정합니다.

나머지 셋은 성격이 조금 다릅니다. obsidian-cli는 CLI 기반 보관함 조작과 플러그인·테마 개발 작업을 맡아요. defuddle은 웹페이지에서 불필요한 요소를 걷어내고 Markdown 본문만 추출하고, knap은 JSON·CSV 데이터로 Markdown 템플릿을 렌더링하거나 일괄 생성합니다.

제가 가장 먼저 구분하라고 권하는 건, 하려는 일이 파일 작성인지 실행 중인 Obsidian 앱을 조작하는 일인지예요. 두 기능은 준비 조건부터 다릅니다. 흔히 헷갈리는 부분인데, 에이전트용 스킬을 설치했다고 Obsidian 안에 채팅 화면이 생기는 것도 아니에요.

CLI 쪽은 설정에서 활성화하고 등록하는 과정이 필요합니다. Obsidian CLI 공식 문서의 설치·문제 해결 안내에 따르면 설치 프로그램 버전이 1.12.7 이상이어야 하는데, 이 숫자는 최신 앱 버전을 가리키는 표기가 아니니 혼동하지 마세요. 명령은 실행 중인 앱과 연결되며, 앱이 꺼져 있으면 첫 명령이 앱을 실행한다고 안내되어 있습니다.

Bases의 지도 뷰도 비슷한 함정이 있어요. 위도·경도 속성과 Maps 커뮤니티 플러그인이 있어야 지도가 표시되므로, .base 파일을 만드는 일과 지도를 띄울 환경을 갖추는 일은 별개로 봐야 합니다.

검수는 구문, 참조, 실제 결과 순으로

각 문서가 무엇을 검사하는지를 기준으로 정리하면 아래 순서가 자연스럽습니다. 저장소 전체에 정해진 단일 공식 절차가 있는 건 아니고, 검사 대상을 헷갈리지 않도록 나눠 본 제안이에요.

1. 스킬 패키지의 메타데이터를 검사합니다. skills-ref validate ./my-skill은 SKILL.md의 메타데이터와 명명 규칙을 확인하며, 생성된 노트나 Bases의 실행 결과는 검사하지 않습니다.
2. 생성된 파일의 구문과 참조를 살핍니다. Bases는 YAML 구문과 함께 참조한 속성·수식이 실제로 존재하는지 확인하세요. Canvas는 JSON 파싱에 더해 ID 고유성, 노드 유형별 필수 필드, fromNode·toNode가 가리키는 노드의 존재까지 점검해야 합니다.
3. 앱 표시나 실제 데이터 실행으로 결과를 확인합니다. Markdown은 Obsidian 읽기 보기에서 렌더링을 보고, Bases는 파일을 열어 뷰가 제대로 표시되는지 살펴보세요. Canvas는 연결 관계와 함께 카드가 겹쳐 읽기 어려운 곳이 없는지도 봐 두는 게 좋습니다.

2단계에서 놓치기 쉬운 게 Bases의 formula.X예요. YAML 파싱이 성공했더라도 그 수식이 정의되어 있는지는 따로 확인해야 합니다.

Knap은 정적 검사로 끝내지 말고 실제 데이터를 넣어 보는 단계까지 가야 해요. knap validate template.md가 보는 건 템플릿 문법, 필터 이름, 정적인 필터 인자까지입니다. 변수가 존재하는지, 실행 시 어떤 값이 들어오는지, 동적인 인자는 어떤지는 확인하지 않아요. 그래서 샘플 데이터로 먼저 렌더링해 보고, 일괄 생성 때는 --dry-run으로 파일을 쓰기 전에 검증과 출력 경로를 확인하는 흐름을 권합니다. CSV 값은 문자열로 취급되기 때문에 숫자나 불리언을 전제로 한 처리가 있다면 샘플 결과부터 살펴보세요. 자세한 검사 범위는 Knap 스킬 문서에 정리되어 있습니다.

"완료"는 검사 결과를 보고 판단하세요

CLI에는 미해결 링크를 조회하는 unresolved, Bases 결과를 확인하는 base:query, 개발 오류와 화면을 살피는 dev:errors·dev:screenshot 같은 명령이 있습니다. 그렇다고 에이전트가 이 명령이나 확인 절차를 매번 알아서 수행한다고 보기는 어려워요.

에이전트가 "파일 생성 완료"라고 보고하면, 그 말보다 어떤 파일을 검사했는지, 참조 오류가 남아 있는지, 화면과 데이터 결과가 의도대로인지를 먼저 확인하세요.

여기서 다룬 지원 범위와 검수 지침은 2026-11-09 기준이며, 특정 커밋에 고정하지 않은 main 브랜치와 온라인 문서를 따릅니다. 문서에 적힌 검수 지침이 곧 여러분 보관함에서의 실행 시험 결과는 아니니, 실제 적용 환경에서 얻은 검사 결과와 표시·실행 증거를 근거로 완료 여부를 판단해야 합니다.