whoqol-toolkit
English · Português · Español
[!WARNING]
Beta. The tool may still contain errors. Check every result before publishing it and
report problems.
A plugin for Claude Code and Antigravity (agy) that scores and analyses WHOQOL
quality-of-life questionnaires for publication. You give it the spreadsheet exported from Google Forms, REDCap,
LimeSurvey, SPSS or Excel; it applies the official WHO scoring rules, checks data quality, estimates reliability and
validity, compares groups and writes APA tables, figures and a draft of the methods and results sections.
All numbers come from a tested, deterministic Python package that the skill runs with uv run. The agent's job is to
ask the right questions, run the scripts and interpret the output; it never computes scores itself.
Supported instruments: WHOQOL-BREF, WHOQOL-OLD, EUROHIS-QOL 8, WHOQOL-HIV-BREF, WHOQOL-SRPB BREF, WHOQOL-SRPB,
WHOQOL-DIS (physical and intellectual disabilities), WHOQOL-100, WHOQOL-HIV and WHOQOL-100 + SRPB. Each one is
scored by the rules of its WHO manual or official syntax; where the sources are silent or disagree, the convention
adopted is documented and stated in the methods draft (instruments.md).
Contents
Overview
| |
|---|
| Hosts | Claude Code (plugin) · Antigravity CLI (plugin) · plain command line |
| Instruments | WHOQOL-BREF, WHOQOL-OLD, EUROHIS-QOL 8, WHOQOL-HIV-BREF, WHOQOL-SRPB BREF, WHOQOL-SRPB, WHOQOL-DIS (PD, ID, Brazilian national items, proxy), WHOQOL-100 (6 domains or the 4 BREF domains), WHOQOL-HIV, WHOQOL-100 + SRPB (details) |
| Input formats | .xlsx, .xls, .ods, .csv, .tsv, .sav |
| Item detection | by number (Q1, 1., item_1, pergunta 1, pregunta 1) or by the question text in Portuguese, English or Spanish; numeric (1–5) or text answers |
| Languages | Portuguese, English and Spanish. The report follows the language of the questionnaire (English for any other); the methods/results draft is always written in all three |
| Language version | detected from answers and headers (pt-BR: Fleck et al., 2000; es-ES: Lucas, 1998; en: WHOQOL Group, 1998) and cited in the methods text |
| Runtime | Python ≥ 3.10, dependencies resolved by uv; runs locally, no external services |
Pipeline
flowchart LR
A["Spreadsheet"] --> B["1 · inspect<br/>item columns, language version,<br/>other variables"]
M["Data dictionary<br/>(optional, pre-filled)"] -.-> C
B --> C["2 · agree on the plan<br/>groups, covariates,<br/>reference values"]
C --> D["3 · analyze<br/>WHO scoring, quality,<br/>psychometrics, statistics"]
D --> E["4 · interpretation<br/>by the agent, in the<br/>user's language"]
D --> F["report.md · tables.docx<br/>results.xlsx · figures<br/>methods_results_pt/en/es.md"]
Analyses
| Area | What is computed |
|---|
| Scoring | WHO rules: Q3, Q4 and Q26 reversed; domain = mean × 4 (4–20) and 0–100; minimum valid items per domain (6/7, 5/6, 2/3, 6/8); questionnaires with fewer than 21 valid items excluded; global facet (Q1–Q2) reported separately |
| Data quality | missingness per item and overall, unrecognised answers, exclusions, duplicates, straight-lining, floor/ceiling effects |
| Scoring sensitivity | where the official sources are silent or disagree, the data are rescored with each documented alternative rule (e.g. the UFRGS syntax) and the change in means and n is reported |
| Reliability | Cronbach's α with Feldt 95% CI, McDonald's ω, mean inter-item r, SEM, MDC95, ½ SD |
| Validity | multitrait scaling (corrected item–domain r), HTMT, confirmatory factor analysis (ML: χ², CFI, TLI, RMSEA with 90% CI, SRMR, AVE, CR) and a ready lavaan script for WLSMV |
| Comparisons | Welch t / Hedges g, Mann-Whitney / rank-biserial r, Welch ANOVA / ω² + Games-Howell, Kruskal-Wallis / ε² + Dunn; Holm correction; automatic choice by Shapiro-Wilk/CLT (reported) |
| Associations | Spearman ρ with 95% CI; multiple linear regression with HC3 errors and VIF |
| Reference values | one-sample comparison against published means (supplied by the user, with source); optional cut-off proportion |
This is the beginning of the README. Read the rest at the original. Read the full README ↗
