notion-pilot
Automates Notion operations (CRUD) using a dedicated local script, managing pages, databases, and file uploads.
Install
mkdir -p .claude/skills/notion-pilot && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/11757" && unzip -o skill.zip -d .claude/skills/notion-pilot && rm skill.zipInstalls to .claude/skills/notion-pilot
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
Notion API 통합 스킬. DB/페이지/블록 CRUD, 마크다운 읽기/쓰기, 파일 업로드, 이미지 커버 설정, upsert, 코멘트, 페이지 이동 등 모든 Notion 작업을 notion-api.mjs 모듈로 처리합니다. Use when: (1) 노션에 추가/수정/조회, (2) 노션 DB 생성, (3) 노션 이미지 업로드, (4) 노션 커버 설정, (5) 노션 파일 업로드, (6) Notion API 작업. 트리거: '노션', 'Notion', '노션에', '노션 DB', '노션 페이지', '노션 업로드'.Key capabilities
- →Perform CRUD operations on Notion databases, pages, and blocks
- →Read and write Notion content using Markdown
- →Upload files to Notion
- →Set image covers for Notion pages
- →Create or update Notion pages (upsert)
- →Manage comments and move pages in Notion
How it works
This skill directly calls the Notion API using the `notion-api.mjs` module to handle all Notion operations. It prioritizes Markdown API for page content to save tokens.
Inputs & outputs
When to use notion-pilot
- →Adding tasks to a Notion DB
- →Creating pages from markdown files
- →Uploading files to Notion
About this skill
Notion Pilot 스킬
Notion API를 notion-api.mjs 모듈로 직접 호출하여 DB, 페이지, 블록, 파일 업로드 등 모든 작업을 처리하는 스킬.
Workflow
모든 노션 작업은 아래 순서를 반드시 따른다.
Step 1. config.json 확인
이 스킬 디렉토리 내 config.json을 Read 도구로 확인한다.
config.json이 없는 경우 (최초 실행):
먼저 이 스킬 디렉토리에 빈 토큰으로 config.json을 즉시 생성한다:
{
"token": ""
}
그 다음 사용자에게 아래와 같이 안내한다:
Notion 토큰 설정이 필요합니다. 두 가지 방법 중 선택하세요:
1️⃣ 여기에 토큰을 붙여넣기 (ntn_으로 시작하는 값)
2️⃣ 직접 파일에 입력: ~/.claude/skills/notion-pilot/config.json
토큰 발급: https://www.notion.so/profile/integrations → '새 API 통합' → 토큰 복사
- 사용자가 토큰을 붙여넣으면 → config.json의
token값을 채워준다. - 사용자가 "직접 입력할게" 등으로 응답하면 → config.json 경로를 다시 알려주고 작업을 중단한다.
config.json이 있지만 token이 빈 문자열인 경우:
위와 동일하게 토큰 입력을 안내한다.
config.json이 있고 token이 채워져 있으면 바로 Step 2로 진행한다.
Step 2. 작업 실행
notion-api.mjs 모듈을 import하여 작업을 수행한다.
API 호출 방법
notion-api.mjs 모듈 (유일한 방법)
모든 Notion API 작업에 이 모듈을 사용한다. mcp__notion-mcp__* 도구는 절대 사용하지 않는다. OAuth MCP 토큰 만료 등의 문제가 발생해도 notion-api.mjs로만 작업한다.
import { notion } from 'file:///<이 스킬의 scripts 디렉토리>/notion-api.mjs';
// 검색
const results = await notion.search('키워드', { filter: 'database' });
// DB 생성
const db = await notion.createDatabase(parentPageId, '새 DB', '📋', {
'이름': { title: {} },
'상태': { select: { options: [{ name: '진행중', color: 'blue' }] } },
});
// 페이지 생성 (DB 내) - prop 헬퍼 사용
const page = await notion.createPage(dbId, {
'이름': notion.prop.title('홍길동'),
'상태': notion.prop.status('시작 전'), // status 타입 속성
'분류': notion.prop.select('진행중'), // select 타입 속성
'점수': notion.prop.number(95),
'태그': notion.prop.multiSelect(['A', 'B']),
});
// ── 페이지 본문 읽기/쓰기 (마크다운 우선) ──
// 읽기: 특수 블록도 <callout>, <database> 등 확장 태그로 반환됨 (누락 없음)
const content = await notion.getPageMarkdown(pageId);
// 쓰기: 마크다운 문자열로 본문 전체 교체 (블록 API 대비 토큰 6배 절약)
await notion.updatePageMarkdown(pageId, '## 섹션 제목\n\n본문 내용\n\n- 항목 1\n- 항목 2');
// 블록 API는 마크다운으로 불가능한 세밀한 조작이 필요할 때만 사용
await notion.appendBlocks(pageId, [
notion.block.callout('안내', '📝', 'blue_background'),
notion.block.toDo('할 일 항목', false),
notion.block.toggle('토글 제목', [notion.block.paragraph('토글 내부')]),
notion.block.code('console.log("hi")', 'javascript'),
]);
// ※ appendBlocks는 rich_text의 text 객체 안에 잘못 넣은 annotations를
// rich_text 아이템 최상위로 자동으로 옮긴 뒤 전송한다.
// 하위 블록 전체 조회 (100개 넘는 블록도 자동 페이지네이션, 평탄 배열 반환)
const allBlocks = await notion.getBlocksAll(pageId);
// ── 마크다운 쓰기 시 특수 블록 레퍼런스 ──
// ✅ 읽기/쓰기 모두 지원:
//
// [callout] 반드시 아래 형식 준수 — 태그와 내용이 별도 줄, 내용은 탭(\t) 들여쓰기:
// <callout icon="📌">
// 한 줄 내용
// </callout>
// <callout icon="📌" color="blue_bg">
// 멀티라인 내용
// 두 번째 줄 (탭 들여쓰기 필수)
// </callout>
// ※ 색상 단축키: blue_bg, green_bg, yellow_bg, orange_bg, red_bg, purple_bg, pink_bg, gray_bg
// ⚠️ 금지: <callout icon="📌">내용</callout> (한 줄 인라인 형식은 단순 텍스트만 가능)
// ⚠️ 금지: 내용에 빈 줄(\n\n) 포함 — 빈 줄 대신 탭+빈줄(\t\n) 사용
//
// [toggle/details] 반드시 아래 형식 준수 — 내용은 탭(\t) 들여쓰기:
// <details>
// <summary>토글 제목</summary>
// 내용 (탭 들여쓰기 필수)
//
// 빈 줄도 탭+빈줄(\t\n\t) 형태로
// </details>
// ⚠️ 금지: <details><summary>제목</summary>내용</details> (한 줄 인라인 형식 — 파싱 실패)
//
// > 인용문 (quote)
// --- (divider)
// - [ ] 미완료 / - [x] 완료 (to_do)
// | 헤더 | ... | (table)
// ```lang ... ``` (code)
// $`E=mc^2`$ (인라인 수식)
// $$\nE=mc^2\n$$ (수식 블록)
//
// ⚠️ 읽기전용 (쓰기 불가, 블록 API로 대체):
// bookmark → 읽으면 <unknown alt="bookmark"/> 로 표시
// embed → 읽으면 <unknown alt="embed"/> 로 표시
// synced_block → 블록 API 필수
// DB 전체 조회 (자동 페이지네이션)
const allPages = await notion.queryAll(dbId);
// ── 저수준 API 호출 (call) ──
// 시그니처: notion.call(method, path, body?)
// - method: 'GET' | 'POST' | 'PATCH' | 'DELETE'
// - path: 슬래시(/)로 시작하는 API 경로 (예: '/pages/PAGE_ID')
// - body: POST/PATCH 시 요청 본문 (선택)
// ⚠️ queryAll/createPage 등 고수준 함수는 DB ID → DS ID 자동 변환을 하지만,
// call()은 자동 변환하지 않으므로 DS ID가 필요한 엔드포인트에서는 직접 DS ID를 사용해야 한다.
const page = await notion.call('GET', '/pages/PAGE_ID');
const children = await notion.call('GET', '/blocks/BLOCK_ID/children?page_size=100');
await notion.call('PATCH', '/pages/PAGE_ID', { in_trash: true });
// 블록을 특정 위치에 삽입: `after` 파라미터는 폐기됨(2026-03-11) → `position` 객체 사용
await notion.call('PATCH', '/blocks/PARENT_ID/children', {
position: { type: 'after_block', after_block: { id: 'BLOCK_ID' } }, // 시작/끝: { type:'start' } / { type:'end' }(기본)
children: [ /* 블록 배열 */ ],
});
// 배치 처리 (동시성 15)
await notion.batch(items, async (item) => {
await notion.createPage(dbId, { '이름': notion.prop.title(item.name) });
});
// Upsert (단건)
const result = await notion.upsertPage(dbId, '이름', 'title', '홍길동', {
'이름': notion.prop.title('홍길동'),
'점수': notion.prop.number(95),
});
// Bulk Upsert (대량, queryAll 캐시 + 동시성 15)
const stats = await notion.bulkUpsert(dbId, '이름', [
{ matchValue: '홍길동', properties: { '이름': notion.prop.title('홍길동'), '점수': notion.prop.number(100) } },
]);
// 파일 업로드 → 페이지 커버 설정 / 이미지 블록 추가
await notion.setCover(pageId, 'C:/path/to/cover.webp');
await notion.addImageBlock(pageId, 'C:/path/to/photo.png');
// URL에서 다운로드 → Notion 업로드 (실패 시 null)
const uploadId = await notion.uploadFromUrl('https://example.com/img.jpg');
// 로컬 파일 업로드만 (ID 반환). 업로드 완료(status 'uploaded')까지 확인한 뒤 ID를 돌려준다.
// 지원 확장자: 이미지(webp/png/jpg/gif/svg), pdf, mp4, mp3, zip, html
const id = await notion.uploadFile('C:/path/to/file.pdf');
// 파일 속성(files)에 첨부 + 정말 붙었는지 확인 (실패하면 새로 업로드해 1회 재시도, 그래도 안 되면 에러)
// ⚠️ files 속성 첨부는 uploadFile + updatePage 직접 조합 대신 이 함수를 쓴다.
// 완료 확인 없이 붙이면 저장 직후에는 보이다가 1시간 뒤 첨부만 사라질 수 있다.
const att = await notion.attachFileToProperty(pageId, '첨부파일', 'C:/path/to/자료.zip');
// → { uploadId, entryType: 'file', status: 'uploaded', expiry_time: null, url, bytes }
// 첨부 재확인: 실제로 내려받아 바이트 수까지 대조 (첨부 직후 + 몇 분 뒤 두 번 확인 권장)
const check = await notion.verifyFileProperty(pageId, '첨부파일', { expectBytes: att.bytes });
// → { count, files: [{ name, type, ok, bytes, ... }], ok: true|false }
// 업로드 객체 상태 조회 (status, expiry_time 등)
const fu = await notion.getFileUpload(id);
// 코멘트
await notion.createComment(pageId, '코멘트 내용');
const comments = await notion.listComments(pageId);
// 페이지 이동
await notion.movePage(pageId, { page_id: targetPageId });
주의사항:
- 크리덴셜은 모듈이
config.json에서 자동 로드 - API 버전
2026-03-11(DB ID → DS ID 자동 변환 내장) createDatabase는 요청한 속성이 하나라도 만들어지지 않으면 에러를 낸다 (조용히 빠진 채 넘어가지 않음)- Formula에서 다른 Formula/Rollup 참조 시
{{notion:block_property:PROP_ID:...}}내부 형식 필요 (prop() 불가)
실패 시 자가 수복 프로토콜
모듈 함수 호출이 실패하면 아래 순서를 따른다. MCP 폴백은 절대 하지 않는다.
- 에러 패턴 가이드 조회 — 아래 표에서 에러 코드+메시지 패턴을 먼저 확인
- 가이드에 있으면 — 해당 해법을 즉시 적용하여 재시도
- 가이드에 없으면 — 모듈을 import하되, 실패한 부분만
notion.call()로 우회하는 인라인 스크립트 작성 - 우회 성공 시 — 우회 코드를
notion-api.mjs에 반영하고, 새 패턴을 아래 표에 추가
에러 패턴 가이드
| 코드 | 메시지 패턴 | 원인 | 해법 |
|---|---|---|---|
| 400 | body.parent.database_id should be a string | createPage에 객체를 넘김 | 첫 인자로 DB ID 문자열만 넘긴다: createPage('db-id', { props }) |
| 400 | text.annotations should be not present | annotations를 text 객체 안에 넣음 | annotations는 rich_text 아이템 최상위에 배치: { text: { content: '...' }, annotations: { bold: true } } (appendBlocks는 자동 교정함) |
| 400 | rich_text should be an array | rich_text에 문자열을 넣음 | rich_text: [{ text: { content: '...' } }] 배열 형태 필수 |
| 400 | Could not find property | DB 속성명 오타 | notion.prop.* 헬퍼 사용 + getDatabase()로 실제 속성명 확인 |
| 400 | body.children[N] 관련 | 블록 구조 오류 | notion.block.* 헬퍼 사용. 직접 JSON 구성 시 Notion API 블록 스펙 확인 |
| 404 | Could not find database | DB ID가 DS ID로 변경됨 | 자동 폴백 작동. _dsCache에 매핑 저장됨 |
| 404 | Could not find page/block | Integration에 해당 페이지가 공유되지 않음 | 노션 페이지 우측 상단 ··· → 연결 → 만든 Integration 선택 |
| 401 | API token is invalid | 토큰 만료/오입력 | 이 스킬 폴더의 config.json 토큰 교체 |
| 429 | Rate limited | 요청 과다 | notion.batch() 동시성 15 사용. 자동 재시도 대기 |
| 200 | (사일런트) createDatabase 후 properties 없음 | API 2026-03-11에서 POST /databases의 properties 파라미터가 무시됨 | 모듈에서 처리됨: DB 생성 → data_sources[0].id 추출 → PATCH /data_sources/{dsId}로 properties 추가. 기본 'Name' 속성은 title 타입 속성명으로 자동 rename. 그래도 빠진 속성이 있으면 에러 |
| 400 | body.archived should be not present | 페이지/DB 휴지통 처리에 { archived: true } 사용 (구 필드명) | API 2026-03-11부터 in_trash로 변경됨. notion.call('PATCH', '/pages/ID', { in_trash: true }) 사용. 복원은 { in_trash: false }. 응답 객체에서도 response.in_trash를 읽는다 |
| 400 | filename has an extension that is not supported for the File Upload API | 폰트(.ttf/.otf/.woff/.woff2) 등 미지원 확장자 업로드 | File Upload API는 image/audio/video/document(.pdf/.json/.txt) + .zip만 허용. 폰트 등은 개별 .zip으로 묶어 업로드하고 attachFileToProperty()로 files 속성에 첨부 |
| 400 | content type application/octet-stream is not supported for the File Upload API | 모듈의 MIME_MAP에 없는 확장자 → octet-stream 폴백, Notion이 거부 | notion-api.mjs의 MIME_MAP에 해당 확장자의 정확한 MIME 추가(.zip→application/zip 등). octet-stream은 거부됨 |
| 400 | body.after should be not present | 블록 삽입 위치 지정에 after 사용 (폐기됨) | API 2026-03-11부터 after → position 객체로 변경. 특정 블록 뒤 삽입: call('PATCH','/blocks/PARENT_ID/children', { position:{ type:'after_block', after_block:{ id:BLOCK_ID } }, children:[...] }). 시작/끝: { type:'start' } / { type:'end' }(기본) |
| — | (사일런트) 파일 첨부가 며칠 뒤 사라짐 | 업로드가 pending인 채로 첨부 → 1시간 안에 완료되지 않으면 노션이 파일을 회수 | 모듈에서 처리됨: uploadFile()이 완료 상태를 확인한다. files 속성은 attachFileToProperty()로 붙이고 verifyFileProperty()로 재확인 |
새로운 에러 패턴을 발견할 때마다 이 표에 추가한다.
토큰 절약 규칙
- 페이지 본문은 마크다운 API 우선: 읽기
getPageMarkdown(), 쓰기updatePageMarkdown(). 특수 블록도 확장 태그로 보존됨. 블록 API 대비 읽기 20배, 쓰기 6배 토큰 절약. - 블록 API는 세밀한 조작이 필요할 때만: 특정 블록 하나만 수정/삭제, 블록 순서 조작 등.
- 여러 페이지 작업 시
notion.batch()로 동시성 15 병렬 처리. - 전체 조회 시
notion.queryAll()로 자동 페이지네이션. - Upsert 전략 선택: 10건 미만 →
upsertPage(), 10건 이상 →bulkUpsert(). - 하위 블록 전체 조회 시
notion.getBlocksAll()로 자동 페이지네이션 (getBlocks()는 첫 100개만).
헬퍼 레퍼런스
notion.block.* — 블록 빌더
| 헬퍼 | 인자 | Notion 블록 타입 |
|---|---|---|
paragraph(text, {link?, color?}) | 텍스트, 옵션 |
Content truncated.
When not to use it
- →The task does not involve Notion API operations
- →You intend to use `mcp__notion-mcp__*` tools
Limitations
- →Requires a Notion API token
- →Must use `notion-api.mjs` module for all operations
- →Does not use `mcp__notion-mcp__*` tools
How it compares
This skill directly interacts with the Notion API via a dedicated module, offering token efficiency and specific handling for Markdown content, unlike relying on general MCP tools.
Compared to similar skills
notion-pilot side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| notion-pilot (this skill) | 0 | 5mo | Review | Intermediate |
| notion-knowledge-capture | 10 | 1y | No flags | Intermediate |
| slack-memory-store | 1 | 9mo | Review | Intermediate |
| diary | 0 | 7mo | Review | Advanced |
Try saying
Example prompts that trigger this skill in your AI assistant.
You might also like
notion-knowledge-capture
makenotion
Transforms conversations and discussions into structured documentation pages in Notion. Captures insights, decisions, and knowledge from chat context, formats appropriately, and saves to wikis or databases with proper organization and linking for easy discovery.
slack-memory-store
krafton-ai
Comprehensive memory storage system for AI employees in IT companies who communicate via Slack. Automatically classifies and stores diverse information types (Slack messages, Confluence docs, emails, meetings, projects, decisions, feedback) in an organized folder structure with efficient indexing and retrieval. Use when managing or searching employee memory, storing conversations, documenting decisions, tracking projects, or organizing any work-related information.
diary
Anhvu1107
ALWAYS use this when the request matches Diary: Unified Diary System: A context-preserving automated logger for multi-project development.
session-review
philoserf
Wraps up a session with two outputs — a sweep into the auto-memory system to preserve reusable insights for future Claude sessions, and a human-readable recap saved to the Obsidian notes vault. Use for retrospectives, debriefs, post-mortems, or end-of-session reflection.
gtd
Gerstep
Autonomous task execution from GTD.md items. Use when processing GTD tasks, call prep, outreach, or podcast preparation.
harnesscp-memory
LSDIPPOLLC
>