mirror of
https://github.com/magnus919/agent-skills.git
synced 2026-09-13 04:26:28 +03:00
3256a87bcb
Adds five top-level operational tool skills, one per named tool: - slack: messages, channels, threads, search, files, and webhook signature verification (HMAC-SHA256) via a bounded, stdlib-only slack-cli. - notion: pages, database queries, search, and guarded page updates via notion-cli. - email: transactional email via Twilio SendGrid (send, deliverability bounces/spam reports, Signed Event Webhook verification with a self-contained ECDSA P-256 verifier) via email-cli. - crm: HubSpot CRM records, contact search, and deal pipeline views with guarded stage updates via crm-cli. - stripe: read-only-first balance, payment, and subscription queries with a guarded period-end subscription cancellation via stripe-cli. Each skill ships an executable script (--json output, --limit bounded reads, --dry-run/--yes mutation gate), a human README with the five required sections, a schema-v1 evals/evals.json with six output-quality cases, a dated source index + operations reference, and a deterministic unittest suite run by check-artifacts. All five are indexed in the top-level README and the generated catalogs were regenerated. Eval coverage rises from 78/139 to 83/144. Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
51 lines
3.3 KiB
Markdown
51 lines
3.3 KiB
Markdown
# Notion — Read and Edit Notion from the Terminal
|
|
|
|
Operate Notion without leaving your terminal or your agent's tool loop: retrieve pages, query databases, search across the workspace, and make confirmed property updates.
|
|
|
|
## Why Install This Skill
|
|
|
|
Teams run their operational memory in Notion — runbooks, on-call docs, product trackers, decision logs — and agents have had no bounded way to read it. This skill gives your agent a real read path (page retrieval, database queries, search) and a safe write path: creating a page or updating a property is a guarded mutation that requires a preview and an explicit confirmation, so the agent can answer questions from Notion without ever silently editing shared content.
|
|
|
|
It ships `notion-cli`, a small Python script that speaks the Notion API with no third-party dependencies. Reads are capped (`--limit`), output is clean JSON for the agent or readable text for you, and `--help` works with no token and no network. The script sends the standard `Notion-Version` header and summarizes pages as title + ID + URL instead of dumping raw block trees.
|
|
|
|
## What You Get
|
|
|
|
| Directory | Purpose |
|
|
|---|---|
|
|
| `SKILL.md` | Agent-facing operating contract, mutation gates, and verification boundaries |
|
|
| `references/` | Dated source index and an API operations reference (endpoints, pagination, property types, filters, errors) |
|
|
| `scripts/notion-cli` | Bounded, stdlib-only CLI: pages get/create/update, databases query, search; `--json`, `--limit`, mutations gated by `--dry-run`/`--yes` |
|
|
| `tests/` | 13 deterministic tests against a stub Notion API, covering the mutation gate and read-only contract |
|
|
| `evals/evals.json` | Six output-quality evaluation cases for agent runs |
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# Help works with no token and no network
|
|
notion/scripts/notion-cli --help
|
|
|
|
# Find a page by text (bounded)
|
|
NOTION_TOKEN=secret_... notion/scripts/notion-cli --json search query --query "on-call runbook"
|
|
|
|
# Retrieve one page
|
|
NOTION_TOKEN=secret_... notion/scripts/notion-cli --json pages get --page-id <page-id>
|
|
|
|
# Query a database, capped at 10 rows
|
|
NOTION_TOKEN=secret_... notion/scripts/notion-cli --json --limit 10 databases query --database-id <db-id>
|
|
|
|
# Update a page property: preview first, then confirm
|
|
printf '{"Status": {"select": {"name": "Done"}}}' > props.json
|
|
NOTION_TOKEN=secret_... notion/scripts/notion-cli pages update --page-id <page-id> --properties props.json --dry-run
|
|
NOTION_TOKEN=secret_... notion/scripts/notion-cli pages update --page-id <page-id> --properties props.json --yes
|
|
```
|
|
|
|
## Triggers
|
|
|
|
Load this skill for `notion` operations: "what does the runbook say", reading pages, querying a Notion database (rows, filters), searching pages and databases, creating a page row, or updating a page property with confirmation. Do not load it for building Notion integrations or apps, workspace administration, or other knowledge bases like Confluence.
|
|
|
|
## Requirements
|
|
|
|
- Python 3.9+ for `notion-cli` (stdlib only; `--help` needs nothing else).
|
|
- A Notion integration token (`NOTION_TOKEN`, `secret_...`) with the workspace pages/databases you need **shared with the integration**. Search and database access require the corresponding capabilities in the integration settings.
|
|
- Network access to `api.notion.com` for live reads and writes. Optionally set `NOTION_VERSION` to pin the API version (default `2022-06-28`).
|