From b186bd15d0c13ef67a87d8305565b6dd784a503a Mon Sep 17 00:00:00 2001 From: Simon Davies Date: Thu, 7 May 2026 09:32:43 +0100 Subject: [PATCH 1/2] feat: add clarifying questions to pptx, pdf, xlsx skills Each skill now has a structured 'Clarifying Questions' section that tells the LLM exactly what to ask when details are missing: - pptx-expert: topic, audience, slide count, purpose, theme, charts - pdf-expert: document type, topic, audience, sections, page format - xlsx-expert: purpose, data structure, data source, charts, formulas Questions are grouped into three tiers: 1. Always needed (ask if missing) 2. Ask if relevant to the request 3. Never ask (use sensible defaults) The LLM is instructed to group questions into ONE ask_user call, skip anything already specified, and offer defaults the user can accept with 'yes'. Signed-off-by: Simon Davies --- skills/pdf-expert/SKILL.md | 32 ++++++++++++++++++++++++++++- skills/pptx-expert/SKILL.md | 29 ++++++++++++++++++++++++++- skills/xlsx-expert/SKILL.md | 40 ++++++++++++++++++++++++++++++++----- 3 files changed, 94 insertions(+), 7 deletions(-) diff --git a/skills/pdf-expert/SKILL.md b/skills/pdf-expert/SKILL.md index ebaa8b0..dab6ca8 100644 --- a/skills/pdf-expert/SKILL.md +++ b/skills/pdf-expert/SKILL.md @@ -144,12 +144,42 @@ Use `estimateHeight(elements)` to predict total height BEFORE rendering. ## Setup Sequence -1. `ask_user` — clarify requirements (topic, audience, data sources) +1. **Clarify requirements** — use `ask_user` (see Clarifying Questions below) 2. `apply_profile({ profiles: 'file-builder' })` — for fs-write plugin 3. `module_info('pdf')` → read typeDefinitions for ALL parameters 4. `module_info('pdf-charts')` → if charts needed 5. Register handler and execute +## Clarifying Questions + +Before building, check the user's request for these details. Ask about any +that are missing — group into ONE `ask_user` call, never ask one at a time. +Skip anything the user already specified. Offer sensible defaults they can +accept with "yes" or "looks good". + +**Always needed (ask if missing):** + +- **Document type** — Report, letter, invoice, resume, brochure, manual, whitepaper? +- **Topic/Subject** — What is the document about? +- **Audience** — Who will read it? (management, clients, public, academic) +- **Key sections** — What main sections or topics should it cover? + +**Ask if relevant to the request:** + +- **Page format** — Letter or A4? Portrait or landscape? (default: Letter, portrait) +- **Length** — Approximate page count, or let content determine naturally? +- **Style/Tone** — Formal/professional, casual, academic, technical? +- **Data/Charts** — Any data to visualise? What chart types? +- **Branding** — Company colours, logo image URL? +- **Table of contents** — Include a TOC? (suggest yes for 5+ pages) + +**Never ask — use sensible defaults:** + +- Theme → `light-clean` for content, dark only for title pages +- Font → use standard PDF fonts +- Headers/footers/page numbers → always include for multi-page docs +- Margins → use standard 1" margins + ## Common Mistakes to Avoid - Forgetting `addPage()` before low-level drawing → ERROR diff --git a/skills/pptx-expert/SKILL.md b/skills/pptx-expert/SKILL.md index 464d30d..8dc7069 100644 --- a/skills/pptx-expert/SKILL.md +++ b/skills/pptx-expert/SKILL.md @@ -119,11 +119,38 @@ Call `module_info('ooxml-core')` to see available themes. ## Setup Sequence -1. `ask_user` — clarify topic, audience, slide count +1. **Clarify requirements** — use `ask_user` (see Clarifying Questions below) 2. `apply_profile({ profiles: 'file-builder' })` — for fs-write 3. `module_info('pptx')` → read typeDefinitions 4. Register handler(s) and execute +## Clarifying Questions + +Before building, check the user's request for these details. Ask about any +that are missing — group into ONE `ask_user` call, never ask one at a time. +Skip anything the user already specified. Offer sensible defaults they can +accept with "yes" or "looks good". + +**Always needed (ask if missing):** + +- **Topic/Title** — What is the presentation about? +- **Audience** — Who will view it? (executives, team, customers, students, general) +- **Slide count** — How many slides? Suggest 8–12 if unspecified. +- **Purpose** — Inform, persuade, train, report? + +**Ask if relevant to the request:** + +- **Theme/Style** — Professional/corporate, creative, minimal, dark? Any brand colours? +- **Content structure** — Do you have an outline, or should I create one? +- **Data/Charts** — Any data to visualise? What chart types? (bar, pie, line, etc.) +- **Images** — Any images to include? (URLs or descriptions for placeholders) + +**Never ask — use sensible defaults:** + +- Speaker notes style → always include professional speaker notes +- Font choices → use theme defaults +- Slide dimensions → always 16:9 + ## Common Mistakes - Concatenating ShapeFragments with `+` → use arrays diff --git a/skills/xlsx-expert/SKILL.md b/skills/xlsx-expert/SKILL.md index 74a0ecf..ab60ba8 100644 --- a/skills/xlsx-expert/SKILL.md +++ b/skills/xlsx-expert/SKILL.md @@ -60,11 +60,41 @@ You are an expert at building professional Excel `.xlsx` workbooks inside the Hy ## Setup Sequence -1. `apply_profile({ profiles: 'file-builder' })` for binary output and larger buffers. -2. `manage_plugin('fs-write', 'enable')` if the workbook needs to be written to disk. -3. `module_info('xlsx')` and read the type definitions. -4. Register a handler that imports from `ha:xlsx`. -5. Build the workbook, then write the returned `Uint8Array` with the fs-write binary API. +1. **Clarify requirements** — use `ask_user` (see Clarifying Questions below) +2. `apply_profile({ profiles: 'file-builder' })` for binary output and larger buffers. +3. `manage_plugin('fs-write', 'enable')` if the workbook needs to be written to disk. +4. `module_info('xlsx')` and read the type definitions. +5. Register a handler that imports from `ha:xlsx`. +6. Build the workbook, then write the returned `Uint8Array` with the fs-write binary API. + +## Clarifying Questions + +Before building, check the user's request for these details. Ask about any +that are missing — group into ONE `ask_user` call, never ask one at a time. +Skip anything the user already specified. Offer sensible defaults they can +accept with "yes" or "looks good". + +**Always needed (ask if missing):** + +- **Purpose** — What will this workbook be used for? (tracking, analysis, reporting) +- **Data structure** — What columns/fields are needed? How many rows approximately? +- **Data source** — Will data come from a file, URL, or should I generate sample data? + +**Ask if relevant to the request:** + +- **Multiple sheets** — One sheet or multiple? (e.g. summary + detail, by category) +- **Charts** — Any visualisations needed? What types? (column, bar, line, pie) +- **Formulas** — Any calculations? (totals, averages, percentages, lookups) +- **Formatting** — Conditional formatting, data bars, colour coding for thresholds? +- **Pivot tables** — Any pivot analysis needed? Which fields to group by? +- **Filters/Sorting** — Auto-filter, frozen header rows? + +**Never ask — use sensible defaults:** + +- Column widths → auto-size based on content +- Header styling → bold, coloured background, border +- Number formats → auto-detect from data types +- Sheet protection → don't apply unless explicitly requested ## Common Patterns From 798519584616090e2081da42bc8a2bafbc5ae520 Mon Sep 17 00:00:00 2001 From: Simon Davies Date: Thu, 7 May 2026 10:12:39 +0100 Subject: [PATCH 2/2] =?UTF-8?q?fix:=20address=20PR=20#110=20review=20feedb?= =?UTF-8?q?ack=20=E2=80=94=20clarify=20remote=20asset=20handling?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit All 3 skills mentioned URLs/images in clarifying questions but the setup sequence only applies file-builder (fs-write), leaving the LLM unable to actually fetch remote content. - xlsx: data source URL now notes to apply web-research profile - pptx: images changed from URLs to local paths, with web-research guidance if remote URLs are needed - pdf: branding logo changed from URL to local path/bytes, with web-research guidance if remote URLs are needed Signed-off-by: Simon Davies --- skills/pdf-expert/SKILL.md | 2 +- skills/pptx-expert/SKILL.md | 2 +- skills/xlsx-expert/SKILL.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/skills/pdf-expert/SKILL.md b/skills/pdf-expert/SKILL.md index dab6ca8..19e6fd6 100644 --- a/skills/pdf-expert/SKILL.md +++ b/skills/pdf-expert/SKILL.md @@ -170,7 +170,7 @@ accept with "yes" or "looks good". - **Length** — Approximate page count, or let content determine naturally? - **Style/Tone** — Formal/professional, casual, academic, technical? - **Data/Charts** — Any data to visualise? What chart types? -- **Branding** — Company colours, logo image URL? +- **Branding** — Company colours, logo image? (local path or provided bytes. If remote URLs are needed, also apply `web-research` profile) - **Table of contents** — Include a TOC? (suggest yes for 5+ pages) **Never ask — use sensible defaults:** diff --git a/skills/pptx-expert/SKILL.md b/skills/pptx-expert/SKILL.md index 8dc7069..75d9dc1 100644 --- a/skills/pptx-expert/SKILL.md +++ b/skills/pptx-expert/SKILL.md @@ -143,7 +143,7 @@ accept with "yes" or "looks good". - **Theme/Style** — Professional/corporate, creative, minimal, dark? Any brand colours? - **Content structure** — Do you have an outline, or should I create one? - **Data/Charts** — Any data to visualise? What chart types? (bar, pie, line, etc.) -- **Images** — Any images to include? (URLs or descriptions for placeholders) +- **Images** — Any images to include? (local file paths or descriptions for placeholders. If remote URLs are needed, also apply `web-research` profile) **Never ask — use sensible defaults:** diff --git a/skills/xlsx-expert/SKILL.md b/skills/xlsx-expert/SKILL.md index ab60ba8..7509b53 100644 --- a/skills/xlsx-expert/SKILL.md +++ b/skills/xlsx-expert/SKILL.md @@ -78,7 +78,7 @@ accept with "yes" or "looks good". - **Purpose** — What will this workbook be used for? (tracking, analysis, reporting) - **Data structure** — What columns/fields are needed? How many rows approximately? -- **Data source** — Will data come from a file, URL, or should I generate sample data? +- **Data source** — Will data come from a file, URL, or should I generate sample data? If a URL, also apply `web-research` profile to enable fetching. **Ask if relevant to the request:**