An Agent Skill for Codex, Claude Code, WorkBuddy, OpenCode, and other instruction-aware agents. It helps organizational behavior, management, marketing, psychology, and social science researchers review translated scales, adapted Chinese questionnaires, paired surveys, and pre-launch survey quality.
中文说明 | Template files | Prompt cookbook | Install and update | WorkBuddy setup | Claude Code guide | Other agents | Sample output
Survey Scale Review helps researchers catch the problems that often appear between "we selected the scales" and "the questionnaire is ready to launch":
- English source scale items translated into Chinese
- Mature scales adapted to AI, leadership, team, or work-task contexts
- Reverse-coded source items rewritten into positive wording
- Self-developed or highly adapted items with psychometric wording problems
- Leader-employee paired questionnaires and multi-wave survey designs
- Pre-launch issues such as placeholders, respondent mismatch, vague referents, and unclear time windows
It is designed for researchers in organizational behavior, management, marketing, HRM, psychology, management psychology, AI at work, leadership, and survey-based social science research.
Many survey problems are not obvious until data collection is already underway:
- A research assistant translated a scale item fluently, but the adapted wording no longer measures the same construct.
- A reverse-coded source item was rewritten positively, but the scoring note still says reverse-code it.
- "My team" means coworkers to one respondent and subordinates to another.
- A leader-rated performance scale is listed as an employee self-report variable.
- A questionnaire still contains
XX,x月x日, or internal notes. - A reviewer may later ask whether an "adapted" scale is actually a newly developed scale.
This skill gives AI agents a domain-specific review workflow for these issues. It is especially optimized for Chinese-language research workflows: Excel/Word scale files, Chinese survey-platform drafts, paired leader-subordinate surveys, Chinese wording ambiguity, and RA-researcher revision handoffs.
Open the agent you use, such as Codex, Claude Code, WorkBuddy, OpenCode, Cursor, Windsurf, Trae, Qoder, Gemini CLI, GitHub Copilot CLI, Tongyi Lingma, Doubao MarsCode, or Tencent Cloud CodeBuddy, and paste:
Please install this Agent Skill from https://github.com/gtskevin/survey-scale-review into my local skills folder.
If I am using Codex, install it under ~/.codex/skills/survey-scale-review.
If I am using Claude Code, install it under ~/.claude/skills/survey-scale-review.
If I am using WorkBuddy, prefer the Claude Code skill path: ~/.claude/skills/survey-scale-review.
If my tool does not support skills, connect this repository as a project instruction or custom command and tell me what to type afterward.
Then start a new session and ask:
Use $survey-scale-review to review my questionnaire Excel file.
If you installed this skill earlier, update it regularly. If you do not use the command line, paste this into Codex, Claude Code, or WorkBuddy:
Please update the Agent Skill at https://github.com/gtskevin/survey-scale-review.
Check whether ~/.codex/skills/survey-scale-review and ~/.claude/skills/survey-scale-review exist.
If the directory is a git clone, run git pull --ff-only.
If it is not a git repository, back up the old directory and reinstall the latest version from GitHub.
When done, tell me the local commit and commit date.
Command-line users can run:
git -C ~/.codex/skills/survey-scale-review pull --ff-only
git -C ~/.claude/skills/survey-scale-review pull --ff-onlyRun only the command for the directory you actually use. See the install and update guide for details.
mkdir -p ~/.codex/skills
git clone https://github.com/gtskevin/survey-scale-review.git ~/.codex/skills/survey-scale-reviewStart a new Codex session and ask:
Use $survey-scale-review to review my questionnaire Excel file.
Claude Code supports SKILL.md-based Agent Skills. Install the same repository into Claude's personal skills folder:
mkdir -p ~/.claude/skills
git clone https://github.com/gtskevin/survey-scale-review.git ~/.claude/skills/survey-scale-reviewStart Claude Code and invoke:
/survey-scale-review review my questionnaire Excel file.
See Claude Code setup for details.
WorkBuddy's documentation describes it as built on Claude Code and MCP, so the simplest setup is to install Survey Scale Review through the Claude Code skill path:
mkdir -p ~/.claude/skills
git clone https://github.com/gtskevin/survey-scale-review.git ~/.claude/skills/survey-scale-reviewThen use it in a WorkBuddy/Claude Code session:
/survey-scale-review review my questionnaire Excel file.
If you do not use the command line, paste the non-command-line install request above into WorkBuddy. See WorkBuddy setup for details.
This repository is not limited to Codex or Claude Code. Different agents can reuse it through three patterns:
-
Native skill path: Codex, Claude Code, WorkBuddy.
-
Custom command path: OpenCode and agents that support command/prompt files.
-
Project instruction path: Cursor, Windsurf, Trae, Qoder, Gemini CLI, GitHub Copilot CLI, Tongyi Lingma, Doubao MarsCode, Tencent Cloud CodeBuddy, and similar tools through
AGENTS.md, project rules, knowledge files, or reusable prompts.
If your questionnaire is not organized in a standard format, you can still ask:
Use $survey-scale-review to review this questionnaire draft.
It is not in your template format, so first infer the structure and tell me what is missing.
You do not have to use the template, but it makes the review cleaner.
| Option | Best for | What to provide |
|---|---|---|
| Existing file | You already have an RA-prepared Excel/Word/questionnaire draft | Upload the file and ask for review |
| Recommended Excel template | You are preparing a new study or want structured review output | Use templates/survey_scale_review_template.xlsx |
| CSV templates | You prefer plain tables or Google Sheets | Use variables_template.csv and questionnaire_template.csv |
| Plain text | You only have copied scale items | Paste variable names, source items, translated/adapted items, and sources |
The template separates two things:
- Variable list: construct names, respondent, wave, item count, and scale type.
- Questionnaire items: source item, current translated/adapted item, source reference, and notes.
This mirrors how many OB and management researchers actually review questionnaires: first checking the research design structure, then checking the item-level wording.
| Question | Short answer |
|---|---|
| My questionnaire is not in the template format. | Yes. Ask the skill to infer the structure first and list missing information. |
| I only have a Word document or survey-platform draft. | Yes. The review will focus on structure, instructions, respondent experience, and launch readiness. |
| I do not have the English source items. | Yes, but translation/adaptation equivalence cannot be fully reviewed. |
| I use mature Chinese scales. | Yes. The review can focus on respondent clarity, pairing, time windows, response options, and launch blockers. |
| I am not an OB researcher. | Possibly. The standards are optimized for OB, management, psychology, HRM, and survey-based social science research. |
- Does the Chinese wording preserve the source item's subject, referent, behavior, intensity, and time frame?
- If the item is adapted, can the adaptation be explained to future reviewers?
- Did the item shift from behavior to attitude, from perception to fact, or from one level of analysis to another?
- Are new or heavily rewritten items clearly marked?
The skill assumes many researchers prefer to rewrite reverse-coded source items into positive Chinese wording to reduce respondent confusion.
It checks:
- Whether the positive wording accurately reflects the intended direction
- Whether scoring notes have been updated
- Whether all items in the scale point in the same conceptual direction
It checks common scale-writing problems, including:
- Double-barreled items
- Leading wording
- Loaded or moralized wording
- Vague referents
- Vague time frames
- Frequency-agreement response mismatch
- Double negatives
- Unsupported assumptions
- Construct contamination
- Causal wording inside measurement items
- Overly academic language
- Are employee-rated and leader-rated variables correctly separated?
- Are T1/T2/T3 variables consistent between the variable list and questionnaire body?
- Is the target person clear in leader-rated items?
- Are pairing IDs, respondent instructions, and time windows clear?
The skill reviews the questionnaire from the perspective of employees and managers who may be busy, cautious, or unfamiliar with academic constructs.
It flags ambiguous expressions such as:
- "my team"
- "leader"
- "recently"
- "AI tools"
- "others"
- "work performance"
The skill defaults to Chinese review outputs:
- One concise HTML review page with a 10-minute decision dashboard, P0/P1 action list, researcher-decision list, key suggested revisions, and compact scale-level diagnosis
- A short chat summary plus the HTML file link, instead of a long Markdown report in the chat
- A prominent disclaimer at both the beginning and end: AI assists review but does not replace expert human review, back-translation, pretesting, or validity evidence
- A built-in
Check for updateslink and copyable update prompt so non-technical users can ask their agent to update the skill - Beginner-friendly instant hover explanations for terms such as
implicit adaptation,referent,level of analysis, andback-translation - HTML tables with Chinese headers, P0-P3 colors or badges, a
变量/量表column,为什么重要, and谁来处理 - Markdown, Excel, or a separate optimized questionnaire comparison file only when the user explicitly asks for them
Priority levels:
| Priority | Meaning |
|---|---|
| P0 | Launch blocker: must fix before distribution |
| P1 | High risk: likely affects data quality, scoring, pairing, or reviewer defensibility |
| P2 | Medium risk: affects clarity, wording, or respondent experience |
| P3 | Low risk or reminder: useful for polishing or documentation |
See an anonymized example: sample HTML issue table.
Full review:
Use $survey-scale-review to review this Excel questionnaire.
Focus on translation quality, adapted scale defensibility, reverse-coded item handling,
leader-employee pairing, respondent ambiguity, and launch-blocking problems.
Pre-launch check:
Use $survey-scale-review for a pre-launch check.
Do not rewrite every item; focus on placeholders, confusing instructions,
respondent mismatch, time windows, response options, and pairing risks.
Template-first workflow:
Use $survey-scale-review. I want to prepare a scale review file from scratch.
Show me what to put into the template before reviewing it.
Non-template workflow:
Use $survey-scale-review to inspect this questionnaire draft.
It may not follow your template. First infer the variables, respondents, waves,
source items, translated items, and missing information.
More examples: Prompt cookbook.
- RA prepares the questionnaire or fills the template.
- Ask the skill to run a quick structure check.
- RA handles issues marked "RA can handle" first: placeholders, missing sources, item counts, formatting.
- The researcher handles issues marked "researcher must confirm": adapted-scale logic, construct meaning, reverse-coded scoring, self-developed items.
- Run a pre-launch check after revisions.
- Launch the questionnaire only after P0 issues are cleared and P1 issues are either fixed or consciously accepted.
The generated HTML issue table is designed for non-technical review:
- Start with the 10-minute decision dashboard.
- Fix P0 issues first.
- Then review P1 issues.
- Confirm construct and level-of-analysis decisions before asking an RA to batch-replace item wording.
- Use the
变量/量表column to locate the affected construct. - Use the
谁来处理column to decide whether RA can handle it or the researcher/expert must confirm. - Do not blindly accept item-rewriting suggestions when they affect construct meaning.
- It does not replace researcher judgment about construct definition or theory.
- It does not automatically verify original journal scale wording unless source documents are provided.
- It does not guarantee measurement validity.
- It does not silently overwrite your questionnaire.
- It does not assume every adapted item is valid just because it is fluent.
survey-scale-review/
├── SKILL.md
├── README.md
├── README.zh-CN.md
├── agents/
│ └── openai.yaml
├── docs/
│ ├── claude-code.md
│ ├── claude-code.zh-CN.md
│ ├── developer-advanced.md
│ ├── developer-advanced.zh-CN.md
│ ├── opencode.md
│ ├── opencode.zh-CN.md
│ ├── other-agents.md
│ ├── other-agents.zh-CN.md
│ ├── prompt-cookbook.md
│ ├── prompt-cookbook.zh-CN.md
│ ├── update.md
│ ├── update.zh-CN.md
│ ├── workbuddy.md
│ └── workbuddy.zh-CN.md
├── examples/
│ ├── sample_issues.html
│ └── sample_questionnaire_with_issues.xlsx
├── references/
│ ├── adaptation-review.md
│ ├── evaluation-rubric.md
│ ├── output-formats.md
│ ├── report-template.md
│ └── respondent-experience.md
├── scripts/
│ └── inspect_workbook.py
└── templates/
├── README.md
├── README.zh-CN.md
├── survey_scale_review_template.xlsx
├── variables_template.csv
└── questionnaire_template.csv
organizational behavior, OB research, marketing research, management psychology, survey scale review, questionnaire review, scale adaptation, adapted scales, Chinese translation, Chinese researchers, management research, HRM research, psychology scales, reverse-coded items, leader-employee paired survey, supervisor-subordinate survey, multi-wave survey, AI at work, psychometrics, measurement validity, construct validity, item wording, Codex skill, Claude Code skill, WorkBuddy, OpenCode, Cursor, Windsurf, Trae, Qoder
MIT