From 18f0bf6049b23ab00ed4b89034314e62071a1ce4 Mon Sep 17 00:00:00 2001
From: Eve <eve@ai.cowbay.org>
Date: Thu, 16 Apr 2026 16:48:38 +0800
Subject: [PATCH] skills: explain kal intake fields

---
 skills/kal/SKILL.md | 19 ++++++++++++++++---
 1 file changed, 16 insertions(+), 3 deletions(-)

diff --git a/skills/kal/SKILL.md b/skills/kal/SKILL.md
index 5b42619..33034e0 100644
--- a/skills/kal/SKILL.md
+++ b/skills/kal/SKILL.md
@@ -9,7 +9,7 @@ When this skill triggers, first collect the minimum input needed for a KAL run,
 
 ## Primary behavior
 
-If the user says only `啟動KAL` or gives an incomplete kickoff, use a friendly intake reply: one short lead-in sentence plus the same 4-line template.
+If the user says only `啟動KAL` or gives an incomplete kickoff, use a friendly intake reply: one short lead-in sentence plus the same 4-line template, followed by short field guidance.
 
 Default wording:
 
@@ -19,6 +19,12 @@ topic: ""
 seed: ""
 goal: ""
 scope: ""
+
+說明：
+- topic：你想研究的主題是什麼
+- seed：先給我起始材料，例如網址 / repo / 關鍵字 / 文件
+- goal：你最後想得到什麼，例如摘要 / 比較 / 評估 / 決策建議
+- scope：要納入或排除什麼範圍
 ```
 
 Keep the lead-in short and natural. Do not add analysis yet.
@@ -32,11 +38,13 @@ Keep the lead-in short and natural. Do not add analysis yet.
 
 ## Response rules
 
-- If the user only says `啟動KAL`, return one short friendly lead-in sentence plus the 4-line template.
-- If the user gives some fields but not all, return the same template with known values filled in and missing ones left empty; a short natural lead-in is allowed.
+- If the user only says `啟動KAL`, return one short friendly lead-in sentence plus the 4-line template and short field explanations.
+- If the user gives some fields but not all, return the same template with known values filled in and missing ones left empty; a short natural lead-in is allowed, and keep the short explanations.
 - If the user provides enough information, normalize it into the 4-line template and then proceed with the KAL workflow.
 - Keep the intake step lightweight.
 - Do not add unnecessary analysis before the intake is clear.
+- If the user explicitly asks how to fill the fields, always include the explanation block.
+- If the user explicitly asks for raw copy-paste format only, you may omit the explanation block.
 
 ## Filled-template behavior
 
@@ -86,3 +94,8 @@ seed: "..."
 goal: "..."
 scope: "..."
 ```
+
+- The explanation block belongs below the 4 fields by default.
+- For chat surfaces, short bullets are preferred over tables.
+- Do not turn intake into a long questionnaire.
+- Keep it to one short lead-in, the 4 fields, and brief field hints.