اللغة

التعليمة كتابة عادية. وبضع إضافات صغيرة تتيح لك أن تقول بدقة ما يهمّ، فيستطيع الناس مراجعتها ويفهمها كل وكيل بالطريقة نفسها. تعرضها هذه الجولة واحدة تلو الأخرى، بالمثال نفسه من البداية إلى النهاية: مساعد ينظّم يوم شخص ما. الأمثلة نفسها بالإنجليزية، كما كُتبت.

ابدأ بكتابة عادية

معظم التعليمة نثر: ما الغاية من الوكيل وكيف ينبغي أن يعمل. ترويسة قصيرة في الأعلى تعطي المستند عنوانًا وإصدارًا. أما الملاحظات الموجّهة إلى الناس، مثل من كتبه ولماذا تغيّر، فتأتي في آخره تمامًا، ولا يستلمها الوكيل أبدًا.

morning-assistant.md
---
spec: "1"
title: Morning assistant
version: "1.0.0"
---

# Morning assistant

Prepare a useful daily brief.

MUST[status]: keep tentative appointments tentative.
BECAUSE: an invitation is not a commitment.

---
authors: [Alex]
history:
  - summary: Preserve appointment status.
sources:
  - { title: Team guidance, uri: ./team.md }

القواعد

السطر الذي يبدأ بإحدى خمس كلمات هو قاعدة. الكلمة تبيّن مدى قوّتها، واسم اختياري بين قوسين مربّعين يتيح للناس الإشارة إليها. وتأتي BECAUSE: في السطر التالي لتذكر السبب، وهذا يساعد الوكيل على تطبيق القاعدة بحكمة.

الكلمةمعناهامثال
MUSTمطلب إلزاميask Alex before changing an invitation.
SHOULDخيار افتراضي مدروسkeep the daily brief under 150 words.
MAYخيار مسموح بهsuggest a focus task when time is available.
NEVERحظرreveal a private event to another person.
SHOULD NOTتصرّف غير مستحسنplan around it as a confirmed commitment.
قاعدة وسببها
MUST[approval]: ask Alex before changing an invitation.
BECAUSE: calendar changes affect other people.

ويمكن أن تذكر القاعدة أيضًا متى تنطبق، بين قوسين بعد كلمتها:

قاعدة لها شرط
SHOULD NOT (if an invitation is tentative): plan around it as a confirmed commitment.
BECAUSE: the attendee has not accepted yet.

السياسات وحواجز الحماية

القواعد التي تنتمي إلى موضوع واحد يمكن جمعها في سياسة لها عنوانها الخاص، فتُراجَع وتُشارَك وتُستبدَل كوحدة واحدة. وحاجز الحماية يعلّم حدًّا ينبغي أن يلفت نظر كل من يقرأ.

سياسة
:::policy{id=calendar title="Calendar policy"}
MUST[approval]: ask Alex before changing an invitation.
BECAUSE: calendar changes affect other people.

SHOULD[brief]: keep the daily brief under 150 words.

NEVER[privacy]: reveal a private event to another person.
:::
حاجز حماية
:::guardrail{id=calendar-changes title="Calendar changes"}
Never send, delete, or move an invitation without the owner's approval.
:::

تعليمات مفصّلة

القواعد القصيرة لا تكفي دائمًا. يمكنك أن تضيف شروطًا، ومثالًا على النتيجة الجيدة، وشكل الإجابة التي تتوقعها. كل جزء موسوم بما هو عليه، فيميّز الوكيل الإرشاد من المثال، ويراها القارئ معروضة بوضوح.

إرشاد، ومثال، والناتج المتوقع
:::policy{id=planning title="Planning guidance"}
MUST[status] (if an invitation is tentative): preserve its tentative status.
BECAUSE: an unanswered invitation is not a commitment.

SHOULD[brief]: keep the daily brief under 150 words.
BECAUSE: the owner reads it on a phone.

NEVER[privacy]: reveal private event details to another person.
:::

:::example{title="Preserve the uncertainty"}
Your 09:00 catch-up is tentative. The 11:00 review is confirmed.
:::

:::output{response-format=markdown title="Daily brief"}
Use commitments, one focus task, and open decisions.
:::

الأدوات

يمكن أن تسمّي التعليمة الأدوات التي يجوز للوكيل استخدامها، مثل تقويم مربوط عبر MCP، وأن تحدّد أيّ إجراءاته مسموح به. هنا يجوز للمساعد أن يقرأ الأحداث وأوقات التفرّغ (events.list, availability.read)، لكنه لا يحذف حدثًا أبدًا (events.delete).

ربط بأداة
:::mcp{id=calendar title="Calendar" src="https://calendar.example.org/mcp" account=personal tools="events.list,availability.read" allow="events.list,availability.read" deny="events.delete"}
Read appointments for planning. Ask Alex before changing an invitation.
:::

المهارات

المهارة طريقة قابلة لإعادة الاستخدام لإنجاز مهمة واحدة، مكتوبة في خطوات. اكتبها مرة واحدة، وأعطها اسمًا، وأشر إليها حيثما احتجت إليها. هذه المهارة اسمها «Prioritize the day» (ترتيب أولويات اليوم): اختيار مهمة واحدة مفيدة وممكنة الإنجاز للتركيز عليها.

مهارة وإشارة إليها
:::skill{id=prioritize title="Prioritize the day"}
Choose one useful, achievable focus task.

1. Review commitments and available focus time.
2. Choose one useful, achievable task.
3. Explain why it is a good first priority.
:::

Use :skill[Prioritize the day]{ref=#prioritize}.

الأشخاص

كثيرًا ما تعتمد التعليمات على أشخاص: من صاحب القرار، ومن يجب أن يوافق على تغيير. أعلن الشخص مرة واحدة، فتستطيع القواعد أن تشير إليه باسمه. كل من يقرأ يرى من المقصود، وتستطيع الأدوات أن تضع رابطًا إليه.

شخص، وقاعدة تذكره باسمه
::person{id=owner title="Alex" role=owner src="https://example.org/people/alex"}

MUST[approval]: ask :person[Alex]{ref=#owner} before changing an invitation.
BECAUSE: calendar changes affect other people.

جمع كل شيء معًا

هذا هو المساعد كاملًا في ملف واحد: ترويسته، وغايته، وقاعدة، والتقويم الذي يجوز له استخدامه، ومهارة، وسير عمل صغير، والملاحظات الموجّهة إلى الناس. افتح المحرّر لتكتب تعليمتك؛ فهو يعرض المستند نفسه كصفحة يستطيع الناس قراءتها.

morning-assistant.md
---
spec: "1"
title: Morning assistant
version: "1.0.0"
---

# Morning assistant

Prepare a useful daily brief.

MUST[status]: keep tentative appointments tentative.
BECAUSE: an invitation is not a commitment.


:::mcp{id=calendar title="Calendar" src="https://calendar.example.org/mcp" account=personal tools="events.list,availability.read" allow="events.list,availability.read" deny="events.delete"}
Read appointments for planning. Ask Alex before changing an invitation.
:::

:::skill{id=prioritize title="Prioritize the day"}
Choose one useful, achievable focus task.

1. Review commitments and available focus time.
2. Choose one useful, achievable task.
3. Explain why it is a good first priority.
:::

Use :skill[Prioritize the day]{ref=#prioritize}.

:::workflow{id=brief dialect="instruction/workflow"}
name: morning-brief
steps:
  start:
    kind: manual
  read:
    kind: mcp.tool
    depends_on:
      - start
    server: calendar
    tool: events.list
    timeout: 30s
    retry:
      max: 2
      backoff: 2s
  draft:
    kind: agent
    depends_on:
      - read
    instruction: Prepare a daily brief. Keep tentative appointments tentative.
  review:
    kind: human
    depends_on:
      - draft
    question: Accept this daily brief?
    schema:
      type: string
      enum:
        - accept
        - revise
    timeout: 2h
  route:
    kind: switch
    depends_on:
      - review
    on: "{{ steps.review.output }}"
    cases:
      accept: accepted
      revise: revision
  accepted:
    kind: finish
    depends_on:
      - route
    output: "{{ steps.draft.output }}"
  revision:
    kind: finish
    depends_on:
      - route
    status: cancelled
    reason: The reviewer requested a revision.
:::

---
authors: [Alex]
history:
  - summary: Preserve appointment status.
sources:
  - { title: Team guidance, uri: ./team.md }

إلى أين بعد ذلك

  • سير العمل: إجراءات فيها خطوات وقرارات وموافقات.
  • المفاهيم: كيف تُحفظ إصدارات التعليمات، وكيف تُشارَك وتُتّبع.
  • المواصفة (بالإنجليزية): كل جزء من اللغة، بدقة.