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 strong skill description that clearly defines its purpose (Notion API interactions) and provides explicit guidance on when to use it. The description covers comprehensive capabilities and includes a clear 'Use when' clause. Minor improvement could be made by adding more natural user trigger terms beyond the technical API terminology.
Suggestions
Add more natural user trigger phrases like 'add to Notion', 'Notion workspace', 'sync with Notion', or 'Notion notes' to capture how users naturally request Notion-related tasks.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: 'reading, creating, updating, or deleting pages, databases, blocks, comments' and covers 'authentication, all available endpoints, pagination, error handling, and best practices.' | 3 / 3 |
Completeness | Clearly answers both what ('comprehensive instructions for interacting with the Notion API via REST calls') 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 terms, plus action verbs like 'reading, creating, updating, deleting' and object types like 'pages, databases, blocks, comments.' However, missing common variations users might say like 'add to Notion', 'Notion workspace', or 'sync with Notion.' | 2 / 3 |
Distinctiveness Conflict Risk | Very clear niche focused specifically on Notion API interactions. The explicit mention of 'Notion' and 'REST calls' makes it highly distinguishable from other API or document management skills. | 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 comprehensive and highly actionable Notion API skill with excellent executable examples and good progressive disclosure through external references. The main weaknesses are some verbosity in reference tables that could be externalized, and missing explicit validation/verification steps after destructive operations. The skill would benefit from trimming redundant information Claude already knows and adding feedback loops for error recovery.
Suggestions
Move the detailed error handling table and request size limits table to a separate reference file to improve conciseness
Add explicit verification steps after destructive operations (e.g., 'After archiving, retrieve the page to confirm archived: true')
Remove explanatory text like 'Data sources are individual tables within a database' that explains concepts Claude can infer from the API structure
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is mostly efficient with good code examples, but includes some unnecessary explanations (e.g., explaining what data sources are, the detailed rate limits table, and the comprehensive error handling table that Claude likely knows). The request size limits table adds bulk that could be referenced externally. | 2 / 3 |
Actionability | Excellent actionability with fully executable curl commands throughout, complete with proper headers and JSON payloads. Every endpoint has copy-paste ready examples with jq piping for output formatting. | 3 / 3 |
Workflow Clarity | The authentication flow is clear with a 3-step priority system, and pagination is well-explained. However, the destructive operations section mentions asking for confirmation but lacks explicit validation/verification steps after operations complete. No feedback loops for error recovery in multi-step processes. | 2 / 3 |
Progressive Disclosure | Well-structured with clear sections and appropriate references to external files (block-types.md, property-types.md, filters-and-sorts.md, rich-text.md). The main skill provides a complete overview while deferring detailed reference material to separate files. | 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
9f7f750
- 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.