@dzhechkov/skills-academic 0.1.0

package/document-checker/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: "document-checker"
+description: "Validates completeness of thesis defense package — required documents, formatting consistency, topic alignment."
+trust_tier: 2
+trust_tier_label: "Validated"
+validation:
+  schema_path: schemas/output.json
+  validator_path: scripts/validate-config.json
+---
+
+# Проверка комплектности документов к защите ВКР
+
+Skill для проверки полноты пакета документов перед защитой магистерской ВКР. Содержит только формальный чеклист обязательных и опциональных документов. Персональные данные студентов обрабатываются только в runtime при применении skill'а к конкретным материалам.
+
+## Когда использовать
+
+- Проверка комплектности пакета документов перед защитой
+- Проверка согласованности темы во всех документах
+- Проверка наличия обязательных элементов оформления
+- Быстрая предварительная проверка до детального анализа ВКР
+
+## Когда НЕ использовать
+
+- Для оценки содержания ВКР — используйте skill `dissertation-review`
+- Для генерации вопросов — используйте skill `question-generator`
+- Для исправления оформления — skill только проверяет, не исправляет
+
+## Чеклист документов
+
+### Обязательные документы
+
+| # | Документ | Что проверить | Критичность |
+|---|---------|---------------|-------------|
+| 1 | **ВКР (полный текст)** | PDF или DOCX, все страницы | Блокирующий |
+| 2 | **Отзыв научного руководителя** | Подпись (или электронная), рекомендуемая оценка | Блокирующий |
+| 3 | **Рецензия** | Подпись рецензента, рекомендуемая оценка | Блокирующий |
+| 4 | **Презентация** | PPT/PPTX/PDF, слайды читаемы | Условный* |
+
+*Презентация часто предоставляется непосредственно на защите. Отсутствие в предварительном пакете — не блокирующая проблема.
+
+### Обязательные элементы ВКР
+
+| # | Элемент | Что проверить |
+|---|---------|---------------|
+| 5 | **Титульный лист** | ФИО, тема, руководитель, год, программа |
+| 6 | **Содержание/оглавление** | Номера страниц, соответствие разделам |
+| 7 | **Список литературы** | Наличие, ссылки в тексте |
+| 8 | **Совпадение темы** | Тема одинакова в ВКР, отзыве, рецензии |
+
+### Технические требования
+
+| # | Проверка | Допустимо | Проблема |
+|---|---------|-----------|----------|
+| 9 | Формат файла ВКР | PDF, DOCX | Другой формат — запросить конвертацию |
+| 10 | Объём ВКР (магистерская) | 60-120 страниц | < 50 или > 150 — замечание |
+| 11 | Формат презентации | PPTX, PDF | Нечитаемый формат |
+| 12 | Читаемость файлов | Файлы открываются | Повреждённый файл — блокирующая проблема |
+
+### Опциональные документы
+
+| # | Документ | Статус |
+|---|---------|--------|
+| 13 | Аннотация | Желательно |
+| 14 | Справка антиплагиат | Желательно |
+
+## Протокол
+
+### Шаг 1: Проверить наличие обязательных документов
+
+Для каждого из 4 обязательных документов зафиксировать:
+- ✅ Найден
+- ❌ Не найден (блокирующая проблема — защита невозможна)
+
+Для опциональных: отметить наличие, отсутствие — не ошибка.
+
+### Шаг 2: Проверить титульный лист
+
+Убедиться что указаны:
+- Полное ФИО студента
+- Полная формулировка темы ВКР
+- ФИО и должность научного руководителя
+- Год защиты
+- Название университета и образовательной программы
+
+Отсутствие любого элемента — замечание.
+
+### Шаг 3: Проверить содержание/оглавление
+
+- Есть ли оглавление с номерами страниц?
+- Соответствуют ли разделы в оглавлении фактическим разделам в тексте?
+- Правильны ли номера страниц? (выборочно)
+
+### Шаг 4: Проверить список литературы
+
+- Есть ли список литературы/библиография?
+- Есть ли в тексте ссылки на источники из списка?
+- Используется ли единый стандарт оформления ссылок?
+
+### Шаг 5: Проверить соответствие темы во всех документах
+
+Сравнить формулировку темы:
+1. На титульном листе ВКР
+2. В отзыве руководителя
+3. В рецензии
+4. На первом слайде презентации
+
+**Расхождение в теме — серьёзная проблема**, которую нужно зафиксировать.
+
+### Шаг 6: Сформировать отчёт
+
+```
+ОТЧЁТ О КОМПЛЕКТНОСТИ ПАКЕТА
+═══════════════════════════════
+СТАТУС: [ПОЛНЫЙ / НЕПОЛНЫЙ]
+
+ОБЯЗАТЕЛЬНЫЕ ДОКУМЕНТЫ:
+  [✅/❌] ВКР (полный текст)
+  [✅/❌] Отзыв руководителя
+  [✅/❌] Рецензия
+  [✅/❌] Презентация
+
+ОБЯЗАТЕЛЬНЫЕ ЭЛЕМЕНТЫ:
+  [✅/❌] Титульный лист (полнота данных)
+  [✅/❌] Содержание/оглавление
+  [✅/❌] Список литературы
+  [✅/❌] Совпадение темы во всех документах
+
+ОПЦИОНАЛЬНЫЕ:
+  [✅/❌/—] Аннотация
+  [✅/❌/—] Справка антиплагиат
+
+ВЫЯВЛЕННЫЕ ПРОБЛЕМЫ:
+  1. [...]
+  2. [...]
+
+РЕКОМЕНДАЦИЯ: [Готов к защите / Требует доработки]
+═══════════════════════════════
+```
+
+## Рекомендуемый workflow
+
+```
+1. document-checker → проверить комплектность (ЭТОТ SKILL)
+2. dissertation-review → проанализировать содержание ВКР
+3. question-generator → подготовить вопросы к защите
+```
+
+Document-checker — **первый шаг** перед детальным анализом. Если пакет неполный — нет смысла анализировать содержание.
+
+## Антипаттерны
+
+| Антипаттерн | Почему это проблема | Правильный подход |
+|-------------|--------------------|--------------------|
+| Не проверять тему во всех документах | Расхождение может означать ошибку в документах | Всегда сверять тему |
+| Считать отсутствие аннотации ошибкой | Аннотация — опциональный документ | Отмечать как "отсутствует", не как ошибку |
+| Пропускать проверку титульного листа | Формальные ошибки видны комиссии | Проверять даже если "очевидно" |
+| Не проверять ссылки на литературу | Список может быть "декоративным" | Выборочно проверить 2-3 ссылки |
+| Путать проверку документов с рецензированием | Это разные задачи | Сначала document-checker, потом dissertation-review |
+
+## Самопроверка
+
+- [ ] Все 4 обязательных документа проверены на наличие?
+- [ ] Опциональные документы отмечены отдельно (не как ошибка)?
+- [ ] Титульный лист проверен на полноту данных?
+- [ ] Наличие содержания/оглавления подтверждено?
+- [ ] Список литературы проверен?
+- [ ] Тема сверена минимум в 3 документах (ВКР, отзыв, рецензия)?
+- [ ] Итоговый статус пакета определён (полный/неполный)?
+- [ ] Рекомендация о готовности к защите дана?
+
+## Примеры
+
+**В рамках задачи:**
+- "Проверь комплектность пакета документов из архива"
+- "Совпадает ли тема ВКР в отзыве и рецензии?"
+- "Все ли обязательные документы предоставлены?"
+- "Сформируй отчёт о готовности пакета к защите"
+
+**Вне задачи:**
+- "Оцени качество ВКР" — используй `dissertation-review`
+- "Исправь оформление" — skill только проверяет, не исправляет

package/document-checker/evals/document-checker.yaml

@@ -0,0 +1,53 @@
+# document-checker evaluation
+# Run: aqe eval document-checker
+
+test_cases:
+  - name: "basic invocation"
+    input: "Проверь комплектность пакета документов"
+    expected:
+      status: success
+      summary_contains: "document-checker"
+
+  - name: "complete package"
+    input: "Проверь пакет документов: ВКР, отзыв руководителя, рецензия и презентация — все на месте"
+    expected:
+      status: success
+      package_status: complete
+      has_fields:
+        - documents
+        - recommendation
+
+  - name: "incomplete package - missing review"
+    input: "Проверь пакет: есть ВКР и презентация, но нет рецензии"
+    expected:
+      status: success
+      package_status: incomplete
+      has_fields:
+        - issues
+      issues_severity_includes: critical
+
+  - name: "title page validation"
+    input: "Проверь титульный лист ВКР"
+    expected:
+      status: success
+      has_fields:
+        - title_page_check
+
+  - name: "topic consistency check"
+    input: "Сравни формулировку темы в ВКР, отзыве и рецензии"
+    expected:
+      status: success
+      has_fields:
+        - topic_consistency
+
+  - name: "full report generation"
+    input: "Сформируй полный отчёт о комплектности пакета документов для защиты"
+    expected:
+      status: success
+      has_fields:
+        - package_status
+        - documents
+        - title_page_check
+        - topic_consistency
+        - issues
+        - recommendation

package/document-checker/schemas/output.json

@@ -0,0 +1,114 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "document-checker output",
+  "description": "Structured output from the document-checker skill",
+  "type": "object",
+  "required": ["status", "package_status", "documents", "issues", "recommendation"],
+  "properties": {
+    "status": {
+      "type": "string",
+      "enum": ["success", "error", "skipped"]
+    },
+    "student_name": {
+      "type": "string",
+      "description": "Student full name from the title page"
+    },
+    "topic": {
+      "type": "string",
+      "description": "Thesis topic from the title page"
+    },
+    "package_status": {
+      "type": "string",
+      "enum": ["complete", "incomplete"],
+      "description": "Overall package completeness status"
+    },
+    "documents": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "required", "found"],
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Document name"
+          },
+          "required": {
+            "type": "boolean",
+            "description": "Whether the document is mandatory"
+          },
+          "found": {
+            "type": "boolean",
+            "description": "Whether the document was found"
+          },
+          "format": {
+            "type": "string",
+            "description": "File format (PDF, DOCX, PPTX, etc.)"
+          },
+          "remarks": {
+            "type": "string",
+            "description": "Additional remarks about the document"
+          }
+        }
+      }
+    },
+    "title_page_check": {
+      "type": "object",
+      "properties": {
+        "student_name": { "type": "boolean" },
+        "topic": { "type": "boolean" },
+        "supervisor": { "type": "boolean" },
+        "year": { "type": "boolean" },
+        "university": { "type": "boolean" }
+      },
+      "description": "Title page fields presence check"
+    },
+    "table_of_contents": {
+      "type": "boolean",
+      "description": "Whether table of contents is present"
+    },
+    "bibliography": {
+      "type": "object",
+      "properties": {
+        "present": { "type": "boolean" },
+        "source_count": { "type": "integer" },
+        "references_valid": { "type": "boolean" }
+      },
+      "description": "Bibliography check results"
+    },
+    "topic_consistency": {
+      "type": "object",
+      "properties": {
+        "consistent": {
+          "type": "boolean",
+          "description": "Whether the topic matches across all documents"
+        },
+        "discrepancies": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "List of discrepancies found"
+        }
+      }
+    },
+    "issues": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["severity", "description"],
+        "properties": {
+          "severity": {
+            "type": "string",
+            "enum": ["critical", "warning", "info"]
+          },
+          "description": {
+            "type": "string",
+            "description": "Issue description"
+          }
+        }
+      }
+    },
+    "recommendation": {
+      "type": "string",
+      "description": "Final recommendation on package readiness for defense"
+    }
+  }
+}

package/document-checker/scripts/validate-config.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "document-checker config validator",
+  "description": "Validates configuration inputs for the document-checker skill",
+  "type": "object",
+  "properties": {
+    "documents_directory": {
+      "type": "string",
+      "description": "Path to directory containing all defense documents"
+    },
+    "thesis_path": {
+      "type": "string",
+      "description": "Path to the thesis document"
+    },
+    "supervisor_review_path": {
+      "type": "string",
+      "description": "Path to the supervisor review"
+    },
+    "external_review_path": {
+      "type": "string",
+      "description": "Path to the external review"
+    },
+    "presentation_path": {
+      "type": "string",
+      "description": "Path to the presentation file"
+    },
+    "antiplagiat_path": {
+      "type": "string",
+      "description": "Path to the antiplagiat report (optional)"
+    },
+    "abstract_path": {
+      "type": "string",
+      "description": "Path to the abstract (optional)"
+    },
+    "check_optional": {
+      "type": "boolean",
+      "default": false,
+      "description": "Whether to flag missing optional documents as warnings"
+    }
+  },
+  "anyOf": [
+    { "required": ["documents_directory"] },
+    { "required": ["thesis_path"] }
+  ]
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@dzhechkov/skills-academic",
+  "version": "0.1.0",
+  "description": "Academic skill pack — dissertation review, question generation, document checking for thesis defense (ГЭК). Contains only evaluation criteria and methodology, no student data.",
+  "license": "MIT",
+  "author": "dzhechko",
+  "keywords": [
+    "agent-skills",
+    "agentskills.io",
+    "skill-pack",
+    "academic",
+    "dissertation",
+    "thesis-defense",
+    "evaluation"
+  ],
+  "files": [
+    "dissertation-review",
+    "question-generator",
+    "document-checker",
+    "defense-evaluator",
+    "answer-assessor",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/djd1m/dz-harness-hub.git",
+    "directory": "packages/@dzhechkov/skills-academic"
+  }
+}

package/question-generator/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: "question-generator"
+description: "Generates defense questions of varying difficulty — basic understanding, methodology, application, and critical analysis."
+trust_tier: 2
+trust_tier_label: "Validated"
+validation:
+  schema_path: schemas/output.json
+  validator_path: scripts/validate-config.json
+---
+
+# Генерация вопросов к защите ВКР
+
+Skill для генерации вопросов разной сложности к защите магистерской ВКР. Содержит только методику формирования вопросов и шаблоны категорий. Персональные данные студентов обрабатываются только в runtime при применении skill'а к конкретным материалам.
+
+## Когда использовать
+
+- Подготовка вопросов к защите ВКР до заседания
+- Формирование набора вопросов разной сложности и категорий
+- Подготовка вопросов по слабым местам и замечаниям рецензента
+- Подготовка вопросов, демонстрирующих внимательное ознакомление с работой
+
+## Когда НЕ использовать
+
+- Для подготовки студента к защите (skill для члена ГЭК)
+- Для генерации вопросов без прочтения хотя бы аннотации, введения и заключения
+
+## Протокол
+
+### Шаг 1: Определить ключевые понятия
+
+Прочитать тему, аннотацию, введение и заключение ВКР. Составить списки:
+- **Ключевые термины** — специфические понятия работы
+- **Методы** — какие методы исследования применялись
+- **Результаты** — основные выводы и рекомендации
+- **Ограничения** — что автор сам указал как ограничения
+
+### Шаг 2: Базовые вопросы (3-5 штук, сложность 1)
+
+Цель: проверить понимание студентом предмета своего исследования.
+
+| Шаблон | Что проверяет |
+|--------|---------------|
+| "Что вы понимаете под [ключевой термин]?" | Владение понятийным аппаратом |
+| "Какова основная цель вашей работы?" | Понимание собственных целей |
+| "Какие ключевые результаты вы получили?" | Знание своих выводов |
+| "Как вы определяете [объект исследования]?" | Корректность определений |
+| "В чём актуальность вашей темы?" | Понимание контекста |
+
+### Шаг 3: Методологические вопросы (3-5 штук, сложность 2)
+
+Цель: оценить обоснованность выбора методов и глубину понимания.
+
+| Шаблон | Что проверяет |
+|--------|---------------|
+| "Почему вы выбрали метод X, а не Y?" | Обоснованность выбора |
+| "Какие ограничения у выбранного метода?" | Критическое мышление |
+| "Как бы изменились результаты при другой выборке?" | Устойчивость результатов |
+| "На основании чего вы считаете выборку достаточной?" | Статистическая грамотность |
+| "Какие альтернативные методы рассматривались?" | Широта методологического кругозора |
+
+### Шаг 4: Практические вопросы (2-3 штуки, сложность 2)
+
+Цель: оценить понимание практической применимости.
+
+| Шаблон | Что проверяет |
+|--------|---------------|
+| "Кто может использовать ваши результаты на практике?" | Понимание целевой аудитории |
+| "Как внедрить ваши рекомендации в организации?" | Реалистичность рекомендаций |
+| "Какой экономический/социальный эффект ожидается?" | Обоснованность ожиданий |
+| "Есть ли подтверждение от организации о готовности внедрения?" | Связь с практикой |
+
+### Шаг 5: Критические вопросы (1-2 штуки, сложность 3)
+
+Цель: проверить способность студента к рефлексии и защите своей позиции.
+
+| Шаблон | Что проверяет |
+|--------|---------------|
+| "Какие допущения вы сделали и насколько они обоснованы?" | Осознанность ограничений |
+| "Что бы вы изменили, если бы начали исследование заново?" | Рефлексия |
+| "Ваш вывод X противоречит [известному факту/теории]. Как вы это объясняете?" | Устойчивость к критике |
+| "Какова главная слабость вашей работы?" | Самокритичность |
+| "Вы представляете [CJM TO BE / VSM TO BE / прогноз] как результат. На каких эмпирических данных основана эта оценка и проводилась ли пилотная проверка?" | Разделение проектных оценок и измеренных данных |
+
+### Шаг 6: Смежные вопросы (1-2 штуки, сложность 2-3)
+
+Цель: оценить широту кругозора и связь с другими дисциплинами.
+
+| Шаблон | Что проверяет |
+|--------|---------------|
+| "Как ваша тема связана с направлением [смежная область]?" | Междисциплинарное мышление |
+| "Какие подходы используются в смежных областях для похожих задач?" | Эрудиция |
+
+### Шаг 7: Вопросы для командных проектов
+
+Если ВКР выполнена в команде, добавить 1-2 вопроса:
+- "Какой ваш личный вклад в данный результат?"
+- "Можете ли вы назвать ключевые показатели для вашей части проекта?"
+
+### Шаг 8: Привязка вопросов к страницам ВКР
+
+Каждый вопрос должен ссылаться на конкретную страницу/раздел:
+- Формат: "На странице N (раздел X.Y) вы утверждаете, что... Вопрос: ..."
+- Это демонстрирует внимательное прочтение и помогает студенту сориентироваться
+
+## Формат вопроса
+
+Каждый вопрос в итоговом наборе содержит:
+
+```
+Вопрос:    [формулировка]
+Категория: [базовый / методологический / практический / критический / смежный]
+Сложность: [1 — базовый, 2 — продвинутый, 3 — экспертный]
+Ожидаемые ключевые слова: [что должно прозвучать в ответе]
+Источник:  [из какого раздела/страницы ВКР взят вопрос]
+```
+
+## Рекомендуемый порядок вопросов
+
+1. **Базовый** (разогрев) — дать студенту возможность показать знания
+2. **Методологический** (основное тело) — проверить глубину понимания
+3. **Практический** — связь теории с реальностью
+4. **Критический** (финал) — для дифференциации оценки (4 vs 5)
+5. **Смежный** — в резерве, если осталось время
+
+Если студент не отвечает на базовый вопрос — не углубляться, перейти к другому базовому. Это сигнал для оценки.
+
+## Шаблон для записи вопросов/ответов во время защиты
+
+```
+ЛИСТ ВОПРОСОВ И ОТВЕТОВ
+═══════════════════════════════
+Студент: [заполняется в runtime]
+
+№ | Вопрос                    | Ответ (кратко)     | Оценка ответа
+1 | _________________________ | ___________________ | ⬜ полный ⬜ частичный ⬜ нет
+2 | _________________________ | ___________________ | ⬜ полный ⬜ частичный ⬜ нет
+3 | _________________________ | ___________________ | ⬜ полный ⬜ частичный ⬜ нет
+4 | _________________________ | ___________________ | ⬜ полный ⬜ частичный ⬜ нет
+5 | _________________________ | ___________________ | ⬜ полный ⬜ частичный ⬜ нет
+6 | _________________________ | ___________________ | ⬜ полный ⬜ частичный ⬜ нет
+
+Общее впечатление: ⬜ уверенно ⬜ неуверенно ⬜ не владеет
+═══════════════════════════════
+```
+
+## Рекомендуемый workflow
+
+```
+1. document-checker → проверить комплектность
+2. dissertation-review → проанализировать ВКР, выявить сильные/слабые стороны
+3. question-generator → сгенерировать вопросы на основе анализа
+```
+
+## Ограничения по времени
+
+На вопросы отводится **10-15 минут**, реально **4-6 вопросов** с ответами. Рекомендуется:
+- Минимум 1 базовый (для разогрева)
+- 2-3 методологических или практических (основное тело)
+- 1 критический (для дифференциации оценки)
+- Держать смежные вопросы в резерве
+- Для командных проектов: минимум 1 вопрос о личном вкладе
+
+## Антипаттерны
+
+| Антипаттерн | Почему это проблема | Правильный подход |
+|-------------|--------------------|--------------------|
+| Все вопросы одной сложности | Не дифференцирует оценку | Микс из 3 уровней сложности |
+| Вопросы не по теме ВКР | Нарушение регламента ГЭК | Привязывать к конкретным разделам работы |
+| Только "каверзные" вопросы | Не даёт студенту показать знания | Начинать с базовых |
+| Нет вопросов по замечаниям рецензента | Упущена возможность проверки | Включить хотя бы 1 вопрос по замечаниям |
+| Слишком много вопросов | Выход за тайминг | Максимум 6, с резервом |
+
+## Самопроверка
+
+- [ ] Прочитаны ли тема, аннотация, введение и заключение?
+- [ ] Составлен ли список ключевых терминов и методов?
+- [ ] Есть ли минимум 1 базовый вопрос?
+- [ ] Есть ли минимум 2 методологических вопроса?
+- [ ] Есть ли минимум 1 практический вопрос?
+- [ ] Есть ли минимум 1 критический вопрос?
+- [ ] Каждому вопросу присвоена категория и сложность?
+- [ ] Указаны ожидаемые ключевые слова в ответе?
+- [ ] Общее количество укладывается в 10-15 минут (4-6 вопросов)?
+- [ ] Есть ли вопрос по замечаниям руководителя или рецензента?
+
+## Примеры
+
+**В рамках задачи:**
+- "Сгенерируй 5 вопросов разной сложности по данной ВКР"
+- "Подготовь 2 критических вопроса по методологии исследования"
+- "Какие вопросы задать по замечаниям рецензента?"
+- "Сформируй набор вопросов, демонстрирующий внимательное прочтение работы"
+
+**Вне задачи:**
+- "Подготовь студента к защите" — skill для члена ГЭК, не для студента
+- "Оцени работу" — используй skill `dissertation-review`