notion
Notion API for creating and managing pages, databases, and blocks.
71
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/skillEvaluation — 99%
↑ 1.57xAgent success when using this skill
Validation for skill structure
Discovery
40%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
The description identifies a clear niche (Notion API) and lists some capabilities, but suffers from missing explicit trigger guidance ('Use when...') and lacks comprehensive action verbs. The Notion-specific terminology provides good distinctiveness, but the description needs expansion to help Claude know when to select this skill over others.
Suggestions
Add a 'Use when...' clause with trigger phrases like 'Use when the user mentions Notion, wants to create Notion pages, query Notion databases, or manage workspace content'
Expand specific actions to include more concrete verbs: 'query databases', 'update page properties', 'append blocks', 'search content'
Include common user phrasings like 'add to Notion', 'Notion doc', 'Notion workspace', 'sync with Notion'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (Notion API) and some actions (creating, managing pages, databases, blocks), but lacks comprehensive specific actions like 'query databases', 'update properties', or 'append content'. | 2 / 3 |
Completeness | Describes what it does (Notion API operations) but completely lacks a 'Use when...' clause or any explicit trigger guidance for when Claude should select this skill. | 1 / 3 |
Trigger Term Quality | Includes 'Notion', 'pages', 'databases', 'blocks' which are relevant keywords, but misses common variations users might say like 'Notion workspace', 'Notion doc', or task-oriented terms like 'add to Notion', 'create Notion page'. | 2 / 3 |
Distinctiveness Conflict Risk | Clearly targets Notion API specifically with distinct triggers like 'Notion', 'databases', 'blocks' - unlikely to conflict with other skills as Notion is a specific product. | 3 / 3 |
Total | 8 / 12 Passed |
Implementation
79%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a well-crafted API reference skill with excellent actionability and conciseness. The curl examples are complete and immediately usable. However, it lacks error handling guidance and validation steps for API operations, and the content could be better organized across multiple files for a skill of this length.
Suggestions
Add a brief error handling section showing how to interpret common API error responses (401, 404, 429) and recovery steps
Include a validation pattern after create/update operations (e.g., 'Verify success by checking the response status and returned object')
Consider moving Property Types and Key Differences sections to separate reference files (PROPERTIES.md, VERSION_NOTES.md) with links from the main skill
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is lean and efficient, providing only necessary information. It assumes Claude knows what Notion, APIs, and curl are, jumping straight to actionable setup and examples without explaining basic concepts. | 3 / 3 |
Actionability | Every operation includes complete, copy-paste ready curl commands with proper headers and JSON payloads. Property type formats are concrete and immediately usable. | 3 / 3 |
Workflow Clarity | The setup steps are clearly numbered, but the API operations lack validation checkpoints. There's no guidance on error handling, verifying successful operations, or what to do when requests fail. | 2 / 3 |
Progressive Disclosure | Content is well-organized with clear sections, but this is a longer skill (~150 lines) that could benefit from splitting property types and version differences into separate reference files. Everything is inline rather than appropriately distributed. | 2 / 3 |
Total | 10 / 12 Passed |
Validation
72%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 8 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
metadata_version | 'metadata.version' is missing | Warning |
metadata_field | 'metadata' should map string keys to string values | Warning |
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 8 / 11 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.