diff --git a/packages/opencode/test/skill/skill.test.ts b/packages/opencode/test/skill/skill.test.ts
index f558431aa..23a1adfc9 100644
--- a/packages/opencode/test/skill/skill.test.ts
+++ b/packages/opencode/test/skill/skill.test.ts
@@ -499,10 +499,18 @@ test("bundled productivity skills enforce clarify-first workflow and locale guid
expect(content).toContain("## Step 3: Verify")
expect(content).toContain("## Language")
expect(content).toContain('Reply in the user\'s locale (shown in system environment as "User locale").')
- // Skills must NOT hardcode tool names or JSON schemas — models pick the
- // right tool from the tool list at runtime
+ // Skills should name the question tool behavior without embedding raw schemas.
expect(content).not.toContain("```json")
- expect(content).not.toContain("`question` tool")
+ expect(content).toContain("`question` tool")
+ expect(content).toContain("typically 2-4")
+ expect(content).toContain("ask fewer when only one material gap is missing")
+ expect(content).toContain("recommended answer")
+ expect(content).toContain("Do not ask obvious questions")
+ expect(content).toContain("Stop asking")
+ expect(content).toContain("Before asking, use this decision rule")
+ expect(content).toContain("**Must ask**")
+ expect(content).toContain("**Use a recommended default and continue**")
+ expect(content).toContain("**Ask one multiple-choice question**")
}
const documentProcessing = getContent("document-processing")
@@ -510,18 +518,21 @@ test("bundled productivity skills enforce clarify-first workflow and locale guid
expect(documentProcessing).toContain("**Task type**")
expect(documentProcessing).toContain("**Source**")
expect(documentProcessing).toContain("**Constraints**")
+ expect(documentProcessing).toContain("**Success check**")
const dataAnalysis = getContent("data-analysis")
assertSharedStructure(dataAnalysis)
expect(dataAnalysis).toContain("**Data source**")
expect(dataAnalysis).toContain("**Output**")
expect(dataAnalysis).toContain("**Business question**")
+ expect(dataAnalysis).toContain("**Decision use**")
const writingAssistant = getContent("writing-assistant")
assertSharedStructure(writingAssistant)
expect(writingAssistant).toContain("**Content type**")
expect(writingAssistant).toContain("**Tone**")
expect(writingAssistant).toContain("**Key points**")
+ expect(writingAssistant).toContain("**Success check**")
expect(writingAssistant).toContain("wait for their next message")
},
})
diff --git a/skills/data-analysis/SKILL.md b/skills/data-analysis/SKILL.md
index e74512ff6..6d628ca6e 100644
--- a/skills/data-analysis/SKILL.md
+++ b/skills/data-analysis/SKILL.md
@@ -8,22 +8,32 @@ description: Use when user wants analysis, charts, summaries, or reports from sp
Analyze structured local data and return conclusions, charts, or updated files.
-Do NOT start analyzing until you understand the data and the question. Ask clarifying questions first, then act.
+Do NOT start analyzing until you understand the data and the decision the analysis should support.
+
+When important context is missing, use the `question` tool instead of asking only in plain text. Ask a focused round of questions, typically 2-4, and ask fewer when only one material gap is missing. Ask deeper, non-obvious questions that uncover the user's goal, metrics, constraints, and tradeoffs. Provide your recommended answer as the first option when useful. Use multiple selection when several outputs or dimensions may be needed.
+
+Do not ask obvious questions whose answers are already in the user's message. Stop asking once you can produce a useful first analysis. Ask another focused round only if the user's answer reveals a material gap.
+
+Before asking, use this decision rule:
+- **Must ask** when the missing answer changes the metric, time range, grouping, output format, or decision the analysis supports.
+- **Use a recommended default and continue** when the missing answer is only a preference, such as chart style, wording length, or whether to include extra detail.
+- **Ask one multiple-choice question** when several safe defaults are possible. Put the recommended default first and explain why it is recommended.
## Workflow
-1. **Clarify** - Ask the user what they need before touching any data.
+1. **Clarify** - Use focused questions to understand what result would be useful before touching any data.
2. **Execute** - Inspect the data, run the analysis, and produce the requested outputs.
3. **Verify** - Check that the findings and deliverables match the user's request.
## Step 1: Clarify
-Ask the user the following before acting:
+Use the question tool to ask what matters before acting:
-- **Data source** — Is it a spreadsheet (xlsx/csv), a database export, or will they describe the data in chat?
-- **Output** — Do they want a summary report, a chart or visualization, an updated spreadsheet, or some combination?
-- **Business question** — What question should the analysis answer? Confirm key metrics, dimensions, and date ranges when they matter.
+- **Data source**: Is it a spreadsheet (xlsx/csv), a database export, or will they describe the data in chat?
+- **Output**: Do they want a summary report, a chart or visualization, an updated spreadsheet, or some combination?
+- **Business question**: What question should the analysis answer? Confirm key metrics, dimensions, and date ranges when they matter.
+- **Decision use**: What will the user do with the answer? This determines how much precision, explanation, and caution the analysis needs.
## Step 2: Execute
diff --git a/skills/document-processing/SKILL.md b/skills/document-processing/SKILL.md
index 474915ef1..33a7b86c3 100644
--- a/skills/document-processing/SKILL.md
+++ b/skills/document-processing/SKILL.md
@@ -8,22 +8,32 @@ description: Use when user wants to create, edit, convert, or extract from Word,
Handle document creation, editing, conversion, and extraction for local office files.
-Do NOT start working on files until you understand what the user needs. Ask clarifying questions first, then act.
+Do NOT start working on files until you understand what the user needs and what must be preserved.
+
+When important context is missing, use the `question` tool instead of asking only in plain text. Ask a focused round of questions, typically 2-4, and ask fewer when only one material gap is missing. Ask deeper, non-obvious questions that uncover the user's goal, source material, constraints, and tradeoffs. Provide your recommended answer as the first option when useful. Use multiple selection when several operations or output formats may be needed.
+
+Do not ask obvious questions whose answers are already in the user's message. Stop asking once you can produce a useful first output safely. Ask another focused round only if the user's answer reveals a material gap.
+
+Before asking, use this decision rule:
+- **Must ask** when the missing answer changes the source file, target format, editing scope, layout fidelity, formulas, comments, permissions, or overwrite risk.
+- **Use a recommended default and continue** when the missing answer is only a preference, such as file name, minor formatting, or whether to include a short note with the output.
+- **Ask one multiple-choice question** when several safe paths are possible. Put the recommended default first and explain why it is recommended.
## Workflow
-1. **Clarify** - Ask the user what they need before touching any files.
+1. **Clarify** - Use focused questions to understand the task and constraints before touching any files.
2. **Execute** - Choose the least-destructive toolchain, then perform the task.
3. **Verify** - Check the output against the user's constraints and report the result.
## Step 1: Clarify
-Ask the user the following before acting:
+Use the question tool to ask what matters before acting:
-- **Task type** — Are they creating a new document, editing an existing one, converting between formats, or extracting content?
-- **Source** — Will they upload or specify files, or should you reuse files from a previous step?
-- **Constraints** — Anything that must stay unchanged: layout, formulas, comments, branding, slide order.
+- **Task type**: Are they creating a new document, editing an existing one, converting between formats, or extracting content?
+- **Source**: Will they upload or specify files, or should you reuse files from a previous step?
+- **Constraints**: Anything that must stay unchanged: layout, formulas, comments, branding, slide order.
+- **Success check**: What should the finished file let the user do: send it, review it, import it, print it, or keep editing it?
## Step 2: Execute
diff --git a/skills/writing-assistant/SKILL.md b/skills/writing-assistant/SKILL.md
index a907b622a..407b1c302 100644
--- a/skills/writing-assistant/SKILL.md
+++ b/skills/writing-assistant/SKILL.md
@@ -8,23 +8,33 @@ description: Use when user wants to draft or revise work writing like emails, re
Draft or revise business writing without inventing facts, commitments, or details.
-Do NOT start drafting until you understand what the user needs. Ask clarifying questions first, then write.
+Do NOT start drafting until you understand the user's goal, audience, and source material well enough to avoid inventing facts.
+
+When important context is missing, use the `question` tool instead of asking only in plain text. Ask a focused round of questions, typically 2-4, and ask fewer when only one material gap is missing. Ask deeper, non-obvious questions that uncover the user's goal, audience, tone, constraints, and tradeoffs. Provide your recommended answer as the first option when useful. Use multiple selection when several tones, channels, or output formats may be acceptable.
+
+Do not ask obvious questions whose answers are already in the user's message. Stop asking once you can produce a useful first draft. Ask another focused round only if the user's answer reveals a material gap.
+
+Before asking, use this decision rule:
+- **Must ask** when the missing answer changes the audience, purpose, factual claims, commitments, deadline, channel, or reader action.
+- **Use a recommended default and continue** when the missing answer is only a preference, such as exact length, minor tone choice, or whether to include a subject line.
+- **Ask one multiple-choice question** when several safe drafts are possible. Put the recommended default first and explain why it is recommended.
## Workflow
-1. **Clarify** - Ask the user what they need before writing anything.
+1. **Clarify** - Use focused questions to understand what the writing needs to achieve before writing anything.
2. **Execute** - Extract the facts, choose the right structure, and draft in the requested tone.
3. **Verify** - Check the draft for factual fidelity, tone, and usability.
## Step 1: Clarify
-Ask the user the following before acting:
+Use the question tool to ask what matters before acting:
-- **Content type** — Email, report or memo, announcement, or plan/proposal?
-- **Tone** — Formal, conversational, concise and direct, or persuasive?
-- **Key points** — Will they provide details now, should you draft from what they already said, or should you ask more questions first? Always ask this, even when input seems sufficient.
-- **Constraints** — Any length, audience, structure, or deadline requirements.
+- **Content type**: Email, report or memo, announcement, or plan/proposal?
+- **Tone**: Formal, conversational, concise and direct, or persuasive?
+- **Key points**: Will they provide details now, should you draft from what they already said, or should you ask more questions first? Ask only when the answer would materially change the draft.
+- **Constraints**: Any length, audience, structure, or deadline requirements.
+- **Success check**: What should the reader think, decide, or do after reading?
If the user chooses to provide details later, wait for their next message before proceeding to draft.