feat: add clarifying questions to pptx, pdf, xlsx skills (#110)

* 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 <simongdavies@users.noreply.github.com>

* fix: address PR #110 review feedback — clarify remote asset handling

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 <simongdavies@users.noreply.github.com>

---------

Signed-off-by: Simon Davies <simongdavies@users.noreply.github.com>

Author: simongdavies

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? (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:**
+
+- 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

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? (local file paths or descriptions for placeholders. If remote URLs are needed, also apply `web-research` profile)
+
+**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

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? If a URL, also apply `web-research` profile to enable fetching.
+
+**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