notion

Notion CLI/API for pages, Markdown content, data sources, files, comments, search, Workers, and raw API calls.

Quality

73%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/notion/SKILL.md

Quality

Content

76%Weight 40%Scale 1-5

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

The body is a lean, highly actionable CLI reference: every section is concrete, executable commands with a sensible curl fallback and well-flagged version/deprecation notes. Its main weaknesses are the absence of validation checkpoints around destructive operations (trash, in_trash) and a stray migration-metadata section that adds noise.

Suggestions

Add a verification step before destructive operations, e.g. run 'ntn pages get <page-id>' to confirm the target page before 'ntn pages trash <page-id> --yes'.

Remove the 'PilotDeck Migration Note' section — it is review metadata, not skill guidance, and consumes tokens without aiding usage.

Consider moving the raw-API input syntax and version notes into a references file so SKILL.md stays a lean overview.

Dimension	Reasoning	Score
Conciseness	The body is lean and command-first with time-sensitive version info properly isolated in a 'Version notes' section, but the 'PilotDeck Migration Note' section is review/migration metadata that earns no tokens for skill usage.	4 / 5
Actionability	Fully executable, copy-paste-ready commands throughout — ntn setup, pages, datasources, raw API calls with input syntax, file uploads, workers, and a complete curl fallback with headers — covering the common cases.	5 / 5
Workflow Clarity	Sections are clearly organized per task area, but destructive operations ('ntn pages trash <page-id> --yes', PATCH 'in_trash:=true') lack validation/verification steps; the rubric caps workflow clarity at 3 for destructive workflows without validation.	3 / 5
Progressive Disclosure	No bundle files exist and the single-file structure is well-organized with clear per-capability sections; minor gaps in that sections like raw-API input syntax and version notes could live in a separate reference file to keep the overview even leaner.	4 / 5
	Total	16 / 20 Passed

Description

70%Weight 40%Scale 1-5

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 is specific and clearly distinguishes the Notion niche, listing many capability areas, but it is a noun inventory rather than a statement of actions and contains no 'Use when' trigger guidance. Adding an explicit trigger clause and the natural synonym 'databases' would materially improve it.

Suggestions

Add an explicit trigger clause, e.g. 'Use when working with Notion pages, databases, or workspace content, or when the user mentions Notion.'

Include the natural synonym 'databases' alongside 'data sources' since users typically say 'Notion database'.

Convert a few noun listings into concrete actions (e.g. 'create and update pages, query databases, upload files') to sharpen the capability statement.

Dimension	Reasoning	Score
Specificity	Lists several specific capability areas ('pages, Markdown content, data sources, files, comments, search, Workers, and raw API calls'), but these are objects/domains rather than concrete actions — no verbs like 'create', 'query', or 'update' — so it falls between the 3 and 5 anchors.	4 / 5
Completeness	The 'what' is clear (CLI/API capabilities enumerated), but there is no 'Use when...' clause or equivalent explicit trigger guidance, which the rubric caps at 3.	3 / 5
Trigger Term Quality	Good natural-keyword coverage ('Notion', 'pages', 'comments', 'search', 'files', 'Markdown'), but misses common user synonyms — users say 'Notion database' rather than 'data sources', and terms like 'blocks', 'notes', or 'workspace' are absent.	4 / 5
Distinctiveness Conflict Risk	'Notion CLI/API' anchors a clear niche with distinct triggers; generic nouns like 'pages' and 'files' are contextualized by Notion, so conflict risk with other skills is minimal.	5 / 5
	Total	16 / 20 Passed

Validation

93%

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 — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: OpenBMB/PilotDeck
Path: skills/notion/SKILL.md
Commit: 66bfd09

Reviewed: 2 days 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.