Interactive Project Questionnaire

Portable Agent Skill for local project questionnaires.
Agent Skill для локальных анкет по проекту.

English · Русский

---

English

Long requirement interviews are awkward in chat. This Agent Skills package turns unresolved project decisions into one validated clickable questionnaire running on the user's machine.

The questionnaire server binds only to 127.0.0.1. It does not use Codex Sites, Claude Artifacts, tunnels, remote databases, public links, or external hosting. Submitted answers are validated and written directly to the project as answers.json and answers.md.

The installer includes paths for OpenCode, Claude Code, Gemini CLI, Qwen Code, Kimi Code CLI, Cursor, Codex, and Hermes Agent. It can also install to ~/.agents/skills/ or any directory passed with --target.

How it works

1. The agent turns unresolved project decisions into one validated questionnaire definition.
2. It starts the bundled server on 127.0.0.1 and gives the user the local URL.
3. The user selects options, adds custom answers or comments, and saves the form.
4. The runtime writes answers.json and answers.md; the agent reads both and continues the original task.

If the browser and agent do not share the same loopback namespace, the agent asks a compact set of questions in chat. It never publishes a remote replacement.

Quick start

Send the repository URL to your coding agent:

Install this skill for yourself and verify that it works:
https://github.com/sergeylopukhov/interactive-project-questionnaire

Tip

Agent instructions: clone the repository to a temporary directory and inspect SKILL.md. Run python3 scripts/install_skill.py --agent auto. The command copies the package and runs the smoke test from the installed location. If detection fails, find the client's global Agent Skills directory and pass it with --target.

Manual installation and agent presets

git clone --depth 1 https://github.com/sergeylopukhov/interactive-project-questionnaire.git
cd interactive-project-questionnaire
python3 scripts/install_skill.py --agent auto

Choose another agent or install for several:

python3 scripts/install_skill.py --agent claude
python3 scripts/install_skill.py --agent opencode
python3 scripts/install_skill.py --agent gemini
python3 scripts/install_skill.py --agent qwen
python3 scripts/install_skill.py --agent kimi
python3 scripts/install_skill.py --agent cursor
python3 scripts/install_skill.py --agent all

For any other Agent Skills client, pass its global skills directory:

python3 scripts/install_skill.py --target /path/to/agent/skills

Presets install to:

Preset	Global directory
codex	${CODEX_HOME:-~/.codex}/skills/
claude	~/.claude/skills/
opencode	${XDG_CONFIG_HOME:-~/.config}/opencode/skills/
gemini	~/.gemini/skills/
qwen	~/.qwen/skills/
kimi	${KIMI_CODE_HOME:-~/.kimi-code}/skills/
cursor	~/.cursor/skills/
hermes	~/.hermes/skills/
agents	~/.agents/skills/

Existing installations are preserved unless --force is passed. A forced update validates a staged copy first, then replaces the active installation without leaving an old skill directory for the client to index.

Use

After installation, a compatible agent can pick this skill automatically when the request looks like requirements gathering:

Ask me questions before implementation.

Collect requirements before you build.

You can also invoke the skill explicitly:

Use $interactive-project-questionnaire to collect requirements for this project.

Check

python3 scripts/smoke_test.py
python3 tests/install_skill_test.py

Features

• runs only on 127.0.0.1 and never creates a remote questionnaire;
• requires no npm, pip, Flask, FastAPI, or external service;
• saves canonical answers as JSON and Markdown with timestamped backups;
• supports English and Russian UI labels;
• supports “Other” and “Not sure / recommend for me” choices;
• saves per-question comments;
• rejects unknown option values, invalid scales, unknown IDs, and cyclic conditions;
• keeps schema, storage, HTTP server, and frontend rendering in separate runtime modules.

Documentation

Document	Contents
references/question_schema.md	questions.json schema
references/local_workflow.md	Local server and answer read-back contract
references/usage_examples.md	Prompts and usage examples
SKILL.md	Agent workflow and operating rules

---

Русский

Длинный опрос по проекту неудобно проводить в чате. Скилл собирает нерешённые вопросы в одну проверенную кликабельную анкету, которая работает на компьютере пользователя.

Сервер слушает только 127.0.0.1. Скилл не использует Codex Sites, Claude Artifacts, туннели, удалённые базы, публичные ссылки и внешний хостинг. После отправки формы ответы проходят проверку и сохраняются в проекте как answers.json и answers.md.

В установщике есть готовые пути для OpenCode, Claude Code, Gemini CLI, Qwen Code, Kimi Code CLI, Cursor, Codex и Hermes Agent. Для других клиентов можно выбрать ~/.agents/skills/ или передать нужный каталог через --target.

Как это работает

1. Агент собирает нерешённые вопросы в одну проверенную схему анкеты.
2. Запускает встроенный сервер на 127.0.0.1 и даёт пользователю локальную ссылку.
3. Пользователь выбирает варианты, добавляет свои ответы или комментарии и сохраняет форму.
4. Runtime записывает answers.json и answers.md, агент читает оба файла и продолжает исходную задачу.

Если браузер и агент работают в разных loopback-пространствах, агент задаёт минимум нужных вопросов в чате. Удалённую замену он не публикует.

Быстрый старт

Отправьте агенту ссылку на репозиторий:

Установи этот скилл для себя и проверь, что он работает:
https://github.com/sergeylopukhov/interactive-project-questionnaire

Tip

Инструкция для агента: клонируйте репозиторий во временную папку и проверьте SKILL.md. Выполните python3 scripts/install_skill.py --agent auto. Команда скопирует пакет и запустит smoke-тест из установленной папки. Если автоматическое определение не сработало, найдите глобальный каталог Agent Skills своего клиента и передайте путь через --target.

Ручная установка и профили агентов

git clone --depth 1 https://github.com/sergeylopukhov/interactive-project-questionnaire.git
cd interactive-project-questionnaire
python3 scripts/install_skill.py --agent auto

Для другого агента или сразу нескольких:

python3 scripts/install_skill.py --agent claude
python3 scripts/install_skill.py --agent opencode
python3 scripts/install_skill.py --agent gemini
python3 scripts/install_skill.py --agent qwen
python3 scripts/install_skill.py --agent kimi
python3 scripts/install_skill.py --agent cursor
python3 scripts/install_skill.py --agent all

Для любого другого клиента Agent Skills укажите его каталог:

python3 scripts/install_skill.py --target /путь/к/каталогу/skills

Готовые профили:

Профиль	Глобальный каталог
codex	${CODEX_HOME:-~/.codex}/skills/
claude	~/.claude/skills/
opencode	${XDG_CONFIG_HOME:-~/.config}/opencode/skills/
gemini	~/.gemini/skills/
qwen	~/.qwen/skills/
kimi	${KIMI_CODE_HOME:-~/.kimi-code}/skills/
cursor	~/.cursor/skills/
hermes	~/.hermes/skills/
agents	~/.agents/skills/

Установщик не перезаписывает существующую копию без --force. При принудительном обновлении он сначала проверяет временную копию, затем заменяет активную установку и не оставляет старый каталог, который клиент мог бы принять за второй скилл.

Использование

После установки агент сам выберет скилл, когда запрос потребует собрать требования:

Сначала задай мне вопросы по проекту.

Собери требования перед реализацией.

Или вызовите скилл явно:

Используй $interactive-project-questionnaire, чтобы собрать требования к проекту.

Проверка

python3 scripts/smoke_test.py
python3 tests/install_skill_test.py

Что делает

• запускает анкету только на 127.0.0.1 и не создаёт удалённых форм;
• не требует npm, pip, Flask, FastAPI или внешних сервисов;
• сохраняет итоговые JSON и Markdown с датированными резервными копиями;
• поддерживает русский и английский интерфейс;
• добавляет «Другое / свой вариант» и «Не уверен / порекомендуй сам»;
• сохраняет комментарии к каждому вопросу;
• отклоняет неизвестные варианты, неверные шкалы, неизвестные ID и циклические условия;
• разделяет схему, хранение, HTTP-сервер и frontend-рендеринг по модулям.

Документация

Документ	Содержание
references/question_schema.md	Схема questions.json
references/local_workflow.md	Локальный сервер и контракт чтения ответов
references/usage_examples.md	Примеры запросов и сценариев
SKILL.md	Порядок работы и правила для агента

---

License

MIT © 2026 Sergey Lopukhov.