notion-api
This skill provides comprehensive instructions for interacting with the Notion API via REST calls. This skill should be used whenever the user asks to interact with Notion, including reading, creating, updating, or deleting pages, databases, blocks, comments, or any other Notion content. The skill covers authentication, all available endpoints, pagination, error handling, and best practices.
86
78%
Does it follow best practices?
Impact
100%
1.16xAverage score across 3 eval scenarios
Risky
Do not use without reviewing
Optimize this skill with Tessl
npx tessl skill review --optimize ./skills/notion-api/SKILL.mdQuality
Discovery
85%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is a solid description that clearly communicates both what the skill does and when it should be used. It lists specific actions and Notion-specific entities, making it distinctive. Minor improvements could include more natural user trigger terms and slightly less verbose phrasing, as the opening is somewhat padded with 'comprehensive instructions.'
Suggestions
Add more natural user trigger terms like 'Notion workspace', 'Notion integration', 'query Notion', or 'add to Notion' to capture casual user phrasing.
Trim filler phrases like 'This skill provides comprehensive instructions for' — start directly with actions like 'Interacts with the Notion API via REST calls to read, create, update, or delete...'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: 'reading, creating, updating, or deleting pages, databases, blocks, comments' and mentions authentication, endpoints, pagination, error handling, and best practices. | 3 / 3 |
Completeness | Clearly answers both 'what' (interacting with Notion API via REST calls, covering authentication, endpoints, pagination, error handling) and 'when' ('whenever the user asks to interact with Notion, including reading, creating, updating, or deleting pages, databases, blocks, comments, or any other Notion content'). | 3 / 3 |
Trigger Term Quality | Includes 'Notion' and 'Notion API' as key trigger terms, plus action verbs like 'reading, creating, updating, deleting' and object types like 'pages, databases, blocks, comments.' However, it misses common user variations like 'Notion workspace', 'Notion integration', or casual phrasing like 'add to Notion' or 'query Notion database.' | 2 / 3 |
Distinctiveness Conflict Risk | Clearly scoped to Notion API interactions via REST calls, which is a distinct niche unlikely to conflict with other skills. The mention of specific Notion entities (pages, databases, blocks, comments) further narrows the scope. | 3 / 3 |
Total | 11 / 12 Passed |
Implementation
72%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a thorough, well-organized API reference skill with excellent actionability—every endpoint has executable curl examples. Its main weakness is verbosity from repeating full auth headers in every example and lacking explicit validation workflows for multi-step operations. The progressive disclosure is well done with clear references to supplementary files.
Suggestions
Reduce repetition by defining the auth headers once (e.g., as a shell variable or noting 'all requests use the standard headers above') rather than repeating them in every curl example—this could cut the file by 30%+.
Add explicit verification steps after mutating operations (e.g., 'After creating a page, retrieve it to confirm success and capture the returned ID') to improve workflow clarity for multi-step tasks.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is comprehensive but quite long (~400+ lines). While most content is actionable API examples rather than fluff, there's some redundancy in repeating the same auth headers in every single curl example. A variable or shorthand could reduce this significantly. The conventions section and error table are useful but add bulk. | 2 / 3 |
Actionability | Every endpoint includes fully executable curl commands with proper headers, JSON payloads, and jq piping. The examples are copy-paste ready with clear placeholder values (e.g., {page_id}). Authentication verification, pagination, and all CRUD operations are covered with concrete commands. | 3 / 3 |
Workflow Clarity | The skill includes a good confirmation step for destructive operations and mentions pagination iteration steps, but lacks explicit validation/verification workflows. For example, after creating or updating a page, there's no 'verify the result' step. The authentication section has a verification step, but multi-step workflows like 'create database then add pages' lack sequenced guidance with checkpoints. | 2 / 3 |
Progressive Disclosure | The skill is well-structured with clear sections and appropriately delegates detailed reference material (block types, property types, filters/sorts, rich text) to separate files with clear one-level-deep references. The main file serves as a comprehensive but navigable overview. | 3 / 3 |
Total | 10 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- Repository
- intellectronica/agent-skills
- Commit
9b0e00a
- Reviewed
Table of Contents
Is this your skill?
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.