About

Imported from jeremylongshore/tons-of-skills-marketplace (skills/.curated/notion-policy-guardrails/SKILL.md). Install upstream with npx skills add jeremylongshore/tons-of-skills-marketplace --skill notion-policy-guardrails. Copyright stays with the author (MIT).

Notion Policy & Guardrails

Name: notion-policy-guardrails
Author: jeremylongshore

Overview

Governance framework for Notion integrations at scale. Covers integration naming standards, page sharing policy enforcement, property naming conventions, database schema validation, and access audit scripts. Uses Client from @notionhq/client for programmatic enforcement.

Prerequisites

@notionhq/client v2.x installed (npm install @notionhq/client)
Python: notion-client installed (pip install notion-client)
NOTION_TOKEN environment variable set (admin-level integration recommended for audits)
CI/CD pipeline (GitHub Actions examples provided)

Authentication

All scripts authenticate with a Notion internal integration token read from the NOTION_TOKEN environment variable — never hardcode it. Create the token at notion.so/my-integrations, share the target pages/databases with the integration, and inject the token via CI secrets (e.g. secrets.NOTION_AUDIT_TOKEN). Audit scripts want a broadly-shared admin integration; runtime bots want the narrowest sharing scope that works. Token rotation is tracked in Step 1 (max 90 days).

Instructions

The workflow has three stages. Each stage's full enforcement code (TypeScript + Python) lives in references/implementation.md — the skeletons below show the shape; drill into the reference for the complete functions.

Step 1: Integration Naming Standards and Token Management

Establish a {team}-{env}-{purpose} naming convention (e.g. eng-prod-sync) so teams can identify which bot accessed what, validate it at startup, and track token rotation (max 90 days). Core check:

// Must match: /^[a-z]+-[a-z]+-[a-z]+$/  →  eng-prod-sync
function validateIntegrationName(name: string): string[] { /* ... */ }

Full IntegrationConfig, startup validation, and checkTokenExpiry registry: references/implementation.md § Step 1.

Step 2: Page Sharing Policies and Property Naming Conventions

Standardize property names across databases (PascalCase titles, Date/At suffixes on dates, plural multi-selects, a banned-name list) and audit which pages are shared publicly. Core check:

async function auditDatabaseSchema(notion, databaseId):
  Promise<{ violations: string[]; recommendations: string[] }> { /* ... */ }

Full PROPERTY_NAMING_RULES, auditPageAccess, and the Python port: references/implementation.md § Step 2.

Step 3: Access Audit Scripts and Database Schema Standards

Run a paginated, rate-limited workspace audit of everything the integration can reach, and gate schema drift in CI. Core check:

async function workspaceAccessAudit(notion: Client): Promise<void> { /* ... */ }
// Flags integrations with access to >1000 items; enumerates every database.

Full validateSchemaInCI, the GitHub Actions workflow (weekly cron + token scan), and the Python port: references/implementation.md § Step 3.

Output

Integration naming standards validated at startup
Token rotation tracking with expiry warnings
Property naming conventions audited against database schemas
Access audit showing all content visible to the integration
CI workflow enforcing schema standards and secret scanning
Violation report with actionable recommendations

Error Handling

Issue	Cause	Solution
Audit shows too many pages	Integration shared at workspace level	Narrow sharing to specific pages/databases
Schema validation fails	Property renamed in Notion UI	Update schema config to match
Token scan false positive	Test fixtures contain example tokens	Add `--exclude` for test directories
`object_not_found` during audit	Page unshared since last audit	Expected — log and continue
Naming convention too strict	Legacy integrations don't match	Add exceptions list with migration deadline

Examples

A one-line CI secret scan and the .env-not-committed guard:

grep -rn "ntn_\|secret_" --include="*.ts" --include="*.js" src/ && echo "FAIL: Token found" || echo "PASS: No tokens"
git ls-files | grep -E "^\.env" && echo "FAIL: .env committed" || echo "PASS"

For the full SCHEMA_REGISTRY (per-database required-property maps that feed CI validation) and more, see references/examples.md.

Resources

Next Steps

For architecture blueprints, see notion-architecture-variants. For common mistakes to avoid, see notion-known-pitfalls.

Use it

Copy one of these into your project. Installing also returns the manifest and these snippets.

yaml

targets:
  - https://api.opensmartroute.ai/api/v1/registry/jeremylongshore-tons-of-skills-marketplace-notion-policy-eee5c0/manifest   # or paste the manifest below

Manifest

An Open Capability Manifest: the router reads it to know what this does, what it costs and when to pick it.

jeremylongshore-tons-of-skills-marketplace-notion-policy-eee5c0.ocm.jsonjson

{
  "ocm": "1",
  "id": "jeremylongshore-tons-of-skills-marketplace-notion-policy-eee5c0",
  "kind": "skill",
  "name": "notion-policy-guardrails",
  "description": "Use when you need to govern Notion integrations at scale — set integration naming standards, enforce page sharing policies, standardize property naming and database schemas, and run access audits that scan which bots can reach which pages. Trigger with phrases like \"notion governance\", \"notion policy\", \"notion naming convention\", \"notion access audit\", \"notion schema standard\".",
  "publisher": "jeremylongshore",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "general"
    ],
    "tags": [
      "skill-md",
      "saas",
      "productivity",
      "notion",
      "skills-sh"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "Use when you need to govern Notion integrations at scale — set integration naming standards, enforce page sharing policies, standardize property naming and database schemas, and run access audits that scan which bots can reach which pages. Trigger with phrases like \"notion governance\", \"notion policy\", \"notion naming convention\", \"notion access audit\", \"notion schema standard\"."
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "skills.sh",
      "repository": "https://github.com/jeremylongshore/tons-of-skills-marketplace",
      "path": "skills/.curated/notion-policy-guardrails/SKILL.md",
      "ref": "HEAD",
      "url": "https://github.com/jeremylongshore/tons-of-skills-marketplace/blob/HEAD/skills/.curated/notion-policy-guardrails/SKILL.md",
      "key": "jeremylongshore/tons-of-skills-marketplace/skills/.curated/notion-policy-guardrails/SKILL.md"
    },
    "compatibility": "Designed for Claude Code",
    "allowed_tools": [
      "Read,",
      "Write,",
      "Edit,",
      "Bash(npx:*),",
      "Bash(node:*)"
    ],
    "license": "MIT"
  },
  "instructions": "# Notion Policy & Guardrails\n\n## Overview\n\nGovernance framework for Notion integrations at scale. Covers integration\nnaming standards, page sharing policy enforcement, property naming conventions,\ndatabase schema validation, and access audit scripts. Uses `Client` from\n`@notionhq/client` for programmatic enforcement.\n\n## Prerequisites\n\n- `@notionhq/client` v2.x installed (`npm install @notionhq/client`)\n- Python: `notion-client` installed (`pip install notion-client`)\n- `NOTION_TOKEN` environment variable set (admin-level integration recommended for audits)\n- CI/CD pipeline (GitHub Actions exa",
  "cost": {
    "context_tokens": 1229
  }
}

Fetch it by URL: GET /api/v1/registry/jeremylongshore-tons-of-skills-marketplace-notion-policy-eee5c0/manifest?version=1.0.0

Reviews

Star ratings from people who tried it. One review per account; edit yours any time.

No reviews yet. Install it, try it, and be the first to rate it.