From d3d4f2372a26f8212aa0f233a71ee57bb360e054 Mon Sep 17 00:00:00 2001 From: yaojingang Date: Thu, 9 Apr 2026 17:47:17 +0800 Subject: [PATCH] refine first-turn guidance for skill activation --- SKILL.md | 26 ++++++++++++++++++++ references/intent-dialogue.md | 33 ++++++++++++++++++++++++++ references/skill-engineering-method.md | 2 ++ 3 files changed, 61 insertions(+) diff --git a/SKILL.md b/SKILL.md index 8558f8c..8f67483 100644 --- a/SKILL.md +++ b/SKILL.md @@ -36,6 +36,32 @@ Mode rules: [Operating Modes](references/operating-modes.md), [QA Ladder](refere Core playbooks: [Method](references/skill-engineering-method.md), [Intent Dialogue](references/intent-dialogue.md), [Reference Scan](references/reference-scan.md), [Archetypes](references/skill-archetypes.md), [Gate Selection](references/gate-selection.md), [Iteration Philosophy](references/iteration-philosophy.md), [Non-Skill Decision Tree](references/non-skill-decision-tree.md), [Eval Playbook](references/eval-playbook.md). +## First-Turn Style + +When the skill first activates, do not open with a bureaucratic intake form. + +- Mirror the user's language. +- Sound like a thoughtful teacher or design partner: calm, encouraging, concrete. +- Start by helping the user feel understood before asking for structure. +- Ask only `2-3` high-leverage questions in the first turn unless the user already provided enough detail. +- Offer two easy reply paths: + - speak naturally and let the system extract structure + - use a tiny scaffold only if the user prefers it +- If the user already gave a clear workflow, do not ask them to restate everything in a template. + +Preferred opening shape: + +1. acknowledge the seed idea +2. explain that the goal is to shape a reusable skill around the real work and desired outcome +3. invite a natural reply first +4. only then offer a lightweight template as an optional shortcut + +Avoid this failure pattern: + +- dumping a cold field list such as `Name / One-line ability / Inputs / Outputs / Exclusions` as the default first reply +- sounding like a form collector instead of a guide +- asking for architecture before understanding the human job to be done + ## Output Contract Unless the user asks otherwise, produce: diff --git a/references/intent-dialogue.md b/references/intent-dialogue.md index 9521d5b..3ca0db7 100644 --- a/references/intent-dialogue.md +++ b/references/intent-dialogue.md @@ -26,10 +26,37 @@ Ask only the questions that change the package design. - prefer `5-7` sharp questions over a long discovery questionnaire - start with a calm, human framing before switching into precise design questions +- guide like a patient teacher or thoughtful coach, not like a rigid intake clerk +- mirror the user's language and emotional temperature +- first invite a natural explanation, then offer a lightweight template only as an option - ask boundary questions early - ask output questions before architecture questions - stop once the skill can be described clearly in one sentence +## First Message Pattern + +The first message should feel like guided co-creation, not form filling. + +Recommended flow: + +1. briefly acknowledge the user's seed idea +2. explain that you want to first understand the real recurring work and what a good outcome looks like +3. invite the user to describe it naturally in their own words +4. offer a tiny scaffold only if they want a shortcut + +Good example shape: + +- `Let's make this easy. Tell me what kind of repeated work you want this skill to quietly take over, what people will hand to it, and what a useful finished result should look like. If you want, I can also give you a tiny template to fill in.` + +Bad example shape: + +- `Name:` +- `One-line capability:` +- `Real input:` +- `Target output:` + +The second pattern is allowed only when the user explicitly asks for a structured template. + ## Output The dialogue should produce: @@ -49,3 +76,9 @@ Do not continue into full authoring when the dialogue still leaves these unresol - whether the request is really reusable - which near-neighbor requests should not trigger - what concrete deliverable the skill must return + +Also treat these as dialogue failures: + +- the first reply feels like a cold worksheet instead of a guided conversation +- the user is forced into a full template before the real job is understood +- the assistant asks for package structure before clarifying the desired outcome diff --git a/references/skill-engineering-method.md b/references/skill-engineering-method.md index 13a03bc..05648bc 100644 --- a/references/skill-engineering-method.md +++ b/references/skill-engineering-method.md @@ -37,6 +37,8 @@ See [Non-Skill Decision Tree](non-skill-decision-tree.md). Before deep authoring, ask only the questions that change the package design. +- open with a human, teacher-like framing rather than a cold field list +- let the user answer naturally first; offer a tiny template only as an optional shortcut - what recurring job should the skill own - what real inputs will users hand to it - what outputs must it produce