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.
Install with Tessl CLI
npx tessl i github:intellectronica/agent-skills --skill notion-api80
Does it follow best practices?
If you maintain this skill, you can automatically optimize it using the tessl CLI to improve its score:
npx tessl skill review --optimize ./path/to/skillValidation for skill structure
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 articulates both capabilities and usage triggers. It provides specific actions (CRUD operations on various Notion entities) and explicitly states when to use it. The main weakness is that trigger terms could include more natural user language variations beyond the technical API terminology.
| 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...'). | 3 / 3 |
Trigger Term Quality | Includes 'Notion' and 'Notion API' as key terms, plus entity types like 'pages, databases, blocks, comments.' However, missing common user variations like 'workspace', 'note-taking', or file extensions users might mention. | 2 / 3 |
Distinctiveness Conflict Risk | Very specific to Notion API interactions with clear triggers around 'Notion' and specific Notion entities. Unlikely to conflict with other skills due to the explicit Notion focus. | 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 solid, comprehensive API reference skill with excellent actionability through executable curl examples. The main weaknesses are some verbosity in explaining concepts Claude already knows (conventions, data formats) and missing explicit validation workflows for complex operations. The progressive disclosure is well-handled with clear references to supporting documentation.
Suggestions
Remove or condense the 'Base URL and Conventions' section - Claude knows what UUIDs, ISO 8601, and snake_case are
Add explicit validation workflows for multi-step operations (e.g., 'Before bulk updates: 1. Query current state, 2. Validate changes, 3. Execute with confirmation')
Condense the Request Size Limits table into a brief note with a reference to external documentation
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is mostly efficient with good code examples, but includes some unnecessary explanations (e.g., explaining what UUIDs are, what ISO 8601 format is) and the extensive tables/lists could be more condensed. The conventions section explains things Claude already knows. | 2 / 3 |
Actionability | Excellent actionability with fully executable curl commands for every endpoint, complete with proper headers and JSON payloads. Examples are copy-paste ready and cover all major operations. | 3 / 3 |
Workflow Clarity | The skill covers individual operations well but lacks explicit validation workflows. The confirmation requirement for destructive operations is good, but there's no validate-then-proceed pattern for complex multi-step operations like bulk updates or database migrations. | 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 pointing to detailed references for specialized topics. | 3 / 3 |
Total | 10 / 12 Passed |
Validation
81%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 13 / 16 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
description_trigger_hint | Description may be missing an explicit 'when to use' trigger hint (e.g., 'Use when...') | Warning |
metadata_version | 'metadata' field is not a dictionary | Warning |
license_field | 'license' field is missing | Warning |
Total | 13 / 16 Passed | |
- 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.