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, making it incomplete for skill selection, and the actions described are too general ('managing') without enumerating specific operations.
Suggestions
Add an explicit 'Use when...' clause, e.g., 'Use when the user asks to create, update, query, or organize content in Notion, or mentions Notion pages, databases, or workspace management.'
Replace the vague 'managing' with specific concrete actions such as 'querying databases, updating page properties, appending blocks, searching content, and archiving pages'.
Include natural trigger term variations users might say, such as 'Notion workspace', 'add to Notion', 'Notion table', or 'Notion integration'.
| 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 for when Claude should select this skill. Per the rubric, a missing 'Use when...' clause caps completeness at 2, and since the 'what' is also only moderately detailed, this scores 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', 'add to Notion', or task-oriented terms like 'query', 'update', 'search'. | 2 / 3 |
Distinctiveness Conflict Risk | The explicit mention of 'Notion API' creates a 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, executable curl examples covering all major Notion operations. Its main weaknesses are the repetitive curl headers inflating token usage, the lack of error handling/validation guidance for API operations, and the monolithic structure that could benefit from splitting reference material into separate files.
Suggestions
Define the curl headers once as a reusable pattern or shell function to reduce repetition across all examples (e.g., `notion_api() { curl -H "Authorization: Bearer $NOTION_KEY" -H "Notion-Version: 2025-09-03" -H "Content-Type: application/json" "$@"; }`)
Add a brief error handling section showing how to check for common API error responses (400, 401, 404, 429 rate limit) and what to do about them
Move the Property Types reference and Key Differences sections to separate files (e.g., PROPERTY_TYPES.md, VERSION_CHANGES.md) and link to them from the main skill
| 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 ~50% of the boilerplate. The property types reference and version differences sections earn their place. | 2 / 3 |
Actionability | Every operation includes a fully executable curl command with proper headers, JSON payloads, and realistic property structures. The property types reference provides copy-paste-ready JSON formats. Setup instructions are concrete with exact file paths and commands. | 3 / 3 |
Workflow Clarity | The setup section has a clear 4-step sequence, and operations are well-organized. However, there are no validation checkpoints — no guidance on checking API responses for errors, handling rate limits, or verifying that page creation succeeded. For an API skill involving data modification, this is a gap. | 2 / 3 |
Progressive Disclosure | The content is well-structured with clear section headers and logical grouping, but it's a fairly long monolithic file. The property types reference and version differences could be split into separate reference files, with the main skill linking to them. No external references are provided. | 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
af8bd5f
- 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.