#18411: docs(notion): add file upload documentation to Notion skill
stale
size: S
Cluster:
Skill Improvements and Fixes
## Summary
Adds a **File Uploads** section to the Notion skill (`skills/notion/SKILL.md`) documenting the native Notion API file upload flow.
## What changed
New section covering:
- **3-step upload process**: create file upload object → send binary → attach to block/page
- **curl examples** for file blocks, image blocks, and database file properties
- **Tips** on expiry (1-hour attachment deadline), file reuse, and download URL refresh
- **Link to multi-part upload docs** for files > 20 MB
## Why
The Notion API now supports native file uploads (`POST /v1/file_uploads`), eliminating the need for external hosting workarounds (S3, Google Drive, etc.). The existing skill documentation didn't mention this capability, which meant agents defaulted to external file hosting or told users uploads weren't possible via the API.
## Testing
Verified the 3-step flow works end-to-end: uploaded two PDFs (3 MB and 6 MB) as native Notion file blocks using the documented curl commands.
<!-- greptile_comment -->
<h3>Greptile Summary</h3>
Adds a new **File Uploads** section to the Notion skill documentation (`skills/notion/SKILL.md`) covering the native Notion API file upload flow (`POST /v1/file_uploads`). The section documents a clear 3-step process (create upload object → send binary → attach to block/page), includes curl examples for file blocks and database file properties, and provides practical tips on expiry, reuse, and download URL refresh. This fills a gap where agents previously had no guidance on Notion-native file uploads and would default to external hosting workarounds.
- New section follows existing documentation conventions (consistent `Notion-Version: 2025-09-03` header, `$NOTION_KEY` variable usage, curl example format)
- Previous review feedback (API version inconsistency and misleading `upload_url` field) has been addressed in the follow-up commit
- No code changes; documentation-only PR
<h3>Confidence Score: 5/5</h3>
- This PR is safe to merge — it is a documentation-only addition with no code changes.
- Score of 5 reflects that this is a documentation-only change adding a well-structured File Uploads section to an existing skill file. The new content follows all existing conventions (consistent API version headers, variable usage, curl example formatting). Previous review feedback has been addressed. No logic, code, or configuration changes are involved.
- No files require special attention.
<sub>Last reviewed commit: b339e1e</sub>
<!-- greptile_other_comments_section -->
<!-- /greptile_comment -->
Most Similar PRs
#17684: fix(skills): update notion skill for API 2025-09-03
by chug2k · 2026-02-16
77.3%
#7656: docs(slack): improve skill documentation with thread support and AP...
by pswpswpsw · 2026-02-03
71.2%
#16087: docs: enhance OpenCode documentation in coding-agent skill
by imwxc · 2026-02-14
69.2%
#5273: fix: skill frontmatter fixes + description improvements (35 skills)
by Terwox · 2026-01-31
67.8%
#22410: docs: Add Agent Cloud Memory to community skills
by lilyjazz · 2026-02-21
67.8%
#13594: fix(skills): correct apple-notes SKILL.md memo -a syntax
by lailoo · 2026-02-10
67.3%
#17558: fix(slack): replace files.uploadV2 with 3-step upload flow to fix m...
by fif911 · 2026-02-15
67.3%
#19664: fix(skills): log skill YAML parsing diagnostics with skill name
by orchidsun · 2026-02-18
66.6%
#15803: fix(skills/github): add GraphQL introspection guidance
by rixau · 2026-02-13
65.9%
#10441: webchat: switch file uploads to HTTP /uploads
by supernewbilityxht1 · 2026-02-06
65.5%