notion-cli-skill

An unofficial, vendor-neutral agent skill for using Notion's official ntn CLI to call the Notion API, manage Notion Workers, query data sources, create or update pages, and upload files from the terminal.

This project is not affiliated with, endorsed by, or sponsored by Notion Labs, Inc.

Core Functionality

The skill helps agents perform five main operations:

1. Discover - Inspect live ntn help, endpoint docs, and endpoint specs before choosing command syntax.
2. Authenticate - Prefer NOTION_API_TOKEN when present, otherwise guide users through ntn login or personal access token setup.
3. Call APIs - Build authenticated ntn api requests with inline fields, JSON bodies, query params, headers, and API version overrides.
4. Manage content - Retrieve and update pages, query data sources, and upload or attach files.
5. Operate Workers - Scaffold, deploy, execute, inspect, and manage secrets for Notion Workers.

The skill is intentionally conservative: it avoids printing token values, asks for confirmation before destructive Notion actions, and points agents to live CLI help before relying on remembered syntax. It does not include vendor-specific agent metadata; the portable contract is the SKILL.md file plus the linked references.

Installation & Usage

Install from your GitHub repository after publishing:

npx skills add CaesiumY/notion-cli-skill --skill notion-cli

Once installed, trigger with prompts like:

• Use the Notion CLI to query this data source
• Call the Notion API with ntn
• Upload this file to Notion
• Deploy this Notion Worker
• Create a Notion page from Markdown

The skill expects the official Notion CLI command, ntn, to be available locally. If it is not installed, use the official installer:

curl -fsSL https://ntn.dev | bash

Commands Covered

Area	Commands
Discovery	ntn api ls, ntn api <path> --help, ntn api <path> --docs, ntn api <path> --spec, ntn <command> --help
Authentication	ntn login, ntn logout, ntn doctor
API	ntn api <path> with inline fields, JSON body input, query params, headers, and method overrides
Pages	ntn pages get, ntn pages create, ntn pages update, ntn pages trash
Data sources	ntn datasources query, ntn datasources resolve, direct ntn api v1/data_sources/... calls
Files	ntn files create, ntn files get, ntn files list
Workers	ntn workers new, deploy, list, get, exec, env, sync, runs, webhooks, oauth

Project Structure

notion-cli-skill/
├── .gitignore
├── LICENSE
├── README.md
└── skills/
    └── notion-cli/
        ├── SKILL.md
        └── references/
            ├── api-requests.md
            ├── authentication.md
            ├── cli-reference.md
            ├── datasources.md
            ├── files.md
            └── workers.md

Based On

This skill is based on Notion's official developer documentation:

• Notion CLI documentation index: https://developers.notion.com/llms.txt
• CLI overview: https://developers.notion.com/cli/get-started/overview
• Command reference: https://developers.notion.com/cli/reference/commands
• Workers documentation: https://developers.notion.com/workers/get-started/overview

The repository layout and README structure are modeled after CaesiumY/harness-optimizer, while the skill itself follows a concise progressive-disclosure style for portable agent skills.

License

MIT