# Questionnaire Reading

> >

- **Type:** Skill
- **Install:** `agentstack add skill-hoanghaoha-survy-agent-skills-questionnaire-reading`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [hoanghaoha](https://agentstack.voostack.com/s/hoanghaoha)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [hoanghaoha](https://github.com/hoanghaoha)
- **Source:** https://github.com/hoanghaoha/survy-agent-skills/tree/main/skills/questionnaire-reading

## Install

```sh
agentstack add skill-hoanghaoha-survy-agent-skills-questionnaire-reading
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Questionnaire Reading Skill

This skill converts a raw questionnaire design document into a structured
`questionnaire-design.md` file. The output becomes the authoritative reference
for survey structure, routing logic, and metadata — enabling an AI agent to
understand the data before writing any survy code.

---

## 1. Input Formats

Accept any of the following:

| Format | How to read |
|--------|-------------|
| `.docx` | Use `python-docx` (`pip install python-docx`) to extract paragraphs and tables |
| `.xlsx` / `.xls` | Use `openpyxl` (`pip install openpyxl`) or `polars.read_excel()` to iterate rows |
| `.pdf` | Use `pdfplumber` (`pip install pdfplumber`) to extract text page by page |
| `.txt` / `.md` | Read directly — plain text, no library needed |

Always inspect the raw content first before deciding on a parsing strategy.
Questionnaire documents vary widely; read several rows/paragraphs to detect
the layout pattern before extracting.

---

## 2. Concepts to Extract

For each question, extract:

| Field | Description |
|-------|-------------|
| **Question ID** | Short code used in data (e.g. `Q1`, `S2`, `D3`). If not present, assign sequentially. |
| **Label / Text** | The full question wording shown to respondents. |
| **Type** | `Single` (one answer), `Multi` (multiple answers), `Open` (free text), `Number`, `Grid`. |
| **Options** | Answer choices with their codes/numbers. Capture exactly as designed. |
| **Logic** | Routing instruction — who sees this question. See Section 3. |
| **Terminate** | Flag if any option ends the interview (`-> Terminate respondent`). |

---

## 3. Logic / Routing Rules

Questionnaire logic is the most important thing to capture accurately.
Common patterns and how to write them in the output:

| Design wording | Output phrasing |
|----------------|-----------------|
| "Ask all" / "All respondents" | `Logic: All respondents` |
| "Ask if Q2 = Yes" / "If Q2 = 1" | `Logic: Ask if Q2 == 1 (Yes)` |
| "Ask if Q3 = 1 or 2" | `Logic: Ask if Q3 == 1 (Cat) OR Q3 == 2 (Dog)` |
| "Skip to Q5 if Q4 = No" | `Logic: Ask if Q4 != 2 (No)` |
| "Ask for all non-terminated" | `Logic: Ask for all respondents (who are not terminated)` |
| "Ask if Q1 is answered" | `Logic: Ask if Q1 is not empty` |
| Grid sub-questions | `Logic: Same as parent grid question` |

When logic is ambiguous, capture the raw wording in a `Note:` line beneath.

---

## 4. Output Format

Always write the output as a `.md` file named `questionnaire-design.md` (or
the name the user specifies). Use this exact structure:

```markdown
# QUESTIONNAIRE DESIGN

---
Question: Q1
Type: Single
Label / Text: Please indicate your gender
Options:
1. Male
2. Female
Logic: All respondents

---
Question: Q2
Type: Single
Label / Text: Do you nurture a pet?
Options:
1. Yes
2. No
Logic: All respondents

---
Question: Q3
Type: Multi
Label / Text: Which type of pet do you nurture?
Options:
1. Cat
2. Dog
3. Other -> Terminate respondent
Logic: Ask if Q2 == 1 (Yes)

---
Question: Q4
Type: Single
Label / Text: Which brand do you choose for pet food?
Options:
1. Brand 1
2. Brand 2
3. Brand 3
Logic: Ask for all respondents (who are not terminated)
```

**Rules for the output:**

- One `---` separator before every question block (including the first).
- `Question:` — use the ID exactly as it appears in the data file (or the questionnaire code).
- `Type:` — one of `Single`, `Multi`, `Open`, `Number`, `Grid`.
- `Label / Text:` — full question wording; do NOT truncate.
- `Options:` — list every answer choice with its numeric code.
  - Append ` -> Terminate respondent` for terminating options.
  - Append ` -> Skip to Q{n}` for options that jump forward.
- `Logic:` — concise routing rule using the patterns in Section 3.
- Add `Note:` only when the original wording is ambiguous or non-standard.
- Omit empty fields (e.g. `Options:` block for Open/Number questions unless codes exist).

---

## 5. Step-by-Step Process

1. **Receive the file path** from the user.
2. **Read the raw content** using the appropriate library (see Section 1).
3. **Identify the layout**: Is it a table? Numbered list? Free-form paragraphs?
4. **Extract each question** in order, filling in every field from Section 2.
5. **Resolve logic**: Map routing instructions to the standard phrasing from Section 3.
6. **Write `questionnaire-design.md`** to the same directory as the input file
   (or to a path the user specifies).
7. **Print a short summary**: total questions found, any questions where logic
   was unclear (flagged with `Note:`).

---

## 6. Parsing Tips by Format

### Word (.docx)
- Questions are usually in tables (one row per question) or numbered paragraphs.
- Use `doc.tables` first; if empty, fall back to `doc.paragraphs`.
- Bold text often marks question IDs or labels.
- Italics or parenthetical text often marks routing instructions.

### Excel (.xlsx)
- Look for a header row containing keywords like "Question", "Code", "Label", "Logic", "Routing".
- Each subsequent row is typically one question or one answer option.
- If rows alternate between question and option levels, detect the pattern by column indentation or a "Type" column value.

### PDF (.pdf)
- Extract text page by page with `pdfplumber`.
- Questionnaires in PDF often use numbering (Q1, Q2, …) as anchors — split on these.
- Tables in PDF may be detected via `page.extract_tables()`.
- Watch for headers/footers repeating on every page — strip them.

### Mixed / Unknown
- If the format is unclear, print the first 20 lines/rows and ask the user to confirm the layout before proceeding.

---

## 7. Example Script

See `scripts/parse_questionnaire.py` for a ready-to-run parser that handles
`.docx`, `.xlsx`, `.pdf`, and `.txt` inputs and writes `questionnaire-design.md`.

---

## 8. Integration with survy

Once `questionnaire-design.md` exists, an AI agent can:

- Read the `Question` IDs and map them to `survey["Q1"]` variable IDs.
- Use `Label / Text` to populate `v.label` via `survey.update(...)`.
- Use `Options` to build correct `value_indices` dicts.
- Use `Logic` to understand which respondents answered each question,
  and apply `survey.filter(...)` correctly in analysis.
- Use `-> Terminate respondent` flags to identify and exclude screened-out rows.

---

## 9. Reference Files

- `scripts/parse_questionnaire.py` — ready-to-run parser for docx/xlsx/pdf/txt
- `assets/sample_questionnaire.docx` — example Word questionnaire design
- `assets/sample_questionnaire_design.md` — expected output for the sample

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [hoanghaoha](https://github.com/hoanghaoha)
- **Source:** [hoanghaoha/survy-agent-skills](https://github.com/hoanghaoha/survy-agent-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-hoanghaoha-survy-agent-skills-questionnaire-reading
- Seller: https://agentstack.voostack.com/s/hoanghaoha
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.