# אתר שסוכנים יודעים לקרוא: llms.txt, גרסאות Markdown, OpenAPI וכרטיס שרת MCP

_2026-10-02 · מה צריך כדי שסוכן AI יבין אתר ושירות בלי לנחש: קובץ llms.txt, עמודי Markdown, מפרט OpenAPI, קטלוג API וכרטיס שרת MCP, עם האתר shager.ai כדוגמה עובדת מלאה._

אתר מוכן לסוכנים הוא אתר שבו סוכן AI יכול למצוא, בלי לגרד HTML ובלי לנחש, שלושה דברים: מה השירות עושה, איך מתחברים אליו, ואיך מבצעים בו פעולה. בפועל זה חמישה קבצים או נקודות קצה: `llms.txt` עם תקציר ומפת קישורים, גרסת Markdown לכל עמוד, מפרט OpenAPI שמתאר את ממשק התכנות, קטלוג ב`/.well-known/api-catalog`, וכרטיס שרת MCP. shager.ai מפרסם את כולם, ולכן אשתמש בו כדוגמה.

חשוב להגיד מה זה לא. אף אחד מהקבצים האלה לא מבטיח שמנוע חיפוש או מודל שפה יקרא אותו או ימליץ עליכם. הם מורידים את העלות של סוכן להבין אתכם נכון, וזה הכל. אבל כשסוכן מחליט עם איזה שירות לעבוד, שירות שאפשר להבין בשלוש קריאות עדיף על שירות שצריך לגרד.

## מה זה llms.txt ומה צריך להיות בו?

`llms.txt` הוא הצעה שפרסם Jeremy Howard בספטמבר 2024, ומתוחזקת ב[llmstxt.org](https://llmstxt.org/). זו לא תקינה של IETF או של W3C, אלא מוסכמה פתוחה. הקובץ יושב בשורש האתר, `/llms.txt`, ונכתב בפורמט Markdown במבנה קבוע:

1. כותרת H1 עם שם הפרויקט או האתר. זה החלק היחיד שהוא חובה.
2. ציטוט (blockquote) עם תקציר קצר.
3. פסקאות חופשיות עם מידע נוסף, בלי כותרות.
4. אפס או יותר רשימות קבצים, כל אחת תחת H2, שבהן כל פריט הוא קישור Markdown ואחריו, אם רוצים, נקודתיים והערה.

לפי ההצעה, לרשימה שנקראת `Optional` יש משמעות מיוחדת: אלה קישורים שסוכן יכול לדלג עליהם כשהוא צריך הקשר קצר יותר.

ככה זה נראה ב[llms.txt של שַׁגֵּר](https://shager.ai/llms.txt), בקיצור:

```markdown
# Shager

> Shager (שגר) is agent-first distribution infrastructure for agencies and marketers: ...

## For AI agents
- MCP server: https://app.shager.ai/api/mcp (Authorization: Bearer <api key>; OAuth sign-in is coming)
- REST API: https://app.shager.ai/api/v1 ...

## Product
- [Shager for AI agents](https://shager.ai/md/en/agents): Connect Claude, ChatGPT or Cursor to Shager ...

## Optional
- [Sitemap](https://shager.ai/sitemap.xml)
```

שלוש החלטות שקיבלנו ואני ממליץ עליהן. התקציר אומר במפורש מה לא קיים עדיין (טיקטוק ולינקדאין בפיתוח), כי סוכן שמסיק יכולת שלא קיימת יטעה את המשתמש שלו. הקטע "For AI agents" מופיע לפני רשימת העמודים, כי סוכן שמגיע לקובץ צריך קודם כל לדעת איך מתחברים. והקישורים ברשימות מובילים לגרסאות Markdown ולא לעמודי HTML.

### ומה עם `llms-full.txt`?

`llms-full.txt` הוא קובץ אחד עם כל התוכן של האתר בפורמט Markdown. הוא לא חלק מההצעה שבאתר llmstxt.org, אבל הוא מוסכמה נפוצה, וְשַׁגֵּר מפרסם אותו [בכתובת קבועה](https://shager.ai/llms-full.txt). הוא שימושי לסוכן שרוצה לטעון את כל ההקשר בקריאה אחת, ופחות שימושי כשהאתר גדול.

## גרסת Markdown לכל עמוד

ההצעה שבאתר llmstxt.org ממליצה שלכל עמוד עם מידע שימושי תהיה גרסת Markdown נקייה, ומתארת גילוי שלה דרך `rel="alternate"` עם `type="text/markdown"`, כאלמנט `<link>` בקוד העמוד או ככותרת `Link` בתשובת השרת.

באתר shager.ai יש שלוש דרכים להגיע לגרסת Markdown של כל עמוד, ושלושתן עובדות:

```bash
# 1. נתיב ייעודי תחת /md
curl https://shager.ai/md/pricing

# 2. משא ומתן על תוכן: אותה כתובת, כותרת Accept אחרת
curl -H "Accept: text/markdown" https://shager.ai/pricing

# 3. גילוי דרך כותרת Link בתשובת ה HTML
curl -sI https://shager.ai/agents | grep -i '^link'
# link: </.well-known/api-catalog>; rel="api-catalog", </llms.txt>; rel="describedby"; type="text/plain", </md/agents>; rel="alternate"; type="text/markdown"
```

הדרך השנייה נשענת על משא ומתן על תוכן, מנגנון שמוגדר ב[RFC 9110 של HTTP](https://www.rfc-editor.org/rfc/rfc9110#name-content-negotiation). היתרון שלה הוא שסוכן לא צריך לדעת על מוסכמת `/md` מראש. הוא מבקש Markdown ומקבל Markdown.

בעמודי Markdown כדאי להוריד ניווט, כפתורים וטקסט שיווקי שתלוי בעיצוב, ולהשאיר טבלאות, קוד ועובדות. באתר shager.ai הגרסה העברית יושבת תחת `/md/...` והאנגלית תחת `/md/en/...`.

## OpenAPI: החוזה של ממשק התכנות

`llms.txt` מספר לסוכן מה קיים. מפרט [OpenAPI 3.1](https://spec.openapis.org/oas/v3.1.0) מספר לו בדיוק איך לקרוא לכל פעולה: נתיב, שדות, סוגים, ערכים מותרים ושגיאות. [מפרט OpenAPI של שַׁגֵּר](https://app.shager.ai/api/v1/openapi.json) מתאר את כל הפעולות שזמינות גם ככלי MCP, עם `operationId` זהה לשם הכלי, כך שסוכן שקרא את המפרט יודע שהכלי `create_post` והקריאה `POST /workspaces/{workspace_id}/posts` הם אותה פעולה.

כמה דברים שהופכים מפרט OpenAPI לשימושי לסוכן, ולא רק לגנרטור קוד:

1. **תיאור לכל שדה, שמסביר למה הוא משמש.** אצלנו `stagger_seconds` מתואר כהפסקה אקראית בשניות בין חשבונות באותה רשת, עם ברירת המחדל.
2. **דוגמאות בתוך התיאור** במקומות שבהם הפורמט מכשיל, כמו `schedule_at` שמקבל ISO 8601 עם היסט.
3. **ערכים מותרים כרשימה סגורה (enum)**, כמו `FEED`, `REEL`, `STORY`, `SHORT`, `VIDEO`.
4. **סימון ההרשאה הנדרשת** לכל פעולה. אצלנו זה שדה הרחבה `x-scope`.

## קטלוג API: איפה ממשק התכנות נמצא

[RFC 9727](https://www.rfc-editor.org/rfc/rfc9727) מגדיר כתובת קבועה, `/.well-known/api-catalog`, שבה מפרסם מתאר את ממשקי התכנות שלו ומקשר אליהם. לפי התקן, הקטלוג מתפרסם בפורמט Linkset עם סוג התוכן `application/linkset+json`, ובקשת HEAD לכתובת צריכה להחזיר כותרת `Link` עם היחס `api-catalog`.

[הקטלוג של שַׁגֵּר](https://shager.ai/.well-known/api-catalog) מקשר את כתובת הבסיס של ממשק התכנות לשני דברים: `service-desc` שמצביע על מפרט OpenAPI (למכונה), ו`service-doc` שמצביע על עמוד הסוכנים בגרסת HTML ובגרסת Markdown (לאדם או למודל). היחסים האלה מוגדרים בתקן RFC 8631, ותקן הקטלוג משתמש בהם בדוגמאות שלו.

```json
{"linkset":[{"anchor":"https://app.shager.ai/api/v1",
  "service-desc":[{"href":"https://app.shager.ai/api/v1/openapi.json","type":"application/openapi+json"}],
  "service-doc":[{"href":"https://shager.ai/en/agents","type":"text/html"},
                 {"href":"https://shager.ai/md/en/agents","type":"text/markdown"}]}]}
```

## כרטיס שרת MCP

כרטיס שרת MCP הוא מסמך JSON סטטי שמתאר שרת MCP מרוחק לפני שמתחברים אליו: שם, גרסה, תיאור, נקודות קצה וכותרות נדרשות. ההגדרה היא הרחבה של פרוטוקול MCP, [`SEP-2127`](https://modelcontextprotocol.io/seps/2127-mcp-server-cards), והסכמה המחייבת מתוחזקת במאגר נפרד של ההרחבה. לפי ההצעה, הכרטיס יכול לשבת בכל כתובת, והמיקום המומלץ הוא כתובת השרת עם `/server-card` בסוף. לגילוי לפי דומיין ההצעה מפנה לקטלוג AI בכתובת `/.well-known/ai-catalog.json`, ויש מימושים שמפרסמים את הכרטיס עצמו גם תחת `/.well-known/mcp/`.

שַׁגֵּר מפרסם את הכרטיס בשני המקומות: [`app.shager.ai/api/mcp/server-card`](https://app.shager.ai/api/mcp/server-card) וגם [`shager.ai/.well-known/mcp/server-card.json`](https://shager.ai/.well-known/mcp/server-card.json). החלק החשוב בו הוא `remotes`:

```json
"remotes": [{
  "type": "streamable-http",
  "url": "https://app.shager.ai/api/mcp",
  "headers": [{
    "name": "Authorization",
    "description": "Bearer shgr_… API key (self-signup: POST /api/v1/agent/signup)",
    "isRequired": true,
    "isSecret": true
  }]
}]
```

מכאן לקוח MCP יודע בלי תיעוד נוסף שזה שרת Streamable HTTP, שצריך כותרת `Authorization`, ואיפה משיגים מפתח. ההצעה מסבירה שהכרטיס במתכונתו הראשונה לא אמור לפרסם את רשימת הכלים, כי כלים יכולים להשתנות לפי משתמש, ושהמקור המחייב לכלים הוא `tools/list` בזמן החיבור. שַׁגֵּר מוסיף רשימת כלים לכרטיס כמידע עזר, אבל סוכן צריך לסמוך על מה שהשרת מחזיר בחיבור.

## שני קבצים נוספים שאינם תקן

`auth.md` הוא מוסכמה שלנו, לא תקן: מתכון קצר בשפה פשוטה שמסביר לסוכן איך נרשמים, מה מותר בסנדבוקס ואיך אדם תובע אותו. [הקובץ נמצא כאן](/auth.md). והסקיל ב`https://shager.ai/skills/shager/SKILL.md` כתוב בפורמט [Agent Skills](https://code.claude.com/docs/en/skills), כך שאפשר להוריד אותו כמו שהוא לתיקיית הסקילים של Claude Code. איך בונים סקיל כזה בעצמכם מוסבר ב[מדריך לבניית סקיל לְשַׁגֵּר](/blog/build-a-claude-skill-for-shager).

## רשימת בדיקה לאתר שלכם

| רכיב | איפה | בדיקה מהירה |
|---|---|---|
| llms.txt | `/llms.txt` | H1, תקציר, קישורים לגרסאות Markdown |
| Markdown לכל עמוד | `/md/...` או `Accept: text/markdown` | `curl -H "Accept: text/markdown"` מחזיר Markdown |
| כותרת Link | כל עמוד HTML | `rel="alternate"` עם `type="text/markdown"` |
| OpenAPI | כתובת קבועה | תיאור לכל שדה, enum, שגיאות |
| קטלוג API | `/.well-known/api-catalog` | `application/linkset+json`, כותרת Link בבקשת HEAD |
| כרטיס שרת MCP | `<mcp-url>/server-card` | `remotes` עם כותרות נדרשות |

כדי לראות את כל זה מנקודת המבט של סוכן, אפשר להתחיל מ[עמוד הסוכנים](/agents), שגם הוא זמין בגרסת Markdown.

## שאלות נפוצות

### האם llms.txt משפר דירוג בגוגל?

אין לי מקור רשמי שאומר שכן, ולכן לא הייתי מבטיח את זה ללקוח. הקובץ מיועד לסוכנים ולכלים שקוראים אותו במפורש. העלות שלו נמוכה, והתועלת העיקרית היא שסוכן שמגיע אליכם מבין אתכם נכון.

### צריך גם llms.txt וגם sitemap.xml?

כן, כי הם משרתים קוראים שונים. sitemap מפרט כתובות לסורק של מנוע חיפוש, והקובץ llms.txt נותן לסוכן תקציר ומפה מוערת של מה שחשוב. באתר shager.ai מפת האתר מופיעה בתוך llms.txt תחת `Optional`.

### מה עדיף לסוכן, OpenAPI או שרת MCP?

תלוי איפה הסוכן רץ. סוכן בתוך Claude Code, Cursor או Codex עובד הכי טבעי עם שרת MCP. סקריפט או שירות בקוד ישתמשו בממשק REST לפי מפרט OpenAPI. בְּשַׁגֵּר שניהם חושפים את אותן פעולות, כך שאין צורך לבחור פעם אחת ולתמיד.

---
Source: https://shager.ai/blog/agent-ready-websites-llms-txt