potato-skill: بناء دراسة تعليق توضيحي مع وكيل برمجة

يمكنك بدء مشروع Potato بطريقتين. اكتب المهمة بنفسك كما يبيّن البدء السريع، أو صِف الدراسة لوكيل برمجة ودع potato-skill يصمّمها ويبنيها. تتناول هذه الصفحة الطريق الثاني. وينتهي الطريقان إلى الموضع نفسه: مهمة تعليق توضيحي في Potato تستطيع تشغيلها وتغييرها ومشاركتها.

ما الذي تقرّره المهارة

potato-skill مهارة وكيل، أي حزمة من التعليمات والسكربتات المساعدة يحمّلها وكيل البرمجة حين يحتاج إليها الطلب. وهي تأتي بـ28 ملف مرجع وتسعة سكربتات مساعدة، وتغطي تصميم الدراسة كما تغطي بناءها:

• ما الذي يُسأل عنه المعلّقون، وعلى أي مقياس
• كم معلّقاً يحتاج كل عنصر
• كيف يُدرَّب المعلّقون ويُفحَص عملهم
• الواجهة التي يراها المعلّقون
• تصدير النتائج بالصيغة التي تحتاجها الخطوة التالية

وبعض تلك القرارات تحسمه بنفسها، وبعضها تعيده إليك. والقاعدة التي تعمل بها أن القرار يُتَّخذ محلياً حين يكون تصحيح الخطأ رخيصاً، ويُعاد إليك حين يكون الخطأ مكلفاً أو غير قابل للرجوع أو ليس من شأن الوكيل. فهي تأخذ مقياساً من 5 نقاط مع تسمية كل نقطة، واختصارات لوحة المفاتيح في أي سؤال بتسعة تصنيفات أو أقل، وترتيباً عشوائياً للعناصر مع random_seed ثابت، وجعل كل الأسئلة مطلوبة. وتسألك عن وحدة التعليق، وعن عدد المعلّقين لكل عنصر حين سيجري الإبلاغ عن الاتفاق، وعن صياغة الموافقة المستنيرة، وعن أي مجموعة تصنيفات بلا خيار "غير واضح".

وتعمل المهمة التي تبنيها على Potato، فتحصل على ما يوفّره Potato أصلاً: تسجيل دخول لكل معلّق، وعدة معلّقين لكل عنصر، وإحصاءات الاتفاق، والتكامل مع Prolific وSONA، والتصدير إلى الصيغ التي تقرؤها الأدوات اللاحقة.

المتطلبات

لا بدّ من تثبيت Potato حيثما ينفّذ الوكيل الأوامر، لأن السكربتات المساعدة للمهارة تستورد سجلّات Potato وتشغّل أمر potato:

pip install potato-annotation

وتحتاج كذلك إلى وكيل برمجة. كُتبت المهارة من أجل Claude Code، وهي تُثبَّت في Codex وCursor أيضاً.

تثبيت المهارة

في Claude Code، ثبّتها من سوق الإضافات:

/plugin marketplace add davidjurgens/potato-skill
/plugin install potato-skill@potato

ولـ Codex وCursor، تثبّتها أداة skills الطرفية في المشروع الذي تعمل فيه:

npx skills add davidjurgens/potato-skill --agent codex cursor

ما الذي يتضمنه التثبيت على Codex أو Cursor

تكتب أداة skills الطرفية المجلد .agents/skills/potato-skill/ وفيه SKILL.md وكل المراجع الـ28 وكل السكربتات التسعة، فيحصل مشروع Codex أو Cursor على المادة نفسها التي يحصل عليها تثبيت Claude Code. وهي تترك AGENTS.md و.cursor/rules دون مساس، وطريقة اكتشاف كل أداة للمهارة في ذلك المجلد شأن تلك الأداة.

ويحمل المستودع كذلك ملف AGENTS.md في جذره، يقرأه Codex وCursor بالاسم دون أي خطوة تثبيت. وذلك الملف ملخص قصير مقابل نحو 79,000 كلمة موزعة على المراجع، وهو يشير إلى ملفات مرجعية وسكربتات لا يضعها على القرص إلا التثبيت الكامل. استخدمه حين تريد أن يمتلك الوكيل حلقة الفحص قبل التسليم والقواعد التي لها أثر فعلي، واستخدم أداة skills الطرفية حين تريد المادة المرجعية التي وراءها.

وصف الدراسة

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

أريد 200 تغريدة مصنّفة حسب المشاعر على مقياس من 5 نقاط، بثلاثة معلّقين لكل تغريدة، مع صفحة موافقة وفحصَي انتباه. ابنِها وشغّلها.

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

الفحوص التي يجريها الوكيل قبل التسليم

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

potato validate config.yaml --strict
potato preview config.yaml --screenshot shot-01.png

يحوّل --strict مفتاحَ ضبط غير معروف من تحذير إلى إخفاق، فيلتقط الخطأ المطبعي الذي كان سيترك ميزة معطّلة في صمت. ويقلع --screenshot بخادم Potato حقيقي ويقوده في Playwright بلا واجهة رسومية، مسجّلاً أخطاء وحدة تحكم المتصفح، واستثناءات الصفحة غير المعالَجة، واستجابات HTTP بقيمة 400 فما فوق. ولا يخرج بالرمز 0 إلا حين تكون القوائم الثلاث كلها فارغة.

وثلاثة من السكربتات المساعدة التسعة تؤتمت ما يمكن قياسه لا ما يُحكم عليه. يقيس check_ui.py التخطيط الحيّ ويبلّغ عن المخططات أو زرّ Next تحت طيّة الشاشة، وعن عناصر الوسائط الفارغة، والاختصارات المكررة. ويبلّغ boot_and_check.py عن كل ميزة مضبوطة لم تحمّل شيئاً. ويمشي walk_task.py في مهمة قيد التشغيل كما يمشي فيها المعلّق ويبلّغ عن الموضع الذي يتوقف عنده.

وقبل أن تدعو أي أحد، افتح المهمة في متصفحك وصنّف بضعة عناصر بنفسك.

المهمة التي تنتجها

مهمة Potato مجلد مشروع يضم ملف ضبط المهمة وبياناتها وتعليماتها. وينطبق عليها كل ما في البدء السريع. تشغّلها بالأمر potato start config.yaml، وتعدّلها يدوياً، وتضيف معلّقين، وتصدّر التصنيفات.

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

التصاميم والتعليقات الموجودة

• تصميم منشور. تستطيع المهارة أن تبدأ من أحد 440 تصميم تعليق توضيحي مأخوذة من أوراق منشورة، بمجموعات تصنيفاتها وصياغة أسئلتها وتعليماتها. تستطيع تصفّحها في المعرض، ويبحث فيها find_design.py عن تصميم قريب مما وصفته.
• تعليقات من أداة أخرى. يقرأ potato import عشرين صيغة، منها Labelbox وCVAT وCOCO، فيستطيع مشروع نصف منجز أن يكمل في Potato.
• دراسة جارية بالفعل. يبلّغ study_status.py عن تقدّم كل معلّق والاتفاق على كل سؤال، وتقول المهارة أي الإصلاحات آمن في منتصف الدراسة وأيها سيفسد البيانات المجموعة أصلاً.

خوادم MCP في Potato

يستطيع الوكيل أن يصل إلى الأجوبة نفسها عبر MCP بدل الصدفة. يعرض potato mcp serve --root . 12 أداة تأليف تقرأ السجلّات نفسها التي تقرأها واجهة سطر الأوامر، ومنها render_task_screenshot التي تعيد الصفحة المصيَّرة صورةً. ويجسر potato mcp connect دراسةً قيد التشغيل ويضيف 12 أداة حيّة تغطي الحالة والتقدّم والمعلّقين والاتفاق والإسناد والتصدير. ويحتاج الجسر إلى كتلة mcp في ملف الضبط تسرد الأدوات المراد عرضها، وإلى رمز من potato mcp issue-token.

الاختبارات مقابل سجلّات Potato

المعرّف الخاطئ المعقول أسوأ من انعدام التوثيق، لأن الوكيل سيستخدمه. ولذلك تُولَّد ثلاثة من المراجع الـ28 من سجلّات Potato نفسها ولا تستطيع أن تنحرف عمّا يفرضه الخادم: أنواع التعليق الـ61 كلها، ولكلٍّ منها مثال معمول مأخوذ من مشروع حقيقي، ومفاتيح الضبط العليا الموثّقة، والمفاتيح الفرعية الموثّقة.

ويغطي التكامل المستمر ملفات المهارة الأساسية، فيتحقق من أن كل نوع تعليق ونوع عرض ومفتاح ضبط ومُعامِل واسم استراتيجية وأمر مذكور فيها موجود في Potato. وتُدمج كل عيّنة YAML في ملف ضبط عامل وتُمرَّر عبر المدقّق الحقيقي في Potato، ويقلع المثال المعمول بخادم حقيقي.

والمادة المرجعية منشورة على davidjurgens.github.io/potato-skill، وتُقرأ دون تثبيت أي شيء. وتوصي Anthropic بمراجعة أي مهارة قبل تثبيتها.

مقارنة الطريقين

يختلف الطريقان فيما تبدأ منه، لا فيما تنتهي إليه:

وتستطيع تبديل الطريق في أي وقت. يستطيع الوكيل تغيير مهمة كتبتها أنت، وتستطيع أنت تحرير مهمة بناها الوكيل.

أسئلة

تتناول الأسئلة أدناه إعداد potato-skill مع وكيل برمجة ومكان العثور على شيفرته المصدرية.

كيف أستخدم Potato مع وكيل برمجة؟

ثبّت Potato وpotato-skill حيثما ينفّذ الوكيل الأوامر، ثم صِف الدراسة للوكيل بلغة عادية. يثبّت pip install potato-annotation برنامج Potato. وفي Claude Code يثبّت المهارةَ الأمرُ /plugin marketplace add davidjurgens/potato-skill متبوعاً بـ/plugin install potato-skill@potato، وفي Codex أو Cursor يتولى ذلك npx skills add davidjurgens/potato-skill --agent codex cursor. أخبر الوكيل بما يحتاج إلى تعليق، ومن سيعلّقه، وفيمَ ستُستخدم التصنيفات. يبني potato-skill المهمة، ويصيّرها للتحقق من أنها تعمل، ويعيد إليك قائمة بالقرارات التي اتخذها نيابة عنك.

أين أجد potato-skill على GitHub؟

يوجد potato-skill على github.com/davidjurgens/potato-skill، وهو منشور تحت رخصة GPL-3.0-or-later. ومادته المرجعية منشورة على davidjurgens.github.io/potato-skill، فتستطيع أن تقرأ ما تقوله المهارة للوكيل قبل أن تثبّتها.

الخطوات التالية

• البدء السريع، لكتابة مهمة يدوياً
• أساسيات الضبط
• إجراء دراسة تعهيد جماعي
• قياس اتفاق المُعلِّقين
• ملفات ضبط يستطيع وكيل البرمجة التحقق منها
• potato-skill على GitHub