Roberto Ansuini

notion-sync

AIエージェントv3.0.2
作者:Roberto Ansuini更新日 2026-09-08全 19 バージョン · 最新版の公開日 2026-09-08@clawhub_robansuini/notion-sync
タスク自動化ワークフロー編成#Notion#Sync#Project Management

AlphaMoatによると、2026-10時点でnotion-syncのダウンロード数は7,791、スター数は7で、累計ダウンロード数で今回のランキング対象AIスキル10,914件中3,562位、AIエージェントでは1,632件中476位です。

一覧の初期表示は累計ダウンロード数順で、スター数順にも並べ替えできます。詳細ページの順位は累計ダウンロード数で計算しています。

ダウンロード数
7791
スター数
7
累計ダウンロード順位
#3,562
全体の上位 33% · AIエージェントの上位 30%
プラットフォームダウンロード数スター数コメント
ClawHub ↗57547-
SkillHub ↗77916—

プラットフォームごとに集計方法と集計時点が異なります。

このスキルでできること

秘密管理の API key で検索、書出し、作成、構造とデータ照会、属性変更、変化の確認を行います。ローカルは作業範囲内に制限し、外部は正確な読書きパスを認可します。一括照会は条件と試行確認が必要で、アーカイブには明示確認があり完全削除ではありません。必要なページだけを共有し、状態を保護して、意図した場合だけ定期化します。

資料公開日 2026-10-27

できること

  • 範囲を絞った照会や同期を準備する

使う場面

  • 認可済みの Notion 接続で操作したいとき

プロンプト例

スキルのドキュメントをもとに生成した例であり、実際の実行結果ではありません。

先に共有ページや構造を調べ、パスと条件を試行確認して、更新やアーカイブ案を示して。

月次の推移

ダウンロード数7791
3328572581222026-03 · ダウンロード数 36592026-05 · ダウンロード数 45862026-06 · ダウンロード数 47762026-07 · ダウンロード数 50292026-08 · ダウンロード数 51812026-09 · ダウンロード数 57112026-10 · ダウンロード数 779126-0326-0926-10
スター数7
6772026-03 · スター数 62026-05 · スター数 62026-06 · スター数 62026-07 · スター数 62026-08 · スター数 62026-09 · スター数 72026-10 · スター数 726-0326-0926-10

2026-09 から集計方法を変更し、同名スキルを作者ごとに分けて集計し、全スキルを対象にしました。破線は変更前の月で、変更後のデータとは直接比較せず、変更をまたぐ増減も計算していません。

月ダウンロード数前月比スター数
2026-107791—7
2026-095711—7
2026-085181+3.0%6
2026-075029+5.3%6
2026-064776+4.1%6
2026-054586—6
2026-033659—6

SKILL.md 原文

作者が公開した元のファイルをテキストのまま表示しています。AlphaMoat による編集や審査はしていません。リンクはクリックできません。コマンドは内容を確認してから実行してください。取得日 2026-10-23。

18 KB・ClawHub v3.0.2
---
name: notion-sync
description: Read, search, export, create, update, monitor, query, inspect, batch-edit, and explicitly archive Notion pages and databases. Use when the user requests Notion content or database operations and a host secret manager can supply NOTION_API_KEY.
homepage: https://github.com/robansuini/agent-skills
license: MIT-0
allowed-tools: Bash, Read, Write, WebFetch, Env
metadata:
  {
    "openclaw":
      {
すべて表示(全 563 行)
        "emoji": "📝",
        "requires": { "bins": ["node"], "env": ["NOTION_API_KEY"] },
        "primaryEnv": "NOTION_API_KEY",
        "network": { "outboundHosts": ["api.notion.com"] },
      },
  }
---

# Notion Sync

Bi-directional sync between markdown files and Notion pages, plus database management utilities for research tracking and project management.

## Security and capability boundary

- Reads `NOTION_API_KEY` from the environment and sends it only to
  `https://api.notion.com`.
- Reads and writes user-selected markdown and watch-state files. Workspace path
  restrictions are enabled by default. Each external path requires an exact,
  mode-specific `--allow-read-path` or `--allow-write-path` authorization.
- Can search, read, create, update, batch-update, inspect, and archive Notion
  content shared with the configured integration.
- Mutating operations run only through an explicitly selected command. Batch
  query updates require a filter, and page archiving additionally requires
  `--confirm-archive`.

## Upgrading

**v3.0 is a breaking security release.** It removes `--token-file`,
`--token-stdin`, and automatic `~/.notion-token` loading. The scripts now use
only `NOTION_API_KEY`, supplied by the host runtime's secret manager.

Read [references/MIGRATION-V3.md](references/MIGRATION-V3.md) before upgrading
from any v1 or v2 release. Keep v2.5.3 pinned until the replacement secret
injection is configured and verified.

## Requirements

- **Node.js** 18 or later
- A **Notion integration token** (starts with `ntn_` or `secret_`)
- A runtime or secret manager that injects `NOTION_API_KEY`

## Credential workflow

Supply `NOTION_API_KEY` through your platform's secret manager. Do not place
the token in chat, source control, command arguments, URLs, or committed `.env`
files. The scripts do not depend on a particular agent runtime.

### OpenClaw protected-secret mode

OpenClaw users should use version 2026.9.1 or later and its protected-secret
egress workflow:

Before the first Notion API operation in a run:

1. Use the OpenClaw `secrets` tool with `action=list`. Inspect metadata only;
   never request or read the credential in chat.
2. If `NOTION_API_KEY` is missing, use `action=request` with:
   - `name: NOTION_API_KEY`
   - `kind: secret`
   - `allowedHosts: ["api.notion.com"]`
   - a one-line reason explaining that notion-sync needs Notion API access
3. If the request is skipped or unavailable, stop and report the blocker.
   Never ask the user to paste the token into chat or a command.
4. Run scripts with Gateway-hosted exec. Do not override, expand, inspect, log,
   or print `NOTION_API_KEY`; OpenClaw injects an opaque sentinel and replaces
   it only for allowed HTTPS requests to `api.notion.com`.
5. If any Gateway-hosted command already ran before the secret was stored or
   changed, start a new agent run so the new secret snapshot is available.

## Setup

1. Go to https://www.notion.so/my-integrations
2. Create a new integration (or use an existing one)
3. Share your Notion pages/databases with the integration through the page's
   **Connections** menu.
4. Save the token as `NOTION_API_KEY` through your runtime's secret manager.

For OpenClaw, save it through the masked prompt or **Settings → Secrets** as a
protected secret allowed only for `api.notion.com`, then enable protected
egress and restart the Gateway:
   ```bash
   openclaw config set secrets.egressProxy.enabled true --strict-json
   openclaw gateway restart
   ```

When OpenClaw supplies a protected sentinel, a missing proxy, CA, host binding,
or compatible Node runtime fails closed. This protected mode requires Node.js
22.21+ in the 22.x line, 24.5+ in the 24.x line, or 25+. Ordinary environment
credentials use the portable direct-HTTPS path on Node.js 18+.

## JSON Output Mode

All scripts support a global `--json` flag.

- Suppresses progress logs written to stderr
- Keeps stdout machine-readable for automation
- Errors are emitted as JSON: `{ "error": "..." }`

Example:
```bash
node scripts/query-database.js <db-id> --limit 5 --json
```

## Path Safety Mode

Scripts that read/write local files are restricted to the current working directory by default.

- Prevents accidental reads/writes outside the intended workspace
- Applies to: `md-to-notion.js`, `add-to-database.js`, `notion-to-md.js`, `watch-notion.js`
- Canonicalizes symlinked path ancestors before enforcement to block workspace-escape writes
- Outside-workspace access requires the exact target path and access mode;
  authorization does not extend to parent, child, or sibling paths

Examples:
```bash
# Default (safe): path must be inside current workspace
node scripts/md-to-notion.js docs/draft.md <parent-id> "Draft"

# Explicit authorization for one outside-workspace output
node scripts/notion-to-md.js <page-id> ~/Downloads/export.md \
  --allow-write-path ~/Downloads/export.md
```

## Core Operations

### 1. Search Pages and Databases

Search across your Notion workspace by title or content.

```bash
node scripts/search-notion.js "<query>" [--filter page|database] [--limit 10] [--json]
```

**Examples:**
```bash
# Search for newsletter-related pages
node scripts/search-notion.js "newsletter"

# Find only databases
node scripts/search-notion.js "research" --filter database

# Limit results (1-100)
node scripts/search-notion.js "AI" --limit 5
```

`--filter` accepts only `page` or `database`; `--limit` must be a positive integer from 1 to 100.

**Output:**
```json
[
  {
    "id": "page-id-here",
    "object": "page",
    "title": "Newsletter Draft",
    "url": "https://notion.so/...",
    "lastEdited": "2026-02-01T09:00:00.000Z"
  }
]
```

### 2. Query Databases with Filters

Query database contents with advanced filters and sorting.

```bash
node scripts/query-database.js <database-id> [--filter <json>] [--sort <json>] [--limit 10] [--json]
```

`--limit` must be a positive integer from 1 to 100.

**Examples:**
```bash
# Get all items
node scripts/query-database.js xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Filter by Status = "Complete"
node scripts/query-database.js <db-id> \
  --filter '{"property": "Status", "select": {"equals": "Complete"}}'

# Filter by Tags containing "AI"
node scripts/query-database.js <db-id> \
  --filter '{"property": "Tags", "multi_select": {"contains": "AI"}}'

# Sort by Date descending
node scripts/query-database.js <db-id> \
  --sort '[{"property": "Date", "direction": "descending"}]'

# Combine filter + sort
node scripts/query-database.js <db-id> \
  --filter '{"property": "Status", "select": {"equals": "Complete"}}' \
  --sort '[{"property": "Date", "direction": "descending"}]'
```

**Common filter patterns:**
- Select equals: `{"property": "Status", "select": {"equals": "Done"}}`
- Multi-select contains: `{"property": "Tags", "multi_select": {"contains": "AI"}}`
- Date after: `{"property": "Date", "date": {"after": "2024-01-01"}}`
- Checkbox is true: `{"property": "Published", "checkbox": {"equals": true}}`
- Number greater than: `{"property": "Count", "number": {"greater_than": 100}}`

### 3. Update Page Properties

Update properties for database pages (status, tags, dates, etc.).

```bash
node scripts/update-page-properties.js <page-id> <property-name> <value> [--type <type>] [--json]
```

**Supported types:** select, multi_select, checkbox, number, url, email, date, rich_text

Long `rich_text` values are automatically split to Notion's 2,000-character per-item limit.

**Examples:**
```bash
# Set status
node scripts/update-page-properties.js <page-id> Status "Complete" --type select

# Add multiple tags
node scripts/update-page-properties.js <page-id> Tags "AI,Leadership,Research" --type multi_select

# Set checkbox
node scripts/update-page-properties.js <page-id> Published true --type checkbox

# Set date
node scripts/update-page-properties.js <page-id> "Publish Date" "2024-02-01" --type date

# Set URL
node scripts/update-page-properties.js <page-id> "Source URL" "https://example.com" --type url

# Set number
node scripts/update-page-properties.js <page-id> "Word Count" 1200 --type number
```

### 4. Batch Update

Batch update a single property across multiple pages in one command.

**Mode 1 — Query + Update:**
```bash
node scripts/batch-update.js <database-id> <property-name> <value> --filter '<json>' [--type select] [--dry-run] [--limit 100]
```

Query mode requires `--filter` so the command cannot update an entire database by accident. Use stdin mode when you already have an explicit page-id list.

**Example:**
```bash
node scripts/batch-update.js <db-id> Status Review \
  --filter '{"property":"Status","select":{"equals":"Draft"}}' \
  --type select
```

**Mode 2 — Page IDs from stdin:**
```bash
echo "page-id-1\npage-id-2\npage-id-3" | \
  node scripts/batch-update.js --stdin <property-name> <value> [--type select] [--dry-run]
```

**Features:**
- `--dry-run`: prints pages that would be updated (with current property value) without writing
- `--limit <n>`: positive integer max pages to process (default `100`)
- Pagination in query mode (`has_more`/`next_cursor`) up to limit
- Rate-limit friendly updates (300ms between page updates)
- Progress and summary on stderr, JSON result array on stdout

### 5. Markdown → Notion Sync

Push markdown content to Notion with full formatting support.

```bash
node scripts/md-to-notion.js \
  "<markdown-file-path>" \
  "<notion-parent-page-id>" \
  "<page-title>" [--json] [--allow-read-path <exact-path>]
```

**Example:**
```bash
node scripts/md-to-notion.js \
  "projects/newsletter-draft.md" \
  "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
  "Newsletter Draft - Feb 2026"
```

**Supported formatting:**
- Headings (H1-H3)
- Bold/italic text
- Links
- Bullet and numbered lists
- Code blocks with syntax highlighting (``` or ~~~ fences)
- Horizontal dividers
- Paragraphs

**Features:**
- Batched uploads (100 blocks per request)
- Automatic rate limiting (350ms between batches)
- Rich text is automatically chunked to Notion's 2000-character limit (including bold/italic/link spans)
- Unclosed fenced code blocks (` ``` ` or `~~~`) at end-of-file are preserved as code blocks
- Fence-like lines with info strings inside code blocks (e.g. ````js`) are preserved as code content
- Returns Notion page URL and ID

**Output:**
```
Parsed 294 blocks from markdown
✓ Created page: https://www.notion.so/[title-and-id]
✓ Appended 100 blocks (100-200)
✓ Appended 94 blocks (200-294)

✅ Successfully created Notion page!
```

### 6. Notion → Markdown Sync

Pull Notion page content and convert to markdown.

```bash
node scripts/notion-to-md.js <page-id> [output-file] [--json] [--allow-write-path <exact-path>]
```

**Example:**
```bash
node scripts/notion-to-md.js \
  "abc123-example-page-id-456def" \
  "newsletter-updated.md"
```

**Features:**
- Converts Notion blocks to markdown
- Preserves formatting (headings, lists, code, quotes)
- Resolves page titles from the actual Notion `title`-type property (even when the property key is custom)
- Optional file output (writes to file or stdout)

### 7. Change Detection & Monitoring

Monitor Notion pages for edits and compare with local markdown files.

```bash
node scripts/watch-notion.js "<page-id>" "<local-markdown-path>" [--state-file <path>] [--json] [--allow-read-path <exact-path>] [--allow-write-path <exact-path>]
```

**Example:**
```bash
node scripts/watch-notion.js \
  "abc123-example-page-id-456def" \
  "projects/newsletter-draft.md"
```

**State tracking:** By default maintains state in `memory/notion-watch-state.json` (relative to current working directory). You can override with `--state-file <path>` (supports `~` expansion):

```bash
node scripts/watch-notion.js "<page-id>" "<local-path>" --state-file ~/.cache/notion-watch-state.json
```

Default state schema:
```json
{
  "pages": {
    "<page-id>": {
      "lastEditedTime": "2026-01-30T08:57:00.000Z",
      "lastChecked": "2026-01-31T19:41:54.000Z",
      "title": "Your Page Title"
    }
  }
}
```

**Output:**
```json
{
  "pageId": "<page-id>",
  "title": "Your Page Title",
  "lastEditedTime": "2026-01-30T08:57:00.000Z",
  "hasChanges": false,
  "localPath": "/path/to/your-draft.md",
  "actions": ["✓ No changes since last check"]
}
```

**Automated monitoring:** Schedule periodic checks using cron, CI pipelines, or any task scheduler:
```bash
# Example: cron job every 2 hours during work hours
0 9-21/2 * * * cd /path/to/workspace && node scripts/watch-notion.js "<page-id>" "<local-path>"
```

The script outputs JSON — pipe it to any notification system when `hasChanges` is `true`.

### 8. Database Management

#### Add Markdown Content to Database

Add a markdown file as a new page in any Notion database.

```bash
node scripts/add-to-database.js <database-id> "<page-title>" <markdown-file-path> [--json] [--allow-read-path <exact-path>]
```

**Examples:**
```bash
# Add research output
node scripts/add-to-database.js \
  xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  "Research Report - Feb 2026" \
  projects/research-insights.md

# Add project notes
node scripts/add-to-database.js \
  <project-db-id> \
  "Sprint Retrospective" \
  docs/retro-2026-02.md

# Add meeting notes
node scripts/add-to-database.js \
  <notes-db-id> \
  "Weekly Team Sync" \
  notes/sync-2026-02-06.md
```

**Features:**
- Creates database page with title property
- Converts markdown to Notion blocks (headings, paragraphs, dividers)
- Handles large files with batched uploads
- Returns page URL for immediate access

**Note:** Additional properties (Type, Tags, Status, etc.) must be set manually in Notion UI after creation.

#### Inspect Database Schema

```bash
node scripts/get-database-schema.js <database-id> [--json]
```

**Example output:**
```json
{
  "object": "database",
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "title": [{"plain_text": "Ax Resources"}],
  "properties": {
    "Name": {"type": "title"},
    "Type": {"type": "select"},
    "Tags": {"type": "multi_select"}
  }
}
```

**Use when:**
- Setting up new database integrations
- Debugging property names/types
- Understanding database structure

#### Archive Pages

```bash
node scripts/delete-notion-page.js <page-id> --confirm-archive [--json]
```

**Note:** This archives the page (sets `archived: true`), not permanent deletion.
The explicit confirmation flag prevents an agent or user from archiving a page
through an incomplete command.

## Common Workflows

### Collaborative Editing Workflow

1. **Push local draft to Notion:**
   ```bash
   node scripts/md-to-notion.js draft.md <parent-id> "Draft Title"
   ```

2. **User edits in Notion** (anywhere, any device)

3. **Monitor for changes:**
   ```bash
   node scripts/watch-notion.js <page-id> <local-path>
   # Returns hasChanges: true when edited
   ```

4. **Pull updates back:**
   ```bash
   node scripts/notion-to-md.js <page-id> draft-updated.md
   ```

5. **Repeat as needed** (update same page, don't create v2/v3/etc.)

### Research Output Tracking

1. **Generate research locally** (e.g., via sub-agent)

2. **Sync to Notion database:**
   ```bash
   node scripts/add-to-database.js <database-id> "Research Output - 2026-03-21" research-output.md
   ```

3. **User adds metadata in Notion UI** (Type, Tags, Status properties)

4. **Access from anywhere** via Notion web/mobile

### Page ID Extraction

From Notion URL: `https://notion.so/Page-Title-abc123-example-page-id-456def`

Extract: `abc123-example-page-id-456def` (last part after title)

Or use the 32-char format: `abc123examplepageid456def` (hyphens optional)

## Limitations

- **Property updates:** Database properties (Type, Tags, Status) must be added manually in Notion UI after page creation. API property updates can be temperamental with inline databases.
- **Block limits:** Very large markdown files (>1000 blocks) may take several minutes to sync due to rate limiting.
- **Formatting:** Some complex markdown (tables, nested lists >3 levels) may not convert perfectly.

## Troubleshooting

**"Could not find page" error:**
- Ensure page/database is shared with your integration
- Check page ID format (32 chars, alphanumeric + hyphens)

**"Module not found" error:**
- Scripts use built-in Node.js https module (no npm install needed)
- Ensure running from the skill's directory (where scripts/ lives)

**Rate limiting:**
- Notion API has rate limits (~3 requests/second)
- Scripts handle this automatically with 350ms delays between batches

## Resources

### scripts/

**Core Sync:**
- **md-to-notion.js** - Markdown → Notion sync with full formatting
- **notion-to-md.js** - Notion → Markdown conversion
- **watch-notion.js** - Change detection and monitoring

**Search & Query:**
- **search-notion.js** - Search pages and databases by query
- **query-database.js** - Query databases with filters and sorting
- **update-page-properties.js** - Update database page properties
- **batch-update.js** - Batch update one property across many pages (query or stdin IDs)

**Database Management:**
- **add-to-database.js** - Add markdown files as database pages
- **get-database-schema.js** - Inspect database structure
- **delete-notion-page.js** - Archive pages

**Utilities:**
- **notion-utils.js** - Shared utilities (error handling, property formatting, API requests)

All scripts use only built-in Node.js modules (https, fs) - no external dependencies required.

### references/

- **API-REFERENCE.md** - Detailed script signatures, options, and utility behavior

AIエージェントの人気スキル

self-improving agentAIエージェント

開発中の学び、エラー、訂正を Markdown ファイルに記録し、再利用やワークスペースの記憶への昇格に備えます。

↓ 160.3万★ 4544pskoett
技能发现·Find SkillsAIエージェント

やりたいことを自然文で伝えると、ローカルとリモートのカタログからスキルを探して推薦するスキルです。

↓ 157.4万★ 1810桂皮
Agent BrowserAIエージェント

AI エージェント向けのブラウザ自動化コマンドラインスキルです。

↓ 122.3万★ 1001Nicolas Kleiber
Self-Improving + Proactive AgentAIエージェント

利用者の訂正と自己点検を層構造の記憶に蓄え、使われ方に応じて昇格や保管を行うスキルです。

↓ 69.6万★ 1622Iván
Proactive AgentAIエージェント

AI エージェントの先回り、作業記憶、振り返りの手順を計画するためのワークスペース設定ガイドです。

↓ 57.9万★ 916halthelobster
Skill CreatorAIエージェント

効果的な Claude スキルの作成・更新ガイドです。

↓ 47.7万★ 485chindden
Skill VetterAIエージェント

第三者のスキルを入れる前に、出所と権限と危険な作りを手順に沿って調べるスキルです。

↓ 44.5万★ 1328spclaudehome
唐朝诗仙李白 · Ai Agent SkillAIエージェント

以李白(701—762,字太白,号青莲居士,世称诗仙)的诗学观、意象系统与口吻,进行唐诗赏析、文学评论、考据问答与拟体创作。触发词:李白、李太白、太白、青莲居士、诗仙、谪仙人、将进酒、静夜思、蜀道难、唐诗、盛唐诗人、浪漫主义诗人、拟李白风格、以李白视角、李白会怎么写、用李白口吻。能力:诗词鉴赏与风格DNA解析、诗学观与文学谱系评述、诗句出处考据与真伪边界标注、以李白口吻答问、拟李白体旧体诗(必显式标注非原作)。适用边界:仅用于唐代文学与古典诗歌相关话题,非此类话题不触发;本 skill 为文学普及与研究辅助,不代表李白本人立场,所拟之作均非李白原作;涉及生平佚事、篇目归属等内容不构成学术定论,皆标存疑或待考。

↓ 43.6万★ 4user_ff4d9420

データ月:2026-10 · ダウンロード数とスター数は公開スキルレジストリ(ClawHub、SkillHub)から月単位で集計しています。詳しくはデータの方法論をご覧ください。