pentaoa/notion-skill-library

Notion Skill Library

Make each managed skill easy to discover, safe to update, and usable in the agent where it is needed. Treat the Notion skill page as an executable knowledge product, not a bookmark or inventory row.

Choose the library model

• Prefer a native Notion Skills database for instructions that Notion Agent should discover, run, share, and download to local agents.
• Use a general capability catalog for mixed assets such as Prompt, MCP, Connector/App, and Workflow records that are not all executable Notion skills.
• Separate the content source of truth from the catalog record. Content may be canonical in Notion, a repository, or a local source. When both library models exist, the capability catalog links to the native skill record or its canonical source; it does not keep a second instruction body.

Read references/native-notion-library.md when creating, converting, sharing, enabling, downloading, or removing native Notion skills. Read references/schema-and-retrieval.md for a new database, schema mapping, or retrieval design.

Resolve the target before writing

1. Confirm an already authorized Notion surface exists: a connected Notion tool, an API or ntn session, or an authenticated controllable browser. The skill itself does not grant workspace access. If none exists, ask the user to connect one before attempting reads or writes.
2. Use the database or skill page the user supplied. Otherwise, find the workspace's existing Skills database through Notion Library or workspace search before proposing another one.
3. Start with one shared Skills database when the same group uses and maintains the skills. Split only for different access, owners, or a genuinely private drafting space.
4. Fetch the live data-source schema before creating or updating records. Map property roles to the actual names instead of assuming English labels.
5. Query a stable source or package key when one exists. A title match is only a candidate: compare provenance, description, or body before updating. If identity remains ambiguous, keep the records separate or ask the user.

Core workflows

Add or import a skill

Determine whether the source of truth is Notion, a repository, or a local skill folder. Extract the skill's name, description, instructions, and supporting files. Create or update one skill page with:

• a clear Description stating both what the skill does and when it applies;
• concise executable instructions in the page body;
• references, examples, scripts, images, or data in Files when they are needed;
• provenance and ownership properties only when they drive maintenance.

Use references/import-and-sync.md for source- specific import, exact-source preservation, and synchronization rules.

Add or update a catalog capability

For a Prompt, MCP server, Connector/App, Workflow, or non-native Skill record:

1. Fetch the mixed catalog's live schema and map Name, Asset type, Description, canonical source/body, retrieval terms, requirements, and boundaries to the properties or page body actually present.
2. Deduplicate by a stable source/package key, then confirm identity from the record content. Create one record per capability identity.
3. Put short filterable metadata in properties and long reusable content in the page body or an attached exact-source file. A prompt with no repository is a valid canonical body.
4. On update, change the chosen content source first and refresh only its derived catalog representation. Preserve unrelated properties.

Do not apply native enable, download, unmark-as-skill, or shared-skill deletion semantics to Prompt, MCP, Connector/App, or Workflow records. Removing one of these is an ordinary catalog record deletion unless the workspace defines a separate linked lifecycle.

Find and use a skill

Search by the user's intended task, aliases, and likely verbs—not only by the asset's name. With a semantic Notion search surface, prefer Description and body matches over tags alone. With API/CLI only, use title search to locate the data source, query typed Description, Search terms, Asset type, or Tags properties to shortlist records, then fetch candidate bodies. Fetch the selected page and its required files before following it. If several capabilities fit, distinguish them by outcome or scope and ask only when that choice materially changes the result.

Update a skill

Update the canonical source, then refresh the derived copy. Keep the Description aligned with the current behavior because Notion Agent uses it for automatic selection. Preserve unrelated properties and files. Replace an attachment only when its source changed; do not accumulate numbered copies without a reason.

Distribute or remove a skill

For local-agent use, prefer Notion's Download to local agents flow when the native skill page is the content source of truth. For repository-canonical skills, use the target agent's documented skill-install mechanism after confirming it supports the packaged Agent Skills structure; keep the Notion page as its discoverable representation.

Distinguish removal actions: deleting the page removes a shared skill for everyone, disabling a discovered skill affects only the current user, unmarking it keeps a regular page, and uninstalling a local copy does not delete its Notion source. Deleting the Notion page does not remove copies already downloaded to local agents; uninstall those separately. Never substitute one action for another.

Quality contract

Before calling a shared skill ready:

• its Description is specific enough for automatic selection without attracting unrelated tasks;
• its body states the outcome, required inputs, decision-changing constraints, and expected output or completion condition;
• optional detail is moved to references, while essential instructions remain in the page;
• exact source and executable files survive the chosen Notion representation;
• one realistic request has been walked through far enough to expose missing inputs, wrong routing, or unusable output;
• a shared skill has a clear maintainer, whether or not that is stored as an Owner property.

Read references/quality-playbook.md when creating a new shared skill, substantially revising one, or preparing it for public recommendation.

Do not add “unverified” or “not adopted” as default gates. Add lifecycle fields only when a real team workflow uses their values. Store authentication methods or secret locations, never secret values.

Tool routing

Use connected Notion tools for semantic search, page reads, and ordinary page updates. Use the current Notion API or ntn for live schema, typed property queries, pagination, files, and unsupported fields. Use browser interaction for native Skills Library controls that are only exposed in the Notion UI. Discover current tool syntax instead of guessing, and stop retrying a tool once the current surface reports it unavailable. API/CLI tools can create an ordinary database but cannot mark it as a native Skills database. If browser control is unavailable, give the user the documented UI conversion step and wait for them to complete it before continuing with native schema or content work.