notion
Notion API for creating and managing pages, databases, and blocks.
67
52%
Does it follow best practices?
Impact
99%
1.57xAverage score across 3 eval scenarios
Advisory
Suggest reviewing before use
Optimize this skill with Tessl
npx tessl skill review --optimize ./skills/notion/SKILL.mdQuality
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 domain (Notion API) and lists the main resource types (pages, databases, blocks), giving it good distinctiveness. However, it lacks explicit trigger guidance ('Use when...'), uses the vague verb 'managing' instead of enumerating specific operations, and misses common user-facing trigger terms. It needs both more specific actions and explicit usage triggers to be effective for skill selection.
Suggestions
Add a 'Use when...' clause with natural trigger terms, e.g., 'Use when the user wants to create, update, query, or search Notion pages, databases, or blocks, or mentions Notion integration.'
Replace the vague 'managing' with specific actions like 'querying, updating, archiving, searching, and appending content to'.
Include common user phrasing variations such as 'add to Notion', 'Notion workspace', 'Notion database query', or 'create a Notion page'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (Notion API) and some actions (creating and managing pages, databases, and blocks), but 'managing' is somewhat vague and doesn't enumerate specific operations like updating, querying, archiving, or searching. | 2 / 3 |
Completeness | Describes what the skill does but completely lacks a 'Use when...' clause or any explicit trigger guidance, which per the rubric should cap completeness at 2, and since the 'what' is also only moderately detailed, this falls to a weak 2 at best — but the total absence of 'when' guidance warrants a score closer to 1. Capping at 2 per rubric, but the 'what' is also thin. Scoring 1 because both what and when are weak. | 1 / 3 |
Trigger Term Quality | Includes 'Notion', 'pages', 'databases', and 'blocks' which are relevant keywords, but misses common user variations like 'Notion workspace', 'Notion integration', 'add to Notion', or task-specific terms like 'query', 'update', 'search'. | 2 / 3 |
Distinctiveness Conflict Risk | The mention of 'Notion API' creates a very clear niche that is unlikely to conflict with other skills. Notion is a specific product, making this highly distinguishable. | 3 / 3 |
Total | 8 / 12 Passed |
Implementation
64%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, highly actionable API reference skill with complete curl examples for all common Notion operations. Its main weaknesses are the repetitive curl headers inflating token count, and the lack of error handling/validation guidance for API operations that modify data. The version-specific differences section is a valuable addition that addresses a real pain point.
Suggestions
Define the curl headers once as a reusable pattern or shell function to eliminate repetition across all examples, significantly reducing token count.
Add a brief error handling section or validation notes (e.g., check for 200 status, common error codes like 404 for unshared pages, 429 for rate limits) to improve workflow clarity for destructive/write operations.
Consider splitting the property types reference and version differences into a separate reference file, keeping SKILL.md focused on the most common operations with links to detailed references.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is mostly efficient with executable examples, but the repeated curl headers across every example add significant redundancy. A single template or variable approach would save many tokens. The property types reference and version differences sections are useful but could be tighter. | 2 / 3 |
Actionability | Every operation includes a complete, copy-paste-ready curl command with proper headers, JSON payloads, and realistic property structures. The property types reference provides exact JSON formats. Setup instructions are concrete with specific file paths and commands. | 3 / 3 |
Workflow Clarity | The setup steps are clearly sequenced (1-4), and individual operations are clear. However, there are no validation checkpoints — no guidance on checking API responses for errors, handling rate limits, or verifying that operations succeeded. For an API skill involving data creation/modification, error handling guidance would strengthen this. | 2 / 3 |
Progressive Disclosure | The content is well-organized with clear section headers and a logical progression from setup to basics to operations to reference. However, it's a fairly long monolithic file (~130 lines of content) with no references to external files for advanced topics like pagination, error handling, or complex block types that could benefit from separate documentation. | 2 / 3 |
Total | 9 / 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 | |
- Repository
- Hung-Reo/hungreo-openclaw
- Commit
e893157
- 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.