notion

# 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.

# 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.