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 ./openclaw/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 high-level resource types (pages, databases, blocks), giving it reasonable distinctiveness. However, it lacks a 'Use when...' clause, provides only surface-level action descriptions, and misses natural trigger terms users might employ when requesting Notion-related help.
Suggestions
Add an explicit 'Use when...' clause, e.g., 'Use when the user asks to create, query, or update Notion pages, databases, or blocks, or mentions Notion workspace management.'
List more specific concrete actions such as 'query databases, create pages, update properties, add blocks, search content, archive pages' to improve specificity.
Include additional natural trigger terms like 'Notion workspace', 'Notion wiki', 'Notion integration', or 'Notion table' to improve keyword coverage.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (Notion API) and some actions (creating and managing pages, databases, and blocks), but doesn't list specific concrete actions like querying, updating properties, archiving, or searching. | 2 / 3 |
Completeness | Describes what it does (Notion API for creating/managing pages, databases, blocks) but completely lacks a 'Use when...' clause or any explicit trigger guidance, which per the rubric caps completeness at 2, and the 'what' is also fairly thin, placing this at 1. | 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', 'wiki', or task-related terms users might naturally say. | 2 / 3 |
Distinctiveness Conflict Risk | The mention of 'Notion API' creates a clear niche that is unlikely to conflict with other skills; Notion is a specific product and the API focus further narrows the scope. | 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, actionable API reference skill with fully executable curl examples covering all major Notion API operations. Its main weaknesses are the repetitive curl headers inflating token usage, the lack of workflow guidance for multi-step operations (e.g., search → get ID → create page), and no error handling or validation steps. The version-specific information about data sources vs databases is valuable and well-explained.
Suggestions
Define a reusable curl command template or shell function at the top to eliminate the repeated Authorization/Notion-Version/Content-Type headers from every example, significantly reducing token count.
Add a brief workflow example showing a common multi-step operation (e.g., 'To add a page to a database: 1. Search for the database, 2. Extract data_source_id and database_id from results, 3. Create page using database_id as parent') with validation of API responses.
Move the Property Types reference and Key Differences sections to separate files (e.g., PROPERTY_TYPES.md, VERSION_NOTES.md) and link to them from the main skill to improve progressive disclosure.
| 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 setup could eliminate dozens of repeated lines. The property types reference section is useful but could be more compact. | 2 / 3 |
Actionability | Every operation includes fully executable curl commands with proper headers, JSON payloads, and realistic examples. The setup instructions are concrete (mkdir, echo commands), and property type formats are copy-paste ready. | 3 / 3 |
Workflow Clarity | The setup is clearly sequenced (create integration → copy key → store → share). However, for operations like creating pages in databases, there's no guidance on the workflow of first finding the correct IDs (search → extract ID → use in create). No validation or error handling steps are mentioned for any operations. | 2 / 3 |
Progressive Disclosure | The content is well-organized with clear section headers, but it's a monolithic file with no references to external files. The property types section and version differences section could be split into separate reference files to keep the main skill leaner. | 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
- trpc-group/trpc-agent-go
- Commit
09cce3e
- 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.