סקיל notion
סקיל notion הוא סקיל מותאם לקלוד קוד שמאפשר לסוכן לקרוא, ליצור ולעדכן דפים ו-databases של Notion ישירות מתוך התהליך של פרויקט. אני משתמש בו לסנכרון של מפרטי פרויקטים, ניהול לידים, וסיכומי פגישות שעוברים אוטומטית למרכז הידע. בסקירה הזאת תקבלו את הקוד המלא של הסקיל, דוגמאות שימוש מסשנים אמיתיים, וצ׳קליסט אבטחה לפני שאתם משלבים אותו בעבודה היומית.
פקודת התקנה
mkdir -p ~/.claude/skills/notion && curl -o ~/.claude/skills/notion/SKILL.md https://dvirnaaman.co.il/wp-content/uploads/notion-skill.md
קובץ הסקיל הוא Markdown פתוח. אפשר להוריד אותו ולהריץ בדיקת קוד לפני התקנה דרך הכפתורים שבראש העמוד.
מה הסקיל כולל?
הסקיל מלווה את קלוד קוד באינטגרציה מלאה עם Notion, מזיהוי הקשר אוטומטי שמפעיל את הסקיל בזמן הנכון, דרך חוקי קריאה לפני כתיבה ועד טיפול בשגיאות מובנה. הוא כולל את הרכיבים הבאים.
קוד הסקיל המלא
---
name: notion
description: Use when working with Notion - creating, reading, updating pages and databases via the Notion API. Activates whenever the user mentions Notion, refers to a Notion URL, or asks to sync content to/from a knowledge base. Requires NOTION_API_KEY env var.
tools:
- Read
- Write
- WebFetch
---
# Notion Integration Skill
Use when the user asks to create, read, update or query Notion pages and databases via the Notion REST API.
## When to use
Activate this skill whenever the user:
- Mentions Notion explicitly ("update my Notion DB", "create a Notion page").
- Pastes a Notion URL (e.g. `https://www.notion.so/...`) and asks to read or modify content.
- Asks to keep a knowledge base in sync between code/specs and Notion.
- Requests creating recurring artifacts (meeting notes, project pages, content briefs) in Notion.
Do NOT activate this skill when the user only mentions Notion in passing without asking for an action.
## Required environment
- `NOTION_API_KEY` - integration token from https://www.notion.so/profile/integrations
- The integration must be added to the parent page or database (Share -> Add connections -> select your integration).
If `NOTION_API_KEY` is missing, stop and ask the user to add it before doing any work.
## Rules
1. **Read before write.** When updating an existing page or database, fetch the current schema first and respect the existing property names and types. Never invent property names.
2. **Block-level edits.** When updating page content, work at the block level (`PATCH /v1/blocks/{id}/children`). Do not replace the whole page.
3. **Database row creation.** Use `POST /v1/pages` with `parent: {database_id: ...}` and `properties: {...}`. Each property type has a specific shape: `title` is a list of rich text, `select` is `{name: "..."}`, `multi_select` is a list, `date` is `{start, end}`.
4. **Pagination always.** Database queries return up to 100 rows per call. Loop with `start_cursor` until `has_more=false`.
5. **Rate limits.** Notion limits to ~3 requests/second. Insert a 350ms delay between writes when bulk-creating rows.
6. **Hebrew/RTL content.** When writing Hebrew text, set `text.content` directly and add `annotations: {color: "default"}`. Notion handles RTL automatically based on character direction.
7. **No public sharing.** Never expose page IDs, database IDs, or the API key in user-facing output. Reference pages by title only.
## Examples
### Create a project brief page in a database
```python
import os, requests, time
NOTION_API_KEY = os.environ["NOTION_API_KEY"]
DB_ID = "<database-id-from-url>"
headers = {
"Authorization": f"Bearer {NOTION_API_KEY}",
"Notion-Version": "2022-06-28",
"Content-Type": "application/json",
}
payload = {
"parent": {"database_id": DB_ID},
"properties": {
"Name": {"title": [{"text": {"content": "פרויקט בדיקת איכות תוכן"}}]},
"Status": {"select": {"name": "Active"}},
"Owner": {"people": [{"id": "<user-id>"}]},
"Due": {"date": {"start": "2026-05-15"}},
},
"children": [
{
"type": "heading_2",
"heading_2": {"rich_text": [{"text": {"content": "Goal"}}]},
},
{
"type": "paragraph",
"paragraph": {"rich_text": [{"text": {"content": "..."}}]},
},
],
}
r = requests.post("https://api.notion.com/v1/pages", headers=headers, json=payload, timeout=30)
r.raise_for_status()
page_id = r.json()["id"]
```
### Query a database with filters and pagination
```python
def query_db(db_id, filter_obj):
cursor = None
rows = []
while True:
body = {"filter": filter_obj, "page_size": 100}
if cursor:
body["start_cursor"] = cursor
r = requests.post(
f"https://api.notion.com/v1/databases/{db_id}/query",
headers=headers,
json=body,
timeout=30,
)
r.raise_for_status()
data = r.json()
rows.extend(data["results"])
if not data.get("has_more"):
break
cursor = data.get("next_cursor")
time.sleep(0.35)
return rows
```
### Bulk-update a status column
```python
for page in rows:
notion_page_id = page["id"]
requests.patch(
f"https://api.notion.com/v1/pages/{notion_page_id}",
headers=headers,
json={"properties": {"Status": {"select": {"name": "Done"}}}},
timeout=30,
)
time.sleep(0.35)
```
## Output format
When the skill finishes, summarize what was created or updated in plain Hebrew with one short bullet per artifact:
- `[created] page "..." in database "Content Briefs"`
- `[updated] property "Status" on 3 rows`
Never include page IDs or database IDs in the summary.
## Failure modes to handle
- **401 unauthorized:** the integration is not added to the page/database. Ask the user to share the page with the integration.
- **404 object_not_found:** wrong ID, or the integration was removed. Ask the user to re-share.
- **429 rate_limited:** wait 1 second and retry once. If still 429, surface the error.
- **400 validation_error:** show the exact `message` field to the user; do not guess fixes.
מה זה סקיל notion ולמה הוא חשוב?
מי שעובד באתר עם פרויקטי לקוחות, או שמנהל מרכז ידע פנימי, מוצא את עצמו עובר בין הקוד או המפרט לבין Notion עשרות פעמים ביום. הסנכרון הזה לרוב נופל בין הכיסאות, ובסופו של חודש מתברר שכל ההחלטות המעניינות מתועדות במקום הלא נכון. הסקיל הזה הופך את המעבר לאוטומטי ומאפשר לי, למשל, לסיים סשן של שיחה עם קלוד עם שתי תוצאות בו זמנית: קוד שעובד ועמוד Notion עדכני שמתעד מה הוחלט ולמה.
מעבר לחיסכון בזמן, הסקיל פותר בעיה מבנית רחבה יותר. במערכות AI עסקיות, האינטגרציות החיצוניות הן רוב העבודה, לא הדגם עצמו. כשהסקיל מובנה היטב סביב Notion API ו-MCP, אפשר להוסיף עוד שירותים (Linear, Slack, ועוד) באותו דפוס בלי לפרק את התהליך. זה מבסס את הסקיל הזה כתבנית עזר לכל אינטגרציה SaaS עתידית שתידרש בפרויקט.
בנוסף, הסקיל פותר בעיה מובנית של זיכרון מזדמן. כשמדברים עם קלוד בתוך IDE, ההקשר נשאר רק לאותה שיחה. ברגע שמסיימים, הוא נעלם. עמוד Notion שנוצר אוטומטית מהשיחה הופך את ההקשר להיסטוריה מתועדת שאפשר לחזור אליה בעוד שלושה חודשים, וזה ההבדל בין "סשן של AI" לבין "מערכת תיעוד מבוססת AI". המעבר הזה הוא אבן יסוד של עבודה רצינית עם אוטומציות בכל ארגון.
מה סקיל notion נותן לקלוד קוד?
הסקיל מוסיף לקלוד קוד יכולת לשליטה מלאה בכל workspace של Notion דרך ה-API הרשמי. בלעדיו, המשתמש יקליד פרטים ידנית בכל פעם שיש החלטה לתעד. עם הסקיל, ההפעלה אוטומטית: קלוד מזהה שהשיחה מתאימה ל-Notion ומבצע את הפעולה הנכונה בלי שאישוב ידני יידרש.
יצירת ועדכון עמודים
הסקיל יודע ליצור עמוד חדש ב-database או ב-page parent, לעדכן עמוד קיים, ולהוסיף תכנים מובנים בלי לכתוב את ה-API קריאות בעצמך. הקלוד פשוט אומר "תעד את ההחלטה הזו ב-Engineering Decisions" ופועל מיד.
טבלאות ו-databases
קריאה וכתיבה לטבלאות מורכבות עם properties שונים: select, multi-select, date, person, relations, ו-rollup. הסקיל מכיר את הסכמה של ה-database ומקליט נתונים בפורמט הנכון בלי שתצטרכו להגדיר schema ידנית בכל פעם.
חיפוש ו-filtering
שאילתות מתקדמות על workspace שלם, כולל סינון לפי properties, חיפוש טקסטואלי, ומיון לפי תאריך עדכון. שימושי במיוחד למצבים כמו "תמצא את כל ה-bugs מהשבוע האחרון שעדיין פתוחים" או "תביא את כל ההחלטות בנושא X".
תגובה אוטומטית להקשר
הסקיל מזהה אוטומטית מתי השיחה דורשת אינטראקציה עם Notion, בלי שתבקשו במפורש. אם דנים בהחלטה ארכיטקטונית, הוא מציע ליצור entry. אם מציגים bug, הוא מציע לעדכן status. הזיהוי האוטומטי מבטל את הצורך בפקודות ידניות.
התוצאה: שיחה אחת עם קלוד מסתיימת בקוד שעובד וגם בעמוד Notion עדכני שמשמש כתיעוד אמין. אני משתמש בסקיל הזה בכל פרויקט שיש בו workspace של Notion, וזה הכלי שחסך לי הכי הרבה זמן בחצי השנה האחרונה.
למי הסקיל הזה מתאים?
מנהלי תוכן שמתחזקים calendar editorial: עם briefs, status, וקישורים לקבצים שמופיעים בתבנית קבועה. הסקיל מאפשר לקלוד ליצור ולעדכן רשומות בלי מעבר ידני בין הכלים, וכל פוסט שעולה לאוויר מקבל אוטומטית עדכון status בתוך הטבלה הראשית.
מפתחים שעובדים סולו: שרוצים שכל החלטה ארכיטקטונית בסשן עם קלוד תתועד בעמוד Notion ייעודי, עם טבלת decisions שמתעדכנת אוטומטית. בלעדיה, רוב המפתחים שוכחים תוך שבוע מה הוחלט, ואז מבזבזים זמן על דיון חוזר אחרי חודש.
ראשי צוות שמשתמשים ב-Notion ככלי ניהול: שרוצים שעדכוני סטטוס מהקוד יזרמו אוטומטית בלי שיעדכנו ידנית בכל סוף יום. הסקיל יוצר workflow שבו קלוד הוא ה-glue בין ה-IDE ובין ה-PM, ומעביר עדכונים בלי שאלות.
כותבי תוכן ומשווקים: שמתחזקים מאגר רעיונות ב-Notion ורוצים שכל סשן של brainstorming עם קלוד יוסיף שורה לטבלה עם ה-status המתאים. הצוות עוקב על האידיאות שעוד לא יצאו, וקלוד תורם רעיונות חדשים בלי לאבד את ההיסטוריה.
סטודיוס ויועצי AI שעובדים עם לקוחות חיצוניים: כשהלקוח מצפה לתיעוד מקצועי של כל פעולה, הסקיל מבטיח שכל החלטה נשמרת ב-Notion שלו ולא רק בצ'אט. בפיתוח תוכנה ללקוחות שלי, זה הכלי שמבטיח שלקוח יכול לראות את ההיסטוריה גם אחרי שהפרויקט מסתיים. דוגמאות נוספות אפשר לראות בתיק העבודות.
מי שלא מתאים: משתמשים שלא משתמשים ב-Notion באופן יומיומי, או שמסתפקים ב-Markdown מקומי. עבורם הסקיל הוא overhead מיותר. הוא נועד למי שעבר לעבוד ב-Notion ככלי הראשי לתיעוד וניהול, ולא למי שעדיין מנסה את הפלטפורמה.
איך הסקיל עזר לי בפרויקטים אמיתיים
אוטומציית לידים, חיסכון של 4 שעות בשבוע
סוכנות פרסום ביקשה שכל ליד שנכנס לאתר יתועד בטבלת CRM ב-Notion עם פרטים, מקור ו-tags. עם הסקיל, ההגדרה לקחה 30 דקות במקום יום עבודה. כל ליד מתועד תוך פחות משנייה, וצוות המכירות פותח את ה-inbox עם רשימה ממוינת לפי דחיפות.
ניהול ספריית תוכן, 47 בריפים בחודש
בלוג של חברה גדולה השתמש ב-Notion ככלי ניהול מרכזי. הסקיל אפשר לקלוד ליצור brief חדש בכל שיחה על נושא, עם status ראשוני וכל המידע שעלה. החיסכון בזמן העתקה ידנית: כשעה ביום עבודה, ועקביות מלאה בפורמט הבריפים בלי תלות בכותב.
סיכומי פגישות אוטומטיים בסטארטאפ B2B
בסטארטאפ שעובד מבוזר, אחרי כל פגישת תכנון אני מבקש מקלוד לסכם את השיחה לתיק Engineering Decisions ב-Notion. הסקיל יוצר עמוד עם החלטות, action items ו-owners. הצוות רואה את הסיכום תוך דקה אחרי הפגישה, וחברי צוות שמתחילים בבוקר רואים בדיוק מה הוחלט אתמול.
ניהול buglist בפרויקט פיתוח אקטיבי
בפרויקט פיתוח לסטודיו דיגיטלי, כל באג שזיהיתי בסשן עם קלוד נכנס אוטומטית לטבלת Bugs ב-Notion עם תיאור, severity, וקובץ קוד רלוונטי. הצוות בודק את הטבלה כל בוקר ולוקח פריטים לטיפול. שיעור הבאגים שנכנסו לפרודקשן ירד ב-30% בחודש הראשון.
ארבעת מקרי השימוש האלה ממחישים את הגמישות של הסקיל ואת השילוב הטבעי שלו עם זרימות עבודה קיימות. בדומה ל-skill-creator שסקרתי, סקיל notion הוא דוגמה לאיך אינטגרציה אחת טובה משנה את הדרך שבה משתמשים ב-AI בפועל. אם אתם מחפשים אוטומציות מבוססות AI שמשתלבות בכלים שלכם, אפשר לדבר על מה שמתאים לפרויקט הספציפי שלכם.
סיכום
סקיל notion הוא דוגמה למה קורה כשאינטגרציה SaaS נעשית נכון: קלוד קוד מקבל גישה מלאה ל-Notion API, מזהה אוטומטית מתי השיחה דורשת תיעוד, ופועל ברקע בלי הוראות ידניות. התוצאה היא שכל החלטה, כל באג, וכל סיכום פגישה נשמרים במקום הנכון בלי שתשכחו לתעד אחר כך.
אני משתמש בסקיל הזה בעיקר בפרויקטי לקוחות שיש בהם workspace של Notion פעיל. החיסכון בזמן הוא משמעותי, אבל היתרון העיקרי הוא הוודאות: ידיעה שכל מה שעלה בשיחה תועד נכון, בפורמט עקבי, וזמין לחברי הצוות שלא היו בשיחה. למי שמשתמש ב-Notion ככלי הראשי, הסקיל הזה משדרג את היחס שלו עם קלוד מ"כלי קוד" ל"שותף תיעוד מלא".
לפני שמתקינים: וודאו שיש לכם integration token של Notion עם הרשאות מתאימות, ושה-database או ה-page parent משותפים עם ה-integration שלכם. בלי שני אלה, הסקיל פעיל אבל מקבל שגיאות הרשאה. ההתקנה לוקחת 10 דקות ומופיעה בפירוט בקוד הסקיל למעלה.
שאלות ותשובות
איך מתקינים את הסקיל ב-Claude Code?
שמרו את קוד הסקיל כקובץ SKILL.md תחת ~/.claude/skills/notion/, הגדירו NOTION_API_KEY ב-environment, וצרו אינטגרציה ב-Notion. קלוד יזהה את הסקיל אוטומטית בשיחה הבאה שמתייחסת ל-Notion.
האם זה עובד גם ב-Cursor או ב-Codex?
הסקיל בנוי במבנה של Claude Code, כלומר עם frontmatter של name, description ו-tools. ב-Cursor אפשר להעתיק את ההיגיון לקובץ .cursorrules אבל אין activation אוטומטי. ב-Codex של OpenAI יש מבנה אחר. אם אתם עובדים שם, צריך להמיר.
האם הסקיל שולח דאטה לשרת חיצוני?
הסקיל משתמש רק ב-API הרשמי של Notion. אין שרת ביניים, אין proxy, אין שירות צד שלישי. הקוד גלוי בפוסט הזה ואתם יכולים לאמת לפני התקנה.
האם אפשר לערוך את הסקיל?
בהחלט. ערכו את SKILL.md כדי להוסיף חוקים שמתאימים ל-databases שלכם, להחליף שמות properties, או להוסיף failure modes נוספים. שמירת הקובץ מספיקה כדי שקלוד יקרא את הגרסה החדשה בסשן הבא.
מה ההבדל בין סקיל לבין subagent?
סקיל הוא קובץ הוראות שמופעל אוטומטית כשהקשר מתאים, ומגביל את ההתנהגות של קלוד עצמו. subagent הוא תהליך נפרד שיכול לרוץ במקביל לסשן הראשי, בדרך כלל בקונטיינר ענן. סקיל זול יותר ומהיר. subagent מתאים לסריקות ארוכות.
האם הסקיל מתאים לעברית RTL?
כן. Notion מטפל ב-RTL אוטומטית לפי כיווניות התווים, כך שטקסט עברי שעובר דרך הסקיל מופיע נכון בעמוד. אין צורך בהגדרה נוספת.
כמה זמן לוקח לסקיל לרוץ?
פעולה בודדת לוקחת כשנייה. עדכון של 100 שורות ב-database לוקח כ-40 שניות בגלל ה-rate limit של Notion. אם אתם צריכים יותר מהיר, שקלו batch import או התאמת המבנה.
מה קורה אם ה-API key פג תוקף?
הסקיל מזהה את שגיאת 401 ועוצר. אתם תקבלו הודעה ברורה לחדש את ה-token ב-notion.so/profile/integrations. עד אז שום פעולה לא נעשית, גם אם השיחה ממשיכה.
