notion

Original source / Raw SKILL.md

---
name: notion
description: Work with Notion pages and databases via the official Notion API.
homepage: https://developers.notion.com
metadata:
  clawdbot:
    emoji: 🧠
    requires:
      env:
        - NOTION_API_KEY
    install:
      - id: node
        kind: note
        label: "Requires notion-cli (Node.js) or notion-cli-py (Python). See docs below."
---

# Notion

This skill lets the agent work with **Notion pages and databases** using the official Notion API.

The skill is declarative: it documents **safe, recommended operations** and assumes a local CLI
(`notion-cli`) that actually performs API calls.

## Authentication

- Create a Notion Integration at https://www.notion.so/my-integrations
- Copy the Internal Integration Token.
- Export it as:

```bash
export NOTION_API_KEY=secret_xxx
```

Share the integration with the pages or databases you want to access.
Unshared content is invisible to the API.

## Profiles (personal / work)

You may define multiple profiles (e.g. personal, work) via env or config.

Default profile: personal

Override via:

```bash
export NOTION_PROFILE=work
```

## Pages

**Read page:**

```bash
notion-cli page get <page_id>
```

**Append blocks:**

```bash
notion-cli block append <page_id> --markdown "..."
```

Prefer appending over rewriting content.

**Create page:**

```bash
notion-cli page create --parent <page_id> --title "..."
```

## Databases

**Inspect schema:**

```bash
notion-cli db get <database_id>
```

**Query database:**

```bash
notion-cli db query <database_id> --filter <json> --sort <json>
```

**Create row:**

```bash
notion-cli page create --database <database_id> --props <json>
```

**Update row:**

```bash
notion-cli page update <page_id> --props <json>
```

## Schema changes (advanced)

Always inspect diffs before applying schema changes.

Never modify database schema without explicit confirmation.

Recommended flow:

```bash
notion-cli db schema diff <database_id> --desired <json>
notion-cli db schema apply <database_id> --desired <json>
```

## Safety notes

- Notion API is rate-limited; batch carefully.
- Prefer append and updates over destructive operations.
- IDs are opaque; store them explicitly, do not infer from URLs.


---

## Skill Companion Files

> Additional files collected from the skill directory layout.

### README.md

```markdown
# Notion Skill

This skill enables working with Notion pages and databases via the official Notion API.

## Quick Start

1. Create a Notion Integration at https://www.notion.so/my-integrations
2. Copy the Internal Integration Token
3. Export it: `export NOTION_API_KEY=secret_xxx`
4. Share the integration with pages/databases you want to access

## Features

- Read and create pages
- Append blocks to pages
- Query databases
- Create and update database rows
- Schema inspection and changes (with safety checks)

## Requirements

- `NOTION_API_KEY` environment variable
- `notion-cli` (Node.js) or `notion-cli-py` (Python) - see installation instructions in SKILL.md

## Version

Current version: 0.1.0

This is a declarative skill that documents safe, recommended operations. The actual API calls are performed by a local CLI tool.

```

### _meta.json

```json
{
  "owner": "dimagious",
  "slug": "notion-skill",
  "displayName": "Notion",
  "latest": {
    "version": "1.0.0",
    "publishedAt": 1769524433792,
    "commit": "https://github.com/clawdbot/skills/commit/4da4063e8487f6a6a465fa5703caf4b312ea0c6d"
  },
  "history": []
}

```