notion

Notion API for creating and managing pages, databases, and blocks.

1.57x

Quality

—

Does it follow best practices?

Impact

99%

1.57x

Average score across 3 eval scenarios

Securityby

Advisory

Suggest reviewing before use

Quality

Content

65%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is highly actionable with complete, executable curl examples and a useful property-type reference, and it is reasonably well organized. It loses points on conciseness due to unisolated version-sensitive content and on workflow clarity for lack of explicit validation checkpoints around mutating operations.

Suggestions

Move version-specific notes (Notion-Version '2025-09-03', data-source-vs-database differences) into a clearly labeled 'Version notes' or 'old patterns' subsection so time-sensitive content doesn't inflate the main flow.

Add explicit validation checkpoints after mutating operations (e.g. after creating a page, GET it to confirm; after a PATCH, re-fetch the block children) to close the feedback loop.

Consider extracting the Property Types table and full endpoint reference into a reference bundle file and linking to it from the body to improve progressive disclosure.

Dimension	Reasoning	Score
Conciseness	The body is mostly efficient with copy-paste curl examples and minimal preamble, but the version-specific material ('2025-09-03', 'data sources vs databases', the dedicated 'Key Differences' section) adds time-sensitive content not isolated in a deprecated/old-patterns section, which works against conciseness.	2 / 3
Actionability	Every common operation ships as a complete, executable curl command with auth and Notion-Version headers, plus a concrete property-type reference table — fully copy-paste ready with no pseudocode.	3 / 3
Workflow Clarity	The Setup steps are sequenced, but query/database operations that mutate or batch state have no explicit validate-then-retry feedback loop (e.g. confirming a created page's id or re-checking after a PATCH), which caps clarity for these destructive/batch-style operations at 2.	2 / 3
Progressive Disclosure	Sections are well organized (Setup, API Basics, Common Operations, Property Types, Key Differences, Notes) with no nested references, but the single-file body inlines the full API reference rather than splitting a detailed reference into a separate bundle file, so it stops short of the one-level-deep ideal.	2 / 3
	Total	9 / 12 Passed

Description

35%

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 correctly identifies the Notion API domain and its core objects but lacks explicit 'Use when...' trigger guidance and natural user keyword coverage, capping completeness and trigger quality. It is moderately specific and reasonably distinct but would benefit from a concrete trigger clause.

Suggestions

Add an explicit 'Use when...' clause naming natural trigger terms, e.g. 'Use when the user wants to create, read, update, or query Notion pages, databases, or blocks, or mentions Notion.'

Replace generic verbs with concrete API actions the user would say (e.g. 'search Notion, query a database, add blocks to a page') to raise trigger term quality.

Tighten the description to third-person action verbs ('Creates, reads, and updates...') to maximize specificity.

Dimension	Reasoning	Score
Specificity	Names the domain (Notion API) and several concrete objects ('pages, databases, and blocks') but only lists managed entities rather than multiple specific actions like create/read/update or query, which is comprehensive but action-implicit.	2 / 3
Completeness	It states what the skill does ('creating and managing pages, databases, and blocks') but has no 'Use when...' clause or explicit trigger guidance, so the 'when' is entirely missing.	2 / 3
Trigger Term Quality	Phrases like 'creating and managing pages, databases, and blocks' are technically accurate but no natural user terms ('Notion pages', 'update a database', 'query a Notion DB') are surfaced; users rarely say 'managing blocks', so natural keyword coverage is weak.	1 / 3
Distinctiveness Conflict Risk	The Notion API niche is fairly distinct, but the wording could still overlap with generic note/document skills since it lacks a clear trigger phrase to disambiguate.	2 / 3
	Total	7 / 12 Passed

Validation

81%

Warnings & errors only

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
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	13 / 16 Passed

Repository: trpc-group/trpc-agent-go
Commit: 737835b

Reviewed: about 6 hours ago

Table of Contents

Discovery Implementation Validation

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.