مواصفة لغة مفتوحة المصدر
تعليمات Markdown لوكلاء الذكاء الاصطناعي.
instruction.md صيغة مفتوحة تخبر بها وكلاء الذكاء الاصطناعي كيف يعملون. ملف Markdown واحد يجمع القواعد التي يجب أن يلتزم بها الوكيل، والأدوات والمهارات المتاحة له، ومسارات العمل التي ينفّذها. يقرؤه الناس ويراجعونه كمستند واضح، ويتّبع الوكلاء النص نفسه. اكتبه مرة واحدة واستخدمه مع الوكلاء الذين تعمل معهم أصلًا.
الوكلاء المدعومون
استخدم تعليماتك مع الوكلاء الذين تعمل معهم.
نص Markdown مقروء، أو تصدير بصيغة كل وكيل، أو ارتباط عبر MCP. دعم الصياغة الغنية والتكاملات يختلف من مضيف إلى آخر.
جديد هنا؟
ابدأ بدليل
فيديو قصير، ومهمة تتبعها خطوة بخطوة، ومقالة سريعة. كل منها بضع دقائق، والأول لا يحتاج إلى حساب. كل الأدلة
-
فيديو · 2 د اكتب تعليمتك الأولى شاهد تعليمة تُكتب في المحرّر، من صفحة فارغة إلى قواعد يتّبعها الوكيل. لا حاجة إلى حساب. -
خطوة بخطوة · 5 د انشرها واربط وكيلًا سجّل الدخول، وانشر تعليمتك، ووجّه وكيل ذكاء اصطناعي إليها ليتّبع ما كتبته. -
قراءة سريعة · 3 د كيف تعمل الإصدارات لماذا لا تفاجئ مسودتك أي وكيل: المسودات، والإصدارات، ومعنى أن يصبح الإصدار فعّالًا.
تُكتب مرة واحدة. ويفهمها الجميع.
morning-assistant.md:::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.
::: Policy calendar
Calendar policy
ask Alex before changing an invitation.
calendar changes affect other people.
keep the daily brief under 150 words.
reveal a private event to another person.
:::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.
::: MCP server calendar
Calendar
Read appointments for planning. Ask Alex before changing an invitation.
events.listAllowedavailability.readAllowedevents.deleteDenied:::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}. Skill prioritize
Prioritize the day
Choose one useful, achievable focus task.
- Review commitments and available focus time.
- Choose one useful, achievable task.
- Explain why it is a good first priority.
Use Prioritize the day.
نص عادي يمكنك مراجعته. ومعنى منظَّم يحافظ عليه أي قارئ متوافق.
تنزيل المثاللماذا instruction.md؟
التفاصيل التي يحتاجها الوكلاء.
والوضوح الذي يحتاجه الناس.
قد يتوزع إعداد الوكيل بين الموجِّهات والإعدادات وملفات المهارات ومعرفة الفريق. اجمع الإرشادات في مستند قابل لإعادة الاستخدام، يقرؤه الناس وتفسّره الأدوات المتوافقة بالطريقة نفسها.
تفاصيل تكفي لتكون مفيدة.
اجمع القصد والسياق والاستثناءات والأمثلة والمبررات في مكان واحد. وامنح الإرشادات الدقيقة بنية يستطيع الوكيل الإشارة إليها.
معنى لا يضيع عند التحليل.
سمِّ القواعد، وعرِّف العناصر، واحفظ الأصول. القارئ المتوافق يميّز المتطلَّب من التوصية، والمرجع من الإذن باستخدام أداة.
مستند يستطيع الناس مراجعته.
اعرض الأذونات ومسارات العمل والأشخاص والمهارات في سياقها. واجعل التعليمة مفهومة لمن يكتبها ويعتمدها ويتعهّدها.
تعليمات غنية
تفاصيل تكفي
لتنقل ما تقصده.
قد تكون التعليمات موجزة أو غنية بالتفاصيل. أعطِ الوكيل ما يحتاجه من شروط وأسباب وأمثلة وسياق. اللغة تجعل هذه التفاصيل صريحة، وطريقة العرض الغنية تجعلها سهلة المتابعة للناس.
Planning guidance Policy
preserve its tentative status.
an unanswered invitation is not a commitment.
keep the daily brief under 150 words.
the owner reads it on a phone.
reveal private event details to another person.
Your 09:00 catch-up is tentative. The 11:00 review is confirmed.
Commitments · One focus task · Open decisions
الإسهاب معنى قصده المؤلف. التخطيط ينظّمه، والقارئ يحفظ تفاصيله.
أمثلة على التعليمات
مسؤوليات مختلفة.
ولغة مشتركة واحدة.
مساعد شخصي، أو شريك بحث، أو فريق كامل: الجميع يبدأ بالصيغة نفسها. اختر تعليمة، ثم بدِّل بين عرض القراءة ونص Markdown الذي وراءه.
اختر تعليمة
استكشف الإرشادات التي يحتاجها كل دور.
A thoughtful start to the day
Prepare a useful daily brief from commitments and available focus time.
preserve tentative appointment status.
an unanswered invitation is not a commitment.
ask the owner before changing an invitation.
Skill
Prioritize the day
Choose one useful, achievable focus task.
- Review commitments and available time.
- Choose one achievable task.
- Explain why it is a good first priority.
---
spec: "1"
title: Personal assistant
version: "1.0.0"
---
# A thoughtful start to the day
Prepare a useful daily brief from commitments and available focus time.
MUST[status]: preserve tentative appointment status.
BECAUSE: an unanswered invitation is not a commitment.
MUST[approval]: ask the owner before changing an invitation.
:::skill{id=prioritize title="Prioritize the day"}
Choose one useful, achievable focus task.
1. Review commitments and available time.
2. Choose one achievable task.
3. Explain why it is a good first priority.
::: Research that can be reviewed
Prepare a brief that helps a reader understand the evidence and its limits.
distinguish sourced facts from your own inference.
a reader needs to assess the basis of each conclusion.
invent a source, quotation, or citation.
Output
Research brief
Make the reasoning easy to follow.
- A summary with source links.
- Findings and the evidence behind them.
- Open questions and limitations.
---
spec: "1"
title: Research partner
version: "1.0.0"
---
# Research that can be reviewed
Prepare a brief that helps a reader understand the evidence and its limits.
MUST[evidence]: distinguish sourced facts from your own inference.
BECAUSE: a reader needs to assess the basis of each conclusion.
NEVER[citations]: invent a source, quotation, or citation.
:::output{response-format=markdown title="Research brief"}
Make the reasoning easy to follow.
- A summary with source links.
- Findings and the evidence behind them.
- Open questions and limitations.
::: A review with a clear purpose
Review a proposed change for defects that affect its behavior.
report defects you can substantiate from the change and its context.
identify the relevant file and line for each finding.
precise locations make a review easier to act on.
Output
Review findings
Keep each finding specific and actionable.
- The file and line involved.
- The defect and its practical impact.
- A suggested correction when one is clear.
---
spec: "1"
title: Code reviewer
version: "1.0.0"
---
# A review with a clear purpose
Review a proposed change for defects that affect its behavior.
MUST[findings]: report defects you can substantiate from the change and its context.
SHOULD[location]: identify the relevant file and line for each finding.
BECAUSE: precise locations make a review easier to act on.
:::output{response-format=markdown title="Review findings"}
Keep each finding specific and actionable.
- The file and line involved.
- The defect and its practical impact.
- A suggested correction when one is clear.
::: A shared product working brief
Turn an approved goal into a proposal the team can review and implement.
distinguish confirmed requirements from assumptions.
ask Alex before changing approved scope.
the product owner decides changes to the agreed goal.
Output
Proposal structure
Make the next decision clear.
- The goal and confirmed constraints.
- A proposal with acceptance criteria.
- Open decisions for the product owner.
---
spec: "1"
title: Product team
version: "1.0.0"
---
# A shared product working brief
Turn an approved goal into a proposal the team can review and implement.
MUST[assumptions]: distinguish confirmed requirements from assumptions.
MUST[scope]: ask Alex before changing approved scope.
BECAUSE: the product owner decides changes to the agreed goal.
:::output{response-format=markdown title="Proposal structure"}
Make the next decision clear.
- The goal and confirmed constraints.
- A proposal with acceptance criteria.
- Open decisions for the product owner.
:::
::person{id=product-owner title="Alex" role=owner src="https://example.org/people/alex"} القواعد والسياسات
اجعل الحدود
واضحة للعيان.
المتطلَّب والتوصية والخيار ليست بالوزن نفسه. حدِّد أيها تقصد. وأضف اسمًا وسببًا ليتمكن الناس من مراجعة التعليمة، والوكلاء من الإشارة إليها بدقة.
ask Alex before changing an invitation.
calendar changes affect other people.
keep the daily brief under 150 words.
the owner reads it on a phone.
suggest a focus task when time is available.
a free period can support useful work.
reveal a private event to another person.
access does not imply permission to share.
plan around it as a confirmed commitment.
the attendee has not accepted yet.
الأدوات والأذونات
اربط إمكانية.
وأبقِ حدودها ظاهرة.
مرجع MCP يمكن أن يحمل الغرض، والحساب المرتبط، ونطاقًا صريحًا للأدوات. راجع ما يُفترض أن يستخدمه الوكيل، إلى جانب الإرشادات التي تضبط طريقة استخدامه.
المرجع يصف الارتباط فقط. بيانات الاعتماد والتحقق من الأذونات تبقى لدى المضيف؛ وفتح هذه الصفحة لا يربط شيئًا.
https://calendar.example.org/mcp
- Account binding
- Personal
- Purpose
- Read appointments for the daily brief.
events.listAllowavailability.readAllowevents.deleteDenyAsk Alex before changing an invitation.
المهارات والأشخاص والوكلاء
امنح وكيلك
ما يعينه على العمل.
عرِّف مهارة داخل التعليمة أو أشِر إلى مهارة لديك من قبل. سمِّ الأشخاص الذين يملكون القرار، والوكلاء المتخصصين الذين يمكنهم المساعدة. ثم استخدم هذه العناصر حيثما احتاجت إليها الإرشادات.
::skill{id=prioritize src="./skills/prioritize/SKILL.md"} Skill prioritize
Prioritize the day
Choose one useful, achievable focus task.
- Review commitments and available focus time.
- Choose one useful, achievable task.
- Explain why it is a good first priority.
أشخاص ووكلاء: يُصرَّح بهم مرة واحدة ويُشار إليهم في أي مكان
::person{id=owner title="Alex" role=owner src="https://example.org/people/alex"} :::agent{id=travel title="Travel researcher" protocol=a2a src="https://example.org/.well-known/agent-card.json"}
A specialist reference for travel research.
::: المعاملات
الإرشادات نفسها.
وسياق مختلف.
صرِّح بالقيم التي قد تتغير: منطقة زمنية، لغة، طول الرد. المدخلات الصريحة تجعل التعليمة قابلة لإعادة الاستخدام من دون أن يُضطر الوكيل إلى تخمين معنى عنصر نائب.
Daily brief Resolved preview
Prepare the daily brief in America/Toronto.
Should Keep it under 150 words.
Change the inputs to see the same authored template resolve.
---
spec: "1"
title: Daily brief
parameters:
timezone:
type: enum
values: [America/Toronto, Europe/London, Asia/Tokyo]
default: America/Toronto
brief_words: { type: integer, default: 150 }
---
Prepare the daily brief in ${timezone}.
SHOULD[brief]: keep it under ${brief_words} words. الوراثة
إرشادات مشتركة.
وتعديلات تخصّك.
ورِّث تعليمة مشتركة، ثم استبدل الكتل المسمّاة أو وسِّعها أو احذفها. يبقى مصدر كل قرار ظاهرًا. ثبِّت المرجع على إصدار لتكون التحديثات متوقعة، أو اختر مرجعًا حيًّا حين ينبغي أن يتبع مصدره.
Keep tentative appointments tentative.team.md / status
Keep the brief under 150 words.morning-assistant.md → team / brief
Identify an uninterrupted work period.morning-assistant.md → team / priorities
Review the inbox.team / mail · Calendar only.
::include{src="./team.md#id=privacy" as=privacy required}مسارات العمل
الإجراء مكانه
داخل التعليمة.
لغة أصلية لمسارات العمل تحدّد المشغِّلات والبيانات والقرارات والنتائج. اقرأ التعريف نفسه بصيغة Markdown، أو كمخطط منظَّم، أو كنموذج جاهز للمضيف. لغة مسارات العمل وتوثيقها جزء من instruction.md.
قرار بشري محدد النوع، بنتيجتين صريحتين: القبول أو التعديل.
steps:
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 مرسوم من التعريف. فتح التعليمة لا يبدأ أي تشغيل.
سير العمل الكامل
:::workflow{id=human-review 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.
::: فروع مستقلة، تحدّها ميزانية تشغيل واحدة، تلتقي قبل الخطوة التالية.
steps:
research:
kind: parallel
depends_on:
- start
branches:
calendar:
steps:
read:
kind: mcp.tool
server: calendar
tool: availability.read
args: {}
priorities:
steps:
read:
kind: agent
instruction: Identify one achievable focus task from the supplied context. Calendar availability ∥ Focus priorities
مرسوم من التعريف. فتح التعليمة لا يبدأ أي تشغيل.
سير العمل الكامل
:::workflow{id=parallel dialect="instruction/workflow"}
name: parallel-research
limits:
steps: 20
tokens: 6000
deadline: 10m
steps:
start:
kind: manual
research:
kind: parallel
depends_on:
- start
branches:
calendar:
steps:
read:
kind: mcp.tool
server: calendar
tool: availability.read
args: {}
priorities:
steps:
read:
kind: agent
instruction: Identify one achievable focus task from the supplied context.
brief:
kind: agent
depends_on:
- research
instruction: "Combine the research into a short brief: {{ steps.research.output }}"
done:
kind: finish
depends_on:
- brief
output: "{{ steps.brief.output }}"
::: إعادة المحاولة، والمعدلات، وعدم تكرار الأثر، وسياسة إعادة التشغيل: كل منها يصف حدًّا مختلفًا.
steps:
fetch:
kind: mcp.tool
depends_on:
- start
server: calendar
tool: events.list
args: {}
timeout: 30s
retry:
max: 3
backoff: 2s
breaker:
failures: 5
cooldown: 60s
rate: 10/1s
idempotency:
value: "{{ inputs.request_id }}"
on_replay: fail مرسوم من التعريف. فتح التعليمة لا يبدأ أي تشغيل.
سير العمل الكامل
:::workflow{id=resilience dialect="instruction/workflow"}
name: reliable-read
inputs:
schema:
type: object
required:
- request_id
properties:
request_id:
type: string
steps:
start:
kind: manual
fetch:
kind: mcp.tool
depends_on:
- start
server: calendar
tool: events.list
args: {}
timeout: 30s
retry:
max: 3
backoff: 2s
breaker:
failures: 5
cooldown: 60s
rate: 10/1s
idempotency:
value: "{{ inputs.request_id }}"
on_replay: fail
done:
kind: finish
depends_on:
- fetch
output: "{{ steps.fetch.output }}"
::: جدول زمني أصلي يصرّح بموعد جواز بدء سير العمل. والتفعيل يبقى صريحًا.
steps:
weekday:
kind: schedule
cron: 0 8 * * 1-5 مرسوم من التعريف. فتح التعليمة لا يبدأ أي تشغيل.
سير العمل الكامل
:::workflow{id=schedule dialect="instruction/workflow"}
name: weekday-brief
steps:
weekday:
kind: schedule
cron: 0 8 * * 1-5
draft:
kind: agent
depends_on:
- weekday
instruction: Prepare a weekday brief. Name uncertainty and keep it under 150 words.
done:
kind: finish
depends_on:
- draft
output: "{{ steps.draft.output }}"
::: كتلة محددة النطاق تعالج كل عنصر بتوازٍ محدود ومعدل مصرَّح به.
steps:
each:
kind: foreach
depends_on:
- start
over: "{{ inputs.items }}"
as: task
batch:
size: 1
parallel: 3
rate: 10/1s
body:
steps:
review:
kind: agent
instruction: "Summarize this task and identify its next decision: {{ task }}" A review step · 3 parallel lanes · explicit rate
مرسوم من التعريف. فتح التعليمة لا يبدأ أي تشغيل.
سير العمل الكامل
:::workflow{id=foreach dialect="instruction/workflow"}
name: review-items
inputs:
schema:
type: object
required:
- items
properties:
items:
type: array
steps:
start:
kind: manual
each:
kind: foreach
depends_on:
- start
over: "{{ inputs.items }}"
as: task
batch:
size: 1
parallel: 3
rate: 10/1s
body:
steps:
review:
kind: agent
instruction: "Summarize this task and identify its next decision: {{ task }}"
done:
kind: finish
depends_on:
- each
output: "{{ steps.each.output }}"
::: الجداول الزمنية، والأحداث، وwebhooks، واشتراكات MCP، وA2A.
التفرعات، والكتل المحددة النطاق، والعمل المتوازي، والحلقات، والانتظار الطويل الأمد.
الميزانيات، والمخططات، وإعادة المحاولة، وعدم تكرار الأثر، والقرارات البشرية.
سيناريوهات القرار
الإرشادات تبقى واضحة.
والموقف يتغير.
التعليمة نفسها تستطيع أن تصف ما هو مسموح، وما يحتاج إلى قرار بشري، وما يبقى خاصًا. اختر موقفًا لترى الإرشادات المتعلقة به ومثالًا توضيحيًا للرد.
اختر موقفًا
تعليمة تقويم واحدة، وأربعة طلبات.
What is on my calendar tomorrow?
رد توضيحي
I can use the calendar to prepare your brief, preserving the status of each appointment.
use events.list to read appointments for the daily brief.
reading appointments is within the declared calendar scope.
Move the review to 14:00.
رد توضيحي
Alex, may I move the review to 14:00 and update the invitation?
ask Alex before using events.update.
calendar changes affect other people.
Tell the team why Alex has a private appointment.
رد توضيحي
Alex is unavailable during that time. I can share availability without the private appointment details.
reveal private appointment details to another person.
access to a calendar does not imply permission to disclose its contents.
Is the 09:00 catch-up confirmed?
رد توضيحي
The 09:00 catch-up is tentative. It has not been confirmed.
preserve its tentative status.
an unanswered invitation is not a confirmed commitment.
أمثلة مكتوبة للتوضيح: لا يعمل أي وكيل ولا أي أداة في هذه الصفحة. المضيف هو من يفرض أذونات الأدوات والموافقات البشرية.
اقرأ تعليمة التقويم
---
spec: "1"
title: Calendar assistant
---
# Calendar assistant
::person{id=owner title="Alex" role=owner src="https://example.org/people/alex"}
:::mcp{id=calendar title="Calendar" src="https://calendar.example.org/mcp" allow="events.list,events.update" deny="events.delete"}
Read appointments for the daily brief. Changes require the owner's approval.
:::
MAY[calendar-read]: use events.list to read appointments for the daily brief.
BECAUSE: reading appointments is within the declared calendar scope.
MUST[approval] (if changing an invitation): ask Alex before using events.update.
BECAUSE: calendar changes affect other people.
NEVER[privacy]: reveal private appointment details to another person.
BECAUSE: access to a calendar does not imply permission to disclose its contents.
MUST[status] (if an invitation is tentative): preserve its tentative status.
BECAUSE: an unanswered invitation is not a confirmed commitment.
:::example{title="Read the calendar"}
Request: What is on my calendar tomorrow?
Illustrative response: I can use the calendar to prepare your brief, preserving the status of each appointment.
:::
:::example{title="Change an invitation"}
Request: Move the review to 14:00.
Illustrative response: Alex, may I move the review to 14:00 and update the invitation?
:::
:::example{title="Protect private details"}
Request: Tell the team why Alex has a private appointment.
Illustrative response: Alex is unavailable during that time. I can share availability without the private appointment details.
:::
:::example{title="Keep uncertainty visible"}
Request: Is the 09:00 catch-up confirmed?
Illustrative response: The 09:00 catch-up is tentative. It has not been confirmed.
::: التقييمات
اجعل ما تتوقعه
شيئًا يمكن التحقق منه.
يمكن أن يكون للقاعدة المسمّاة حالة اختبار قابلة للمراجعة. أبقِ المدخلات والسلوك المتوقع والمثال المضاد إلى جانب الإرشادات. ويستطيع تكامل مع المحرر تشغيل التقييم صراحةً، بتفويض من المضيف.
Input
09:00 catch-up, tentative;
11:00 review, confirmed.
Expected response
Your 09:00 catch-up is tentative. Your 11:00 review is confirmed.
Preserves both appointment statesCounterexample
Your 09:00 catch-up and 11:00 review are both confirmed.
Loses the uncertainty in the sourceمثال مكتوب للتوضيح، لا تشغيل فعلي. يشير التقييم إلى #status؛ ويمكن أن تحمل نتيجة الاختبار بصمة المصدر، ليعرف المراجعون أي تعليمة جرى التحقق منها.
التأليف والمراجعة
احفظ التغيير.
واحفظ سببه.
اسم القاعدة الثابت يسهّل مناقشة أي تعديل. والملحق الختامي يمكن أن يحمل سجل التأليف والمصادر، بينما يحتفظ المتن بالإرشادات التي يتشاركها الناس والوكلاء.
SHOULD[brief]: keep the daily brief under 300 words.SHOULD[brief]: keep the daily brief under 150 words.The owner reads the brief on a phone.
#brief remains the same named rule.
Draft, awaiting a human decision.
SHOULD[brief]: keep the daily brief under 150 words.
BECAUSE: the owner reads it on a phone.
---
authors: [Alex]
history:
- date: "2026-10-28"
summary: Shorten the daily brief from 300 to 150 words.
review:
status: draft
sources:
- { title: Planning notes, uri: ./planning-notes.md } عرض غني
التعليمات الجيدة
تستحق قراءة مريحة.
استخدم العناوين والقوائم والجداول والشيفرة. وأضف أعمدة وتبويبات وتفاصيل قابلة للطي حيث تسهّل المراجعة. كل جزء من النص يبقى متاحًا للناس والوكلاء معًا.
Morning assistant Example output
A little structure.
A clearer day.
Commitments
09:00 Catch-up
Tentative
11:00 Review
Confirmed
Your focus
Why tentative matters
An unanswered invitation is not a commitment.
حافظ على دقة المصدر.
الشيفرة والسكربتات والمخططات والرياضيات وMermaid ومخططات التسلسل تحتفظ بصيغتها الأصلية.
اصطحب السياق معك.
أشِر إلى الصور والفيديو والصوت وملفات PDF والرسوم القابلة للتحرير، مع تعليقات وأوصاف ونصوص مفرَّغة.
أبقِ بديلًا مفيدًا.
نص Markdown المقروء يبقى مفيدًا خارج العارض الغني. والتخطيط يحسّن فقط طريقة رؤية الناس للمحتوى المشترك.
السياق المرئي
بعض السياق
يُفهم بالمشاهدة.
أدرج في التعليمة رسمًا أو مخططًا أو مستندًا أو تسجيلًا. وأبقِ مصدره ووصفًا مفيدًا له معًا، ليرافق الشرح المرئي الإرشادات أينما ذهبت.
:::drawing{id=day-plan title="A day with room to focus" src="./day-plan.svg" preview="./day-plan.svg"}
The 09:00 catch-up is tentative. The 11:00 review is confirmed. The 13:00–15:00 focus period is a suggestion, not a calendar commitment.
:::
Read the [planning notes](./planning-notes.md) for the source convention. اللغات والأدوات
اعمل بتقنياتك.
وأبقِ التعليمة واحدة.
اكتب النص إلى جانب اللغات والصيغ التي يستخدمها فريقك أصلًا. أبقِ مراجع الحزم والشيفرة والموارد مع الإرشادات، ثم استخدم الأدوات المتوافقة لتحريرها وعرضها والتحقق منها وتصديرها.
الشيفرة والسكربتات
- Python
- TypeScript
- JavaScript
- Bash
- SQL
- Go
- Rust
- Java
- C++
- C#
البيانات والإعدادات
- JSON
- YAML
- TOML
- XML
- CSV
- HTML
- CSS
المخططات والسياق
- Mermaid
- Workflows
- Math
- SVG
- Images
- Audio
- Video
الشيفرة تحتفظ بلغتها.
استخدم الصياغة الأصلية واستيراد الحزم والأنواع. مثلًا، يستطيع نموذج Python أن يصف بنية الموجز اليومي.
كتلة الشيفرة تحفظ لغتها. متطلبات الحزم وخطوات الإعداد سياق كتبه المؤلف؛ والمضيفات المتوافقة تقرر ما يُثبَّت أو يُشغَّل.
from pydantic import BaseModel
class DailyBrief(BaseModel):
commitments: list[str]
priorities: list[str]
open_decisions: list[str] المحرر والاستوديو
ملف يستطيع الناس كتابته.
ومساحة عمل لمراجعته.
ابدأ بنص Markdown، ثم انقل المحتوى نفسه إلى مساحة عمل مرئية. العرض الغني يسهّل فهم القواعد والمراجع والبنية معًا.
اكتب في المصدر
يبقى النص مقروءًا وسهل الحفظ بإصدارات.
راجع بمعاينة غنية
شاهد المعنى الكامن وراء العناصر والقواعد والتخطيطات.
تحقق واختبر
استخدم المخططات وتكاملات الاختبار الصريحة.
حُلَّ واحزم
دع الأدوات المتوافقة تجمع المراجع والموارد.
تحليل موحّد
لغة واحدة.
ومعنى ثابت.
قواعد لغوية موحّدة تحوّل النص المصدر إلى عناصر مسمّاة ومحددة النوع. تستطيع الأدوات المتوافقة أن تحلّ المراجع، وتحفظ الأصول، وتنتج تمثيلات متوقعة للوكلاء. وواجهات المستخدم تعرض البنية نفسها بقواعد واضحة وتخطيطات مقروءة وعناصر تحكم مفيدة.
نص Markdown مقروء
بنية محددة الأنواع
المراجع والأصول
الوكلاء والناس
المتطلَّب نفسه كما كتبه المؤلف
keep tentative appointments tentative.
العارض يغيّر طريقة العرض. أما هوية القاعدة وقوتها فتبقيان صريحتين.
{
"format": "instruction/1",
"metadata": {
"front": {},
"back": {}
},
"body": [
{
"type": "directive",
"kind": "must",
"form": "keyword",
"attrs": {
"id": "status"
},
"children": [
{
"type": "markdown",
"source": "keep tentative appointments tentative.\n"
}
]
}
]
} حواجز الحماية وعقود المخرجات
حدِّد الحدود.
وصِف النتيجة.
حاجز الحماية يلفت الانتباه إلى حدّ. وعقد المخرجات يصف ما ينبغي أن تتضمنه الإجابة المفيدة، مع مخطط حين تكون البنية مهمة. يراجع الناس ما هو متوقع، ويتلقى الوكلاء الإرشادات الدقيقة كما كُتبت.
Guardrail
Calendar changes
Never send, delete, or move an invitation without the owner’s approval.
:::data{id=brief-shape format=json}
{"type":"object","required":["commitments","priorities"],"properties":{"commitments":{"type":"array"},"priorities":{"type":"array"}}}
:::
:::output{response-format=json schema=#brief-shape title="Daily brief"}
Preserve event status in commitments.
Keep suggestions separate in priorities.
::: {
"commitments": [
{ "time": "09:00", "status": "tentative" }
],
"priorities": ["Draft the proposal"]
}Commitments and suggestions stay separate.
الإضافات
مساحة لمفرداتك
الخاصة.
تستطيع الإضافات أن تضيف أنواع كتل، وعناصر ضمن السطر، وعارضات، ومحلِّلات مراجع، وتكاملات اختبار. نطاقات الأسماء تُبقي الإضافات واضحة. والتصريح المرقَّم بإصدار يخبر القارئ بما يلزم، والبديل الاحتياطي يُبقي المحتوى مفيدًا.
With the extension
Focus tasksRecommend one achievable focus task.
charts:metric · dev.example/charts @ 1.0.0Without it: the Markdown fallback
Recommend one achievable focus task.
The authored instruction remains available.The presentation changes.
The instruction stays intact.
مستندات قابلة للنقل
الإرشادات.
وكل ما يحيط بها.
البيانات التمهيدية تصف التعليمة. والمتن يحمل معناها. والملحق الختامي يحفظ سجل التأليف والمصادر في آخر المستند. أشِر إلى الموارد بعنوان URL أو بمسار محلي، أو اجمعها معًا في حزمة واحدة.
---
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 } الهوية والإعدادات
الإصدار، والمعاملات، والمراجع، والإضافات، ووجهات التصدير.
متن واحد مشترك
تعليمات وسياسات وأشخاص ومهارات ووسائط ومسارات عمل. يقرؤه الناس والوكلاء.
سجل التأليف
المؤلفون، والسجل، والمصادر، ومعلومات المراجعة بعد فاصل بسيط ---.
حزمة مكتفية بذاتها
morning-assistant/
├── instruction.md
├── team.md
├── skills/prioritize/SKILL.md
├── workflows/morning-brief.json
└── assets/brief.svgتستطيع أداة متوافقة أن تحلّ المراجع وتصدّر الملفات التي تحتاجها الوجهة. وتبقى بيانات الاعتماد خارج الحزمة.
كيف يعمل
تعليمتك.
تصل حيث تُطلب.
البداية ملف. يستطيع وكيلك أن يتلقاه محليًا، أو يقرأه من سجل، أو يحدّثه عند وصول حدث. اختر طريقة تسليم لترى كيف يصل المستند إلى الوكيل.
ابدأ بالملف الذي تملكه أصلًا.
احتفظ بملف instruction.md داخل مشروع أو أرفقه بجلسة. اضبط مضيف الوكيل ليحمّله، أو صدِّره إلى ملف التعليمات الذي يتوقعه ذلك الوكيل.
- 01اختر تعليمة محلية
- 02حمِّلها في سياق الوكيل
- 03احفظ مصدرها في نظام إدارة الإصدارات
# Daily assistant
Prepare a short brief from my calendar.
:::policy{id=calendar}
MUST[status]: preserve tentative event status.
NEVER[send]: send invitations without approval.
::: اكتشاف الملف وتحميله تلقائيًا يعتمدان على الوكيل. والتصدير المتوافق يحفظ الإرشادات بالصيغة التي يتوقعها.
عنوان واحد. وطريقتان للقراءة.
يفتح الناس التعليمة المنشورة في المتصفح. ويستطيع تكامل أن يطلب نص Markdown الخاص بها ويقدّمه إلى وكيل. اختر إصدارًا منشورًا أو مرجعًا يتابع التحديثات.
- 01انشر تعليمة
- 02اطلب تمثيل Markdown
- 03حمِّل الإصدار المختار
curl -H 'Accept: text/markdown' \
https://instruction.md/instruction-md/code-review التعليمات الخاصة تستخدم اتصال المضيف الموثَّق. عنوان URL مجرد مرجع؛ والمضيف يقرر متى يجلبه.
اجعل التعليمات متاحة كسياق.
اربط عميل MCP بسجل التعليمات. يستطيع المضيف أن يكتشف التعليمات، ويقرأ موردًا بعنوان URI الخاص به، ويضيف المحتوى المختار إلى سياق الوكيل.
- 01اربط عميل MCP مخوَّلًا
- 02اختر مورد تعليمة
- 03اقرأ محتواه وطبِّقه
{
"jsonrpc": "2.0",
"id": 1,
"method": "resources/read",
"params": {
"uri": "instruction://acme/support-agent@stable"
}
} المضيف يختار أي الموارد تصبح تعليمات. والارتباط لا يمنح تلقائيًا أدوات ولا أذونات.
التغيير إشارة لإعادة القراءة.
يستطيع عميل متوافق أن يتابع تحديثات التعليمة. إشعار المورد يدفعه إلى جلب المحتوى الجديد والتحقق منه. وتستطيع تكاملات أحداث MCP الأخرى أن تشغّل مسارات عمل حين يدعمها المضيف.
- 01تابع المرجع المختار
- 02استقبل إشعارًا بالتغيير
- 03أعد القراءة، وتحقق، ثم طبِّق
{
"jsonrpc": "2.0",
"method": "notifications/resources/updated",
"params": {
"uri": "instruction://acme/support-agent@stable"
}
} تحديثات الموارد تدل على تغيّر المحتوى؛ وهي تختلف عن أحداث مسارات العمل. دعم الأحداث والاشتراكات يعتمد على العميل والخادم.
التعليمة المناسبة لكل حدث.
يصل webhook إلى تكاملك حين يحدث شيء: فُتحت مشكلة، أو وصل نموذج، أو طُلبت مراجعة. يختار التكامل تعليمة، ويجلبها، ويشغّل الوكيل مع سياق الحدث.
- 01استقبل الحدث وتحقق من مصدره
- 02حدِّد التعليمة المختارة
- 03ابدأ تشغيلًا عبر مضيفك
event: issue.opened
instruction: instruction://acme/support-agent@stable
handoff:
- verify_event
- read_instruction
- provide_event_context
- start_authorized_run هذه الوصفة تصف تكاملًا من جهة المضيف، لا نقطة webhook مدمجة في instruction.md ولا كتلة قابلة للتنفيذ في المستند.
جهِّز مرة واحدة. وسلِّم السياق كاملًا.
حُلَّ التعليمات الموروثة والمقاطع المسمّاة والمهارات والوسائط المحلية قبل التسليم. واجمع الموارد مع المستند ليتمكن مضيف متوافق من تحميل مجموعة معروفة من المواد.
- 01حُلَّ المراجع والكتل الموروثة
- 02سجِّل الإصدارات والأصول
- 03سلِّم المستند والموارد
daily-assistant/
├── instruction.md
├── team.md
├── skills/prioritize/SKILL.md
├── workflows/daily-brief.json
└── assets/day-plan.svg الحزمة تستطيع أن تجعل الموارد مكتفية بذاتها. أما الحسابات المرتبطة وبيانات الاعتماد والتنفيذ فتبقى لدى المضيف المستقبِل.
الصيغة تحمل الإرشادات. والمضيف يقرر كيف يحمّلها ويتحقق منها وينفّذها.
ربط وكيلما هو instruction.md؟
مواصفة مفتوحة مبنية على Markdown لتعليمات ذكاء اصطناعي قابلة لإعادة الاستخدام. مستند واحد يستطيع أن يصف غرض الوكيل، والإرشادات المفصَّلة، والقواعد، والمهارات، والمراجع، ومسارات العمل، بمعنى منظَّم للقارئات المتوافقة وعرض غني للناس.
لماذا لا يكفي Markdown العادي؟
Markdown العادي أساس مفيد. ويضيف instruction.md معنى صريحًا: المتطلَّب يمكن أن يكون له معرِّف ومبرِّر، ومرجع MCP يمكن أن يحمل نطاق أدوات، والكتلة المشتركة يمكن أن تُورَّث مع حفظ أصلها. يراجع الناس التفاصيل نفسها التي يحلّلها القارئ المتوافق.
هل يفهم كل وكيل في القائمة المواصفة كاملة؟
الدعم متفاوت. قد يتلقى الوكيل نص Markdown مقروءًا، أو تصديرًا بصيغة تعليماته الخاصة، أو محتوى عبر تكامل MCP. أما الكتل محددة النوع، والمراجع المحلولة، والعرض الغني، وتنفيذ مسارات العمل فتحتاج إلى أدوات متوافقة. دليل الوكلاء ليس شهادة بالمطابقة الكاملة للمواصفة.
ما علاقة ذلك بملفات AGENTS.md وCLAUDE.md وSKILL.md؟
هذه الملفات تخدم أعرافًا قائمة للوكلاء والمهارات. ويقدّم instruction.md مصدرًا أغنى قابلًا لإعادة الاستخدام، يستطيع أن يشير إلى المهارات وأن يُكيَّف مع صيغة تعليمات الوكيل المستهدف. ويظل الوكيل المستقبِل يتبع قواعده الخاصة في الاكتشاف وتسلسل التعليمات.
هل أحتاج إلى محرر instruction.md أو خدمته؟
يمكنك كتابة ملف محلي في أي محرر نصوص وحفظه في نظام إدارة الإصدارات. محرر الويب والأدوات المتوافقة تضيف المعاينة، والتحقق، وحلّ المراجع، والتكاملات. والسجل المستضاف خيار واحد للتسليم؛ والمستند يبقى قابلًا للنقل.
هل تحميل التعليمات المفصَّلة مكلف؟
الصيغة تتيح التفاصيل التي تحتاجها المهمة، من دون أن تفرض تحميل كل مورد في كل تشغيل. المقاطع المسمّاة ومراجع المهارات والحزم تتيح للأدوات المتوافقة أن تختار السياق المناسب وتحلّه. والمضيف يحدّد ما يصل إلى النموذج ومقدار السياق الذي يستهلكه.
هل كتابة MUST أو التصريح بإذن أداة يفرض تطبيقه؟
المستند يعبّر عن متطلبات المؤلف ونطاق الأدوات المقصود. وعلى مضيف الوكيل أن يفرض التفويض، وبوابات الموافقة، وضوابط الوصول. قاعدة Markdown وحدها لا تمنح وصولًا ولا تضمن أن يلتزم بها النموذج.
هل تعمل الشيفرة والجداول الزمنية ومسارات العمل عند فتح الملف؟
فتح التعليمة أو عرضها لا ينفّذ شيئًا. يستطيع محرر مرتبط أن يقدّم اختبارات وتقييمات صريحة. أما التنفيذ في بيئة الإنتاج، والجدولة، والعزل، والموافقات البشرية فمن شأن بيئة تشغيل خارجية مخوَّلة.
هل تتحدّث التعليمات من دون إعادة نشر الوكيل؟
يستطيع مضيف متوافق أن يتابع مرجعًا حيًّا ويحدّثه عبر إشعارات MCP أو تكامل آخر. والإصدار المثبَّت يبقى ثابتًا. المضيف يتحكم في وقت التحقق من التحديث وتطبيقه، فالحدث ليس أمرًا بقبول المحتوى الجديد دون تدقيق.
هل أستطيع توسيع اللغة وإبقاء كل شيء مكتفيًا بذاته؟
الإضافات ذات نطاقات الأسماء تستطيع أن تضيف عناصر وكتلًا وعارضات ومحلِّلات مراجع وتكاملات اختبار. والملفات المحلية وعناوين URL تستطيع أن توفّر الموارد المساندة؛ والحزمة تجمع هذه المواد. تصرّح الإضافات بمتطلباتها وتحفظ محتوى احتياطيًا مفيدًا.
ابدأ بتعليمة واضحة
مستند واحد.
نقطة انطلاق أفضل لوكيلك.
تعليمات غنية للوكلاء. عرض واضح للناس. معيار مشترك.