Skip to content
Back to search

agent-notion-template-docs

Marketplace for Notion-template document generation skills

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/heyman333--agent-notion-template-docs/badge.svg)](/listings/heyman333--agent-notion-template-docs)

HTML

<a href="/listings/heyman333--agent-notion-template-docs"><img src="/api/listings/heyman333--agent-notion-template-docs/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

notion-doc ships as a portable [Agent Plugin](https://agent-plugins.org) — one `plugin.json`, one `skills/` directory, one hook. Codex and Claude Code install the same files.

Codex

Install it as a plugin:

codex plugin marketplace add heyman333/agent-notion-template-docs

Then pick `notion-doc` in the plugin browser:

/plugins

Or drop the skill in by hand — it is a directory, nothing to build:

# this repo only
mkdir -p .agents/skills && cp -r skills/notion-doc .agents/skills/

# every project
mkdir -p ~/.agents/skills && cp -r skills/notion-doc ~/.agents/skills/

Codex picks it up on the next session. Ask for a document and it applies on its own; to force it, type `$notion-doc`.

If you install by hand rather than as a plugin, the lint hook does not come along. Wire it up once in `~/.codex/hooks.json` (or `<repo>/.codex/hooks.json`):

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit|apply_patch",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/agent-notion-template-docs/hooks/notion-doc-lint.py"
          }
        ]
      }
    ]
  }
}

The script reads the tool payload on stdin and takes no arguments. It understands both payload shapes — Claude Code's `file_path` and Codex's `apply_patch` body.

Claude Code

/plugin marketplace add heyman333/agent-notion-template-docs
/plugin install notion-doc@agent-notion-template-docs

Choosing an install scope

By default the plugin is installed at the **user** scope — it applies to all of *your* projects and never touches the repo, so teammates are unaffected.

To narrow or widen that, pass `--scope` on the CLI:

# just me, just this project (.claude/settings.local.json — auto-gitignored)
claude plugin marketplace add heyman333/agent-notion-template-docs --scope local
claude plugin install notion-doc@agent-notion-template-docs --scope local

# the whole team on this project (.claude/settings.json — commit it)
claude plugin marketplace add heyman333/agent-notion-template-docs --scope project
claude plugin install notion-doc@agent-notion-template-docs --scope project

With `project` scope, teammates get an install prompt on their next session after pulling. With `local` scope, nothing you install shows up in git.

Updating

New versions ship through this marketplace repo, so refresh the marketplace first, then update the plugin:

/plugin marketplace update agent-notion-template-docs
/plugin update notion-doc@agent-notion-template-docs

Or from the CLI, passing the scope you installed at:

claude plugin marketplace update agent-notion-template-docs
claude plugin update notion-doc@agent-notion-template-docs --scope user   # or local / project

Restart Claude Code to apply. If you installed at more than one scope, update each one — in a project the narrower scope wins. `claude plugin list` shows what you currently have.

You can also copy the skill manually.

# this project only
cp -r skills/notion-doc <your-project>/.claude/skills/

# every project
cp -r skills/notion-doc ~/.claude/skills/

Cursor, Gemini CLI, and others

The skill is two plain files with no agent-specific dependencies. Any agent that can read instruction files can use it.

See [Using with other agents](docs/using-with-other-agents.md) for ready-to-paste snippets for `AGENTS.md`, `.cursor/rules`, and `GEMINI.md`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 16 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "agent-notion-template-docs",
  3. "description": "Marketplace for Notion-template document generation skills",
  4. "owner": {
  5. "name": "heyman333",
  6. "url": "https://github.com/heyman333"
  7. },
  8. "plugins": [
  9. {
  10. "name": "notion-doc",
  11. "source": "./",
  12. "description": "Agent skill that renders agent-generated HTML/Markdown documents with Notion's blocks (callouts, toggles, tables, checklists, code, columns, etc.) and design — content and structure stay free, only the visuals are locked to Notion",
  13. "version": "3.5.1"
  14. }
  15. ]
  16. }
README.md · README · 295 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # 📄 notion-doc
  2. > Make your AI agent write documents like Notion — not like an AI.
  3. ![notion-doc](docs/hero.jpg)
  4. [![notion-sync](https://github.com/heyman333/agent-notion-template-docs/actions/workflows/notion-sync.yml/badge.svg)](https://github.com/heyman333/agent-notion-template-docs/actions/workflows/notion-sync.yml)
  5. [한국어](README.ko.md)
  6. Ask an AI agent to create a document and you'll often get the same kind of output: a purple gradient hero, emoji-heavy headings, cards with drop shadows.
  7. **notion-doc** is an agent skill that gives those documents a Notion-like visual style.
  8. It doesn't decide what goes into your document or how it's structured. Your agent still handles the content and outline. notion-doc only handles the presentation.
  9. | Without notion-doc | With notion-doc |
  10. | --- | --- |
  11. | ![before](docs/screenshot-before.png) | ![after](docs/screenshot-light.png) |
  12. ## What it includes
  13. The skill provides a set of HTML blocks commonly used in Notion:
  14. - Emoji page icons, tag pills, meta lines, and breadcrumbs
  15. - Callouts in 5 colors: blue (key point), gray (note), green (done), yellow (caution), and red (warning)
  16. - Table of contents, simple tables, 2-column layouts, and buttons
  17. - Toggles (`<details>`), checklists with strikethrough, quotes, and bookmark cards
  18. - Syntax-highlighted code blocks using Prism, with light and dark themes
  19. - Inline code
  20. - Notion-style text colors: blue, red, orange, green, and purple
  21. - Korean-aware line breaking (`word-break: keep-all`)
  22. - Print/PDF layout with `@media print`
  23. ### One template for the visual style
  24. The agent doesn't generate CSS for each document. It copies
  25. [template.html](skills/notion-doc/template.html) and fills in the content.
  26. The template defines a 720px content width, `#2C2C2B` text color, and Notion's light and dark color palettes as CSS tokens.
  27. Dark mode follows the viewer's theme. When printed or exported to PDF, it switches back to the light palette.
  28. | Light | Dark |
  29. | --- | --- |
  30. | ![light](docs/screenshot-light.png) | ![dark](docs/screenshot-dark.png) |
  31. ## Install
  32. notion-doc ships as a portable [Agent Plugin](https://agent-plugins.org) — one
  33. `plugin.json`, one `skills/` directory, one hook. Codex and Claude Code install
  34. the same files.
  35. ### Codex
  36. Install it as a plugin:
  37. ```bash
  38. codex plugin marketplace add heyman333/agent-notion-template-docs
  39. ```
  40. Then pick `notion-doc` in the plugin browser:
  41. ```text
  42. /plugins
  43. ```
  44. Or drop the skill in by hand — it is a directory, nothing to build:
  45. ```bash
  46. # this repo only
  47. mkdir -p .agents/skills && cp -r skills/notion-doc .agents/skills/
  48. # every project
  49. mkdir -p ~/.agents/skills && cp -r skills/notion-doc ~/.agents/skills/
  50. ```
  51. Codex picks it up on the next session. Ask for a document and it applies on its
  52. own; to force it, type `$notion-doc`.
  53. If you install by hand rather than as a plugin, the lint hook does not come
  54. along. Wire it up once in `~/.codex/hooks.json` (or `<repo>/.codex/hooks.json`):
  55. ```json
  56. {
  57. "hooks": {
  58. "PostToolUse": [
  59. {
  60. "matcher": "Write|Edit|apply_patch",
  61. "hooks": [
  62. {
  63. "type": "command",
  64. "command": "/path/to/agent-notion-template-docs/hooks/notion-doc-lint.py"
  65. }
  66. ]
  67. }
  68. ]
  69. }
  70. }
  71. ```
  72. The script reads the tool payload on stdin and takes no arguments. It
  73. understands both payload shapes — Claude Code's `file_path` and Codex's
  74. `apply_patch` body.
  75. ### Claude Code
  76. ```text
  77. /plugin marketplace add heyman333/agent-notion-template-docs
  78. /plugin install notion-doc@agent-notion-template-docs
  79. ```
  80. #### Choosing an install scope
  81. By default the plugin is installed at the **user** scope — it applies to all of *your* projects and never touches the repo, so teammates are unaffected.
  82. To narrow or widen that, pass `--scope` on the CLI:
  83. ```bash
  84. # just me, just this project (.claude/settings.local.json — auto-gitignored)
  85. claude plugin marketplace add heyman333/agent-notion-template-docs --scope local
  86. claude plugin install notion-doc@agent-notion-template-docs --scope local
  87. # the whole team on this project (.claude/settings.json — commit it)
  88. claude plugin marketplace add heyman333/agent-notion-template-docs --scope project
  89. claude plugin install notion-doc@agent-notion-template-docs --scope project
  90. ```
  91. With `project` scope, teammates get an install prompt on their next session after pulling. With `local` scope, nothing you install shows up in git.
  92. #### Updating
  93. New versions ship through this marketplace repo, so refresh the marketplace first, then update the plugin:
  94. ```text
  95. /plugin marketplace update agent-notion-template-docs
  96. /plugin update notion-doc@agent-notion-template-docs
  97. ```
  98. Or from the CLI, passing the scope you installed at:
  99. ```bash
  100. claude plugin marketplace update agent-notion-template-docs
  101. claude plugin update notion-doc@agent-notion-template-docs --scope user # or local / project
  102. ```
  103. Restart Claude Code to apply. If you installed at more than one scope, update each one — in a project the narrower scope wins. `claude plugin list` shows what you currently have.
  104. You can also copy the skill manually.
  105. ```bash
  106. # this project only
  107. cp -r skills/notion-doc <your-project>/.claude/skills/
  108. # every project
  109. cp -r skills/notion-doc ~/.claude/skills/
  110. ```
  111. ### Cursor, Gemini CLI, and others
  112. The skill is two plain files with no agent-specific dependencies. Any agent that can read instruction files can use it.
  113. See [Using with other agents](docs/using-with-other-agents.md) for ready-to-paste snippets for `AGENTS.md`, `.cursor/rules`, and `GEMINI.md`.
  114. ## Usage
  115. Once installed, notion-doc is applied automatically when you ask the agent to create a document.
  116. For example:
  117. - "Write this up as a report"
  118. - "Summarize this as a doc"
  119. - "Write a postmortem"
  120. You can also invoke it explicitly:
  121. | Agent | Invoke |
  122. | --- | --- |
  123. | Codex | `$notion-doc` |
  124. | Claude Code | `/notion-doc:notion-doc` |
  125. ## Keeping the template intact
  126. The skill is designed around a single HTML template. The agent should use the template rather than creating its own CSS.
  127. `lint.py` checks generated documents against `template.html`:
  128. ```bash
  129. python3 skills/notion-doc/lint.py mydoc.html
  130. ```
  131. For example:
  132. ```text
  133. ✗ mydoc.html
  134. ERROR [css-drift] CSS differs from the canon (1 lines). Do not write new CSS — + box-shadow: 0 4px 12px ...
  135. ERROR [unknown-class] Classes not in the template: hero-card. Do not invent classes — pick from the block dictionary
  136. ```
  137. The linter catches:
  138. - CSS changes such as new shadows, gradients, or colors
  139. - Inline `style` attributes
  140. - Hand-written colors in the document body
  141. - Classes that are not defined in the template
  142. - Code blocks without a `language-*` class
  143. It uses only the Python standard library, so it can run in any agent or CI environment.
  144. When installed as a plugin, a `PostToolUse` hook runs after HTML files are written and reports what needs to be fixed. If the document was created without the skill, it gives a short reminder to use it. The same script serves both runtimes — it reads Codex's `apply_patch` payload and Claude Code's `file_path` payload.
  145. The hook is limited to document files and skips apps, framework templates, and build output. See the [gating tests](hooks/test_gating.py).
  146. ## Examples
  147. Open the HTML files in a browser to see the actual output.
  148. | File | Content | Blocks shown |
  149. | --- | --- | --- |
  150. | [sample.html](examples/sample.html) | Campaign proposal (Korean) | Most of the available blocks: breadcrumb, TOC, 5 callout colors, tables, 2-column layout, toggle, checklist, bookmark, button |
  151. | [sample-tech.html](examples/sample-tech.html) | Incident analysis (Korean) | Syntax-highlighted code, red/yellow callouts |
  152. | [sample-en.html](examples/sample-en.html) | Campaign proposal (English) | Same document as `sample.html`, in English |
  153. | [before.html](examples/before.html) | Without notion-doc | A typical default agent output |
  154. ## Repo layout
  155. ```text
  156. plugin.json # portable manifest (Agent Plugins 1.0)
  157. hooks.json # Codex PostToolUse hook
  158. AGENTS.md # instructions for agents working on this repo
  159. .codex-plugin/
  160. plugin.json # Codex compatibility manifest
  161. .agents/
  162. plugins/marketplace.json # Codex marketplace catalog
  163. skills/notion-doc # symlink → skills/notion-doc
  164. .claude-plugin/
  165. plugin.json # Claude Code manifest
  166. marketplace.json # Claude Code marketplace catalog
  167. skills/notion-doc/
  168. SKILL.md # block dictionary and visual rules
  169. template.html # HTML template and CSS
  170. lint.py # checks documents against the template
  171. hooks/
  172. hooks.json # Claude Code PostToolUse hook
  173. notion-doc-lint.py # the hook itself — reads both payload shapes
  174. test_gating.py # tests hook behavior
  175. examples/ # rendered example documents
  176. scripts/ # screenshots, Notion sync, manifest consistency
  177. docs/
  178. using-with-other-agents.md
  179. ```
  180. The skill lives in exactly one place. `.agents/skills/notion-doc` is a symlink,
  181. so Codex and Claude Code can never drift apart.
  182. ## Staying in sync with Notion
  183. Notion continues to add new block types and change its visual design. This repo periodically checks a public Notion reference page to see if the implementation has drifted.
  184. The weekly CI job, [notion-sync](.github/workflows/notion-sync.yml), checks the reference page in three ways:
  185. - **Design tokens**: every color in Notion's light and dark palettes, read directly from Notion's own stylesheets (no browser needed).
  186. - **Block types** are read through Notion's page API, with cursor pagination.
  187. - **Render sanity**: a headless browser render confirms the geometry and that blocks still paint.
  188. The results are compared against the committed baselines in [sync/notion-tokens.json](sync/notion-tokens.json) and [sync/notion-snapshot.json](sync/notion-snapshot.json).
  189. Reference page:
  190. [Notion Block Reference — All of Notion's Blocks](https://thomasfrank.notion.site/8b40147600284c60b6f708e38f16ee68)
  191. (Thomas Frank's public reference page.)
  192. When the reference changes, the CI job reports the difference and opens an issue. The report also indicates whether a new block type is already supported by notion-doc.
  193. ## Design source
  194. The visual style in `template.html` is based on Notion's own design tokens rather than manually approximated values.
  195. Notion declares its tokens right in its inline styles (`background: var(--c-graBacPri)`), so every value can be traced instead of sampled:
  196. - [scripts/notion_style_probe.py](scripts/notion_style_probe.py) renders the [Notion Block Reference — All of Notion's Blocks](https://thomasfrank.notion.site/8b40147600284c60b6f708e38f16ee68) page headlessly and reads the block→token mapping straight off the DOM.
  197. - [scripts/notion_tokens.py](scripts/notion_tokens.py) extracts each token's exact light *and* dark value from Notion's stylesheets.
  198. The weekly [notion-sync](#staying-in-sync-with-notion) job re-checks all of it, so the template can't silently drift from Notion.
  199. ## License
  200. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.