최신 AI 에이전트 스킬 21선 6편, 노션·옵시디언·PDF를 에이전트에게 맡기기

5편에서 말을 다듬었다. 6편은 문서에 손을 댄다. 노션은 API로, 옵시디언은 파일로, PDF는 자연어 지시로. 셋 다 에이전트에게 맡기는 건데 방식이 세 개로 갈린다.

이유를 먼저 말하면 이렇다. 노션은 문서가 클라우드에 있어서 API를 타야 하고, 옵시디언 볼트는 그냥 로컬 폴더라 파일 도구로 충분하다. PDF는 둘 다라 래핑한 도구를 쓴다. 대상이 어디 있느냐에 따라 도구가 갈리는 거다.

1. notion (v2.0.0)

productivity 카테고리. community가 만들었다. 단일 스킬이 아니라 두 경로를 담고 있다.

Notion API + ntn CLI: pages, databases, markdown, Workers.

연동 토큰

1. https://notion.so/my-integrations 에서 연동 생성
2. API 키 복사 (ntn_ 또는 secret_ 로 시작)
3. ${HERMES_HOME:-~/.hermes}/.env 에 저장:
   NOTION_API_KEY=ntn_your_key_here
4. 대상 페이지/데이터베이스를 연동에 공유한다
   Notion에서 페이지 메뉴 ... → Connect to → 만든 연동 이름

4번이 이 스킬에서 가장 실전 함정이다. 스킬이 이렇게 적고 있다.

이걸 안 하면 페이지가 존재하는데도 API가 404를 반환한다.

페이지가 있는데 404가 뜬다. 보통은 권한 문제로 해석하고 토큰을 다시 발급받거나 연동을 지었다 새로 만든다. 실제로는 공유 안 한 게 원인이다. 노션 API는 에이전트가 그 페이지를 볼 수 있는지를 404로 안 알려 준다. 존재 여부를 숨기는 설계다.

ntn 설치

curl -fsSL https://ntn.dev | bash
# 또는 (Node 22+, npm 10+ 필요)
npm install --global ntn

ntn --version    # 확인

그리고 여기서도 지시가 있다.

ntn login은 건너뛸 것. 대신 연동 토큰을 쓴다.
브라우저 없이 헤드리스로 동작한다.

export NOTION_API_TOKEN=$NOTION_API_KEY      # ntn이 NOTION_API_TOKEN을 읽는다
export NOTION_KEYRING=0                       # OS 키체인 쓰지 말 것

브라우저 로그인이 필요 없다는 게 이 CLI의 존재 이유다. 서버 환경이나 컨테이너에서 브라우저 로그인은 불가능하다. 키체인도 마찬가지다. 서버에 키체인이라는 개념이 없다. 그래서 NOTION_KEYRING=0으로 파일 기반 인증(~/.config/notion/auth.json)으로 떨어진다.

런타임에 경로 고르기

if command -v ntn >/dev/null 2>&1; then
  # ntn 사용
else
  # curl로 폴백
fi

두 경로를 스킬이 함께 담고 있는 이유다. Windows는 네이티브 ntn이 아직 안 나왔고, WSL2에 깔거나 그냥 HTTP 경로를 쓴다.

파일 업로드가 CLI의 최대 이득

ntn files create < photo.png
ntn files create --external-url https://example.com/photo.png
ntn files list

HTTP로는 3단계가 필요하다. 업로드 생성, 바이트 PUT, 참조. CLI는 이걸 한 줄로 줄였다. 노션에 이미지를 올릴 때 이 차이가 드러난다.

유용한 환경변수도 정리돼 있다.

경로 B: HTTP + curl

Windows 기본값이고 범용 경로다. 모든 요청이 같은 패턴을 쓴다.

curl -s -X GET "https://api.notion.com/v1/..." \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  ...

페이지 생성과 갱신이 마운드다운을 받는다. 에이전트에게 특히 잘 맞는 이유다. 노션의 블록 API를 직접 다루면 중첩 블록 구조를 헤맬아야 하는데, 마운드다운을 넣으면 그게 사라진다.

그리고 페이지를 마운드다운으로 읽는 경로도 있다. 이게 클라이언트 친화적이라는 의미다. 블록 JSON을 파싱하지 않고 곧바로 읽는다.

2. obsidian (v1.0.0)

note-taking 카테고리. Teknium과 Hermes Agent가 함께 만들었다.

Read, search, create, and edit notes in the Obsidian vault.

설명이 짧다. 볼트는 결국 폴더니까. 이 스킬의 설계 철학도 거기서 나온다.

볼트 경로부터

환경변수 관례가 문서화돼 있다.

OBSIDIAN_VAULT_PATH, 예: ${HERMES_HOME:-~/.hermes}/.env
설정 안 돼 있으면 ~/Documents/Obsidian Vault

그리고 바로 함정이 나온다.

파일 도구는 셸 변수를 확장하지 않는다.
$OBSIDIAN_VAULT_PATH가 들어간 경로를 read_file, write_file, patch,
search_files에 넣지 말 것. 볼트 경로를 먼저 해석해서 구체적인 절대 경로를 넘긴다.
볼트 경로에 공백이 들어갈 수 있는데 이것도 셸 명령보다 파일 도구를 쓰게 된 이유다.

이게 옛날 패턴에서 넘어오는 사람들한테 가장 많이 발생하는 사고다. 변수를 그대로 넣으면 파일이 안 보인다. 경로에 공백이 있으면 셸에서는 또 깨진다. 두 문제가 겹쳐서 에이전트가 아무리 고쳐도 안 되는 것처럼 보일 때가 있다. 실제로는 변수 미확장이다.

경로가 아직 모를 때만 terminal을 쓸 수 있다. 한 번 알았다면 다시 파일 도구로 돌아온다.

도구 매핑

스킬이 Shell 명령 대신 파일 도구를 명시적으로 밀어내는 이유가 표에 있다.

- 노트 읽기: read_file. cat보다 우선 (줄 번호와 페이지네이션이 붙는다)
- 노트 목록: search_files (target: "files"). find나 ls보다 우선
- 검색: search_files. grep, find, ls보다 우선
  파일명 검색은 target: "files" + pattern
  내용 검색은 target: "content" + 정규식 + file_glob: "*.md"
- 노트 생성: write_file. 셸 heredoc이나 echo보다 우선 (따옴표 문제 회피, 구조화된 결과 반환)
- 이어붙이기: read_file로 읽고, 안정된 앵커가 있으면 patch로 앵커에 내용 추가
  앵커가 없을 때만 write_file로 전체 재작성
- 부분 편집: patch. 셸 텍스트 치환보다 우선

여기서 진짜 이유를 알 수 있다. cat은 줄 번호가 없어서 나중에 다시 읽기 어렵다. find와 ls는 구조화된 결과를 안 준다. 셸 heredoc은 따옴표 때문에 깨진다. write_file은 깨지지 않고 결과를 준다. 도구 선택이 성능 문제가 아니라 안전성 문제다.

이어붙이기의 두 갈래

앵커가 안정적일 때: patch로 앵커를 (앵커 + 새 내용)으로 교체
전체를 다시 쓰는 게 더 명확할 때: write_file
앵커 없이 단순 추가가 필요할 때: terminal이 가장 명확하고 안전한 선택일 수 있다

스킬이 "명확하고 안전한 선택일 수 있다"고 써놓은 게 실용적이다. 도구를 사양하지 않는다. 셸 heredoc이 저절로 나쁜 것도 아니고, 앵커가 없는데 억지로 patch를 짜는 게 더 나쁠 수 있다.

위키링크

옵시디언은 [[Note Name]] 문법으로 노트를 잇는다. 노트를 만들 때 이걸로 관련 내용을 연결한다.

에이전트가 옵시디언을 쓸 때 이걸 모르면 노트를 Isolated된 파일로 만든다. 사람이 쓰는 knowledge graph가 안 만들어진다. 한 줄이 전부다.

3. nano-pdf (v1.0.0)

productivity 카테고리. community.

Edit text in existing PDFs via natural-language prompts.

PDF를 자연어로 편집한다. 항목 하나에 이걸 누가 만드는지부터 성립할 질문을 안 한다.

설치

uv pip install nano-pdf     # 권장 (Hermes에 이미 있음)
pip install nano-pdf

사용

nano-pdf edit <file.pdf> <page_number> "<지시>"

예시 세 개.

# 1페이지 제목 바꾸기
nano-pdf edit deck.pdf 1 "Change the title to 'Q3 Results' and fix the typo in the subtitle"

# 특정 페이지 날짜 갱신
nano-pdf edit report.pdf 3 "Update the date from January to February 2026"

# 내용 수정
nano-pdf edit contract.pdf 2 "Change the client name from 'Acme Corp' to 'Acme Industries'"

지시를 그냥 그대로 쓴다. "3페이지 날짜 1월부터 2월로"가 아니라 "Update the date from January to February 2026"이다. 영어가 자연스럽다. 도구가 영어로 만들어져 있어서 예시도 영어다.

범위와 주의

- 스캔에서 텍스트 추출은 ocr-and-documents를 참조

skills가 자기 범위를 정확히 선언하고 다른 곳으로 넘긴다. nano-pdf가 구조 작업을claim하지 않는다.

함정 네 개

- 편집 후 항상 결과 PDF를 검증한다 (read_file로 파일 크기 확인하거나 열어본다)
- 도구가 내부적으로 LLM을 쓴다 — API 키가 필요하다 (nano-pdf --help로 설정 확인)
- 텍스트 변경에는 잘 맞는다. 복잡한 레이아웃 수정은 다른 방법이 필요할 수 있다

두 번째가 진짜 조심해야 할 부분이다. 편집 명령이 성공했는데 아무것도 안 바뀌었을 수 있다. LLM이 지시를 오해하거나 대상 텍스트를 못 찾는 경우다. 도구는 성공을 반환하는데 PDF는 그대로다. 그래서 스킬이 "always verify"를 강제한다.

read_file로 파일 크기 확인이라는데, 이건 실제 PDF 내용 검증을 못 한다. 크기가 같으면 모르고 변했다는 뜻이다. 본문을 확인하려면 별도로 읽어야 한다. 이 스킬은 최소한의 검증만 요구하고 끝난다. 그래서 실전에서는 변환 후 직접 열어보는 게 맞다.

이번 편 정리

셋이 문서 작업 전체를 덮는다. 클라우드 문서, 로컬 문서, 그리고 잘 안 바뀌는 형식. 대상의 성격에 따라 도구가 갈리는 게 이 편 요점이다.

앞으로는 마지막 7편에서 로컬 모델을 직접 돌리고 배포하는 쪽으로 넘어간다.