---
title: "최신 AI 에이전트 스킬 21선 6편, 노션·옵시디언·PDF를 에이전트에게 맡기기"
date: 2026-10-01
model: hermes-agent
category: guide
summary: 에이전트 스킬 21선 중 문서 작업 3편이다. 노션 API와 CLI, 옵시디언 볼트, PDF 자연어 편집을 정리한다.
tags: agent-skills, notion, obsidian, pdf, guide
author_type: human
---

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

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

## 1. notion (v2.0.0)

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

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

### 연동 토큰

```text
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번이 이 스킬에서 가장 실전 함정이다. 스킬이 이렇게 적고 있다.

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

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

### ntn 설치

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

ntn --version    # 확인
```

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

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

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

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

### 런타임에 경로 고르기

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

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

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

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

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

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

| 변수 | 효과 |
| --- | --- |
| `NOTION_API_TOKEN` | 인증 토큰 (키체인보다 우선) |
| `NOTION_KEYRING=0` | `~/.config/notion/auth.json` 파일 기반 자격증명 |
| `NOTION_WORKSPACE_ID` | 워크스페이스 선택 프롬프트 생략 |

### 경로 B: HTTP + curl

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

```bash
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가 함께 만들었다.

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

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

### 볼트 경로부터

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

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

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

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

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

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

### 도구 매핑

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

```text
- 노트 읽기: 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`은 깨지지 않고 결과를 준다. 도구 선택이 성능 문제가 아니라 안전성 문제다.

### 이어붙이기의 두 갈래

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

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

### 위키링크

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

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

## 3. nano-pdf (v1.0.0)

`productivity` 카테고리. community.

```text
Edit text in existing PDFs via natural-language prompts.
```

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

### 설치

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

### 사용

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

예시 세 개.

```bash
# 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"이다. 영어가 자연스럽다. 도구가 영어로 만들어져 있어서 예시도 영어다.

### 범위와 주의

```text- 구조적 작업(병합, 분할, 폼, 워터마크, 생성)은 pdf 스킬을 참조
- 스캔에서 텍스트 추출은 ocr-and-documents를 참조
```

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

### 함정 네 개

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

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

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

## 이번 편 정리

| 스킬 | 버전 | 하는 일 |
| --- | --- | --- |
| notion | 2.0.0 | 연동 토큰 + ntn CLI 또는 curl, 페이지·DB·마운드다운 |
| obsidian | 1.0.0 | 파일 도구로 볼트 읽기·검색·생성·편집, 위키링크 |
| nano-pdf | 1.0.0 | 자연어 지시로 PDF 텍스트 편집 |

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

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