# Справочник skills и agents Abulafia

## 1. Как читать этот справочник

Skill — это Markdown-контракт в `skills/<name>/SKILL.md`. Он описывает условие
активации, правила работы, связанные workflows/agents/tools и ожидаемый
результат. Skill не является отдельной программой и обычно не запускается по
имени файла.

Пользователь взаимодействует одним из способов:

1. описывает задачу естественным языком;
2. запускает связанный workflow через slash-команду;
3. запускает story по ID;
4. вызывает локальную служебную команду.

Фактические skills, tools и commands активной установки можно проверить:

```text
/capabilities
/commands
/tools
/agents
```

## 2. Research workflow skills

### 2.1 `deep-research`

- **Что делает:** проводит широкое исследование темы с опорой на первичные
  источники, выделяет согласие, разногласия и пробелы.
- **Запуск:** `/deepresearch <тема>` или `abulafia deepresearch "<тема>"`.
- **Agents:** `researcher`, `verifier`, `reviewer`.
- **Результат:** cited brief в `outputs/` и provenance sidecar.
- **Когда выбирать:** нужен не быстрый ответ, а проверяемый многоисточниковый
  доклад.

### 2.2 `literature-review`

- **Что делает:** ищет научные статьи и синтезирует state of the art.
- **Запуск:** `/lit <тема>`.
- **Agents:** `researcher`, `verifier`, `reviewer`.
- **Результат:** literature review в `outputs/` с provenance.
- **Когда выбирать:** нужны школы мысли, методы, ключевые работы и research gaps.

### 2.3 `peer-review`

- **Что делает:** имитирует строгую, но конструктивную научную рецензию.
- **Запуск:** `/review <артефакт>`.
- **Agents:** `researcher`, `reviewer`.
- **Результат:** structured review в `outputs/`.
- **Проверяет:** novelty, baselines, methods, evaluation, ablations,
  reproducibility, citations и соответствие выводов доказательствам.

### 2.4 `paper-writing`

- **Что делает:** превращает собранные результаты в связный paper-style draft.
- **Запуск:** `/draft <задача>`.
- **Agents:** `writer`, `verifier`.
- **Результат:** Markdown-черновик в `papers/`.
- **Ограничение:** не создаёт вымышленные данные, эксперименты или citations.

### 2.5 `source-comparison`

- **Что делает:** сравнивает источники, papers, frameworks, инструменты или
  утверждения по явным критериям.
- **Запуск:** `/compare <источники и критерии>`.
- **Agents:** `researcher`, `verifier`.
- **Результат:** grounded comparison matrix в `outputs/`.

### 2.6 `paper-code-audit`

- **Что делает:** сопоставляет claims статьи с публичным кодом и проверяет
  воспроизводимость заявленной реализации.
- **Запуск:** `/audit <статья, repository или задача>`.
- **Agents:** `researcher`, `verifier`.
- **Результат:** audit report в `outputs/`.
- **Ищет:** отсутствующие компоненты, расхождения конфигураций, неполные scripts,
  недоказанные benchmarks и provenance gaps.

### 2.7 `replication`

- **Что делает:** планирует или выполняет воспроизведение paper, claim или
  benchmark.
- **Запуск:** `/replicate <paper>`.
- **Agent:** `researcher`.
- **Результат:** replication plan, scripts и results.
- **Gate:** перед исполнением просит выбрать local, virtual environment, Docker,
  cloud или plan-only.

### 2.8 `autoresearch`

- **Что делает:** запускает автономный цикл «гипотеза -> эксперимент -> метрика
  -> сохранить/отбросить -> повторить».
- **Запуск:** `/autoresearch <идея или метрика>`.
- **Tools:** `init_experiment`, `run_experiment`, `log_experiment`, если package
  `pi-autoresearch` установлен.
- **Результат:** `autoresearch.md`, `autoresearch.sh`, `autoresearch.jsonl`.

### 2.9 `watch`

- **Что делает:** создаёт baseline-обзор и периодически проверяет обновления по
  теме, компании, paper area или продукту.
- **Запуск:** `/watch <тема>`.
- **Agent:** `researcher`.
- **Package:** `pi-schedule-prompt`.
- **Результат:** baseline в `outputs/` и recurring schedule.

## 3. Project и session skills

### 3.1 `jobs`

- **Что делает:** показывает background processes, scheduled prompts и текущие
  subagent tasks.
- **Запуск:** `/jobs`.
- **Результат:** интерактивная сводка; отдельный исследовательский отчёт обычно
  не создаётся.

### 3.2 `session-log`

- **Что делает:** сохраняет выполненную работу, выводы, открытые вопросы и
  следующие шаги.
- **Запуск:** `/log`.
- **Результат:** `notes/session-logs/<session>.md`.

### 3.3 `session-search`

- **Что делает:** ищет по прошлым JSONL-сессиям Abulafia.
- **Запуск:** `/search <query>`.
- **Данные:** `%USERPROFILE%\.abulafia\sessions`.
- **Возможность:** найденную сессию можно продолжить через `resume` в UI поиска.

### 3.4 `preview`

- **Что делает:** рендерит Markdown, LaTeX, PDF или code artifacts.
- **Запуск:** `/preview`, `/preview --file <path>`, `/preview-pdf`.
- **Dependencies:** browser; для PDF могут понадобиться Pandoc и LaTeX.
- **Результат:** временный browser/PDF preview; canonical Markdown не заменяется.

### 3.5 `eli5`

- **Что делает:** объясняет сложный paper или концепцию простыми словами.
- **Запуск:** естественный запрос «объясни простыми словами».
- **Структура:** One-Sentence Summary, Big Idea, How It Works, Why It Matters,
  Skepticism и три главных вывода.
- **Особенность:** для конкретной статьи сначала использует `alpha`.

### 3.6 `contributing`

- **Что делает:** задаёт правила внесения изменений в сам репозиторий Abulafia.
- **Когда применяется:** изменение `src/`, `prompts/`, `skills/`, agents,
  install/release pipeline или документации.
- **Обязательные проверки:** `npm test`, `npm run typecheck`, `npm run build`.

## 4. Paper access skill

### 4.1 `alpha-research`

- **Что делает:** поиск, чтение, Q&A, code inspection и annotations для papers
  через alphaXiv-backed CLI.
- **Основные команды:**

```text
alpha search --mode semantic "<query>"
alpha get <arxiv-id-or-url>
alpha get --full-text <arxiv-id>
alpha ask <arxiv-id> "<question>"
alpha code <github-url> [path]
alpha annotate <paper-id> "<note>"
```

- **Авторизация:** `abulafia alpha login`.
- **Когда применять:** papers и arXiv.
- **Когда не применять в одиночку:** latest product, pricing, regulations и
  текущие software releases; для них нужен web search.

## 5. Compute skills

### 5.1 `docker`

- **Что делает:** исполняет research code в изолированном контейнере.
- **Когда выбирать:** непроверенный repository, конфликтующие dependencies,
  воспроизведение или benchmark в sandbox.
- **Tool boundary:** разрешает `docker:*` команды.
- **Результат:** код и результаты пишутся обратно в mounted workspace.
- **GPU:** требует Docker с NVIDIA Container Toolkit.

### 5.2 `modal-compute`

- **Что делает:** запускает stateless GPU workloads в Modal.
- **Когда выбирать:** burst training, inference или benchmark без постоянного
  pod lifecycle.
- **Команды:** `modal run`, `modal deploy`, `modal shell`.
- **Предпосылка:** установлен и настроен Modal CLI.

### 5.3 `runpod-compute`

- **Что делает:** создаёт persistent GPU pods с SSH-доступом.
- **Когда выбирать:** длительный эксперимент, большой dataset, многошаговая
  работа или необходимость сохранять volume между запусками.
- **Команды:** `runpodctl create/get/start/stop/remove pod`.
- **Правило:** после работы остановить или удалить pod.

## 6. Общие story skills

### 6.1 `journal-yuga-common`

Обязательный общий слой для всех S01-S11.

Он отвечает за:

- per-instance state;
- intake и acceptance criteria;
- clarification gate;
- управляющую фразу `хватит вопросов`;
- порядок venue database -> dossiers -> curated index -> web;
- `journal-search-log.md`;
- automatic append-only dossier updates;
- требования к fit reasoning, effort, risk и semantic-loss analysis.

Этот skill не запускается как отдельная пользовательская story. Он всегда
применяется вместе с конкретным `story-sXX-*`.

### 6.2 `megaagent-hu-dialogue`

Общий диалоговый протокол для A01, A06 и A08, где результат должен быть
сформирован через содержательное обсуждение с исследователем (`Hu`), а не
одним ответом модели.

Он отвечает за:

- discussion gate перед созданием итогового артефакта;
- уточнение только блокирующих вопросов;
- управляющие фразы `хватит вопросов` и `stop asking`;
- продолжение с явными метками `Assumption` и `Unknown`, если пользователь
  принудительно завершил уточнение;
- обязательный Discussion Log: вопросы агента, ответы человека и открытые или
  отложенные решения.

Этот skill не запускается отдельно. Он автоматически дополняет контракты
`story-a01-briefer`, `story-a06-validation-hu-assistant` и
`story-a08-analysis-hu-assistant`.

### 6.3 `story-evaluation`

- **Что делает:** оценивает готовые outputs A01-A10 и S01-S11 по методике 21
  stories.
- **Запуск:** `/evaluate-stories <story-id|all> <artifact-or-directory>`.
- **Результат:** scored evaluation report в `outputs/`.
- **Важно:** evaluator не выполняет story и не улучшает её артефакт.

## 7. MegaAgent story skills A01-A10

| Skill | Что делает | Primary output | Handoff |
| --- | --- | --- | --- |
| `story-a01-briefer` | Превращает raw questions, заметки или статью в исследовательский brief: problem/object/subject, PECO, scope и критерии. | `A01-briefer-brief.md` | A02 получает поисковые рамки. |
| `story-a02-librarian` | Строит query strategy, находит, ранжирует, тегирует и дедуплицирует источники. | `A02-librarian-resource-list.md` | A03 получает traceable resource list. |
| `story-a03-eligibility-screener` | Делает двухэтапный thematic screening и присваивает include/exclude/borderline. | `A03-eligibility-verdicts.md` | A04 получает тематически допустимые источники. |
| `story-a04-quality-screener` | Оценивает methods, completeness, bias и reproducibility, формирует Resource Matrix. | `A04-quality-resource-matrix.md` | A05 получает evidence base с caveats. |
| `story-a05-review-summarizator` | Создаёт читаемый analytical review, consensus, disagreements, gaps и disputed questions. | `A05-resource-review.md` | A06 получает материал для human validation. |
| `story-a06-validation-hu-assistant` | Фиксирует решения человека по borderline cases, scope и sources. | `A06-hu-corrections-log.md` | A07 получает явные corrections. |
| `story-a07-analyser` | Строит source/thesis landscapes, citation edges, schools, datasets и case maps. | `A07-landscapes.md` | A08 получает многомерную карту области. |
| `story-a08-analysis-hu-assistant` | Фиксирует approved focuses, deprioritized branches и evidence warnings. | `A08-focuses-log.md` | A09 получает downstream constraints. |
| `story-a09-hypothiser` | Формирует testable hypotheses, counterevidence, data needs и failure conditions. | `A09-hypothesis-system.md` | A10 получает систему гипотез. |
| `story-a10-reporter` | Синтезирует весь pipeline в отчуждаемый аналитический доклад с provenance. | `A10-analytical-report.md` | Финальный продукт. |

### Ключевые quality bars A-series

- A01 должен быть достаточно точным, чтобы A02 не повторял интервью.
- A02 не сохраняет источник без traceable metadata.
- A03 связывает каждый verdict с конкретным критерием.
- A04 обосновывает quality через метод, data, sample и limitations.
- A05 сохраняет minority positions и caveats.
- A06 и A08 не прячут human decisions внутри обычной прозы.
- A07 маркирует unsupported или inferred edges.
- A09 отделяет descriptive findings от testable hypotheses.
- A10 трассирует claims к sources, landscapes, hypotheses и human logs.

## 8. Journal-Yuga story skills S01-S11

| Skill | Что делает | Primary output |
| --- | --- | --- |
| `story-s01-journal-pool` | Подбирает реалистичный пул журналов для готового draft с учётом неформальных ограничений, effort и semantic-loss risk. | `S01-journal-pool.md` |
| `story-s02-mismatch-map` | Сравнивает draft с фиксированным журналом и делит несоответствия на fatal/major/minor. | `S02-mismatch-map.md` |
| `story-s03-positioning-routes` | Проектирует несколько disciplinary routes и article genres из abstract или идеи. | `S03-positioning-routes.md` |
| `story-s04-formal-edit-plan` | Создаёт минимальный план формальных правок под institutional requirement. | `S04-minimal-formal-edit-plan.md` |
| `story-s05-proceedings-plan` | Проверяет CFP fit, deadline, section, template и строит compression plan. | `S05-proceedings-plan.md` |
| `story-s06-strategic-designs` | Проектирует 2-3 содержательно разные структуры статьи для target journal pool. | `S06-strategic-article-designs.md` |
| `story-s07-disciplinary-translation` | Адаптирует русский scholarly text к англоязычному disciplinary register и создаёт citation bridges. | `S07-disciplinary-translation-plan.md` |
| `story-s08-revision-plan` | Разбирает rejection/R&R, разделяет formal, conceptual и methodological objections и предлагает revision или rerouting. | `S08-revision-plan.md` |
| `story-s09-corpus-profile` | Анализирует пользовательский корпус журнала: section lengths, argument structures и citation ecology. | `S09-journal-corpus-profile.md` |
| `story-s10-submission-package` | Проверяет metadata, authors, references, ethics/disclosure/AI policy и готовит cover letter. | `S10-submission-package.md` |
| `story-s11-editorial-board-profile` | Профилирует публичные академические интересы editors и строит теоретические points of resonance. | `S11-editorial-board-profile.md` |

### Ключевые quality bars S-series

- S01 оценивает смысл статьи, а не только keyword overlap.
- S02 основывает expectations на scope, guidelines и recent articles.
- S03 предлагает реально разные routes.
- S04 минимизирует вмешательство в содержание.
- S05 сохраняет core argument при сокращении.
- S06 создаёт структурные, а не косметические варианты.
- S07 является disciplinary adaptation, а не буквальным переводом.
- S08 отделяет тон рецензента от actionable substance.
- S09 использует article IDs и извлечённые counts.
- S10 не меняет смысл на final compliance stage.
- S11 использует только публичные academic evidence и не психологизирует
  редакторов.

## 9. Базовые agents

| Agent | Роль | Типичные tools | Default output |
| --- | --- | --- | --- |
| `researcher` | Поиск и чтение papers, web sources, repositories, docs и local artifacts. | read/write/edit, shell, search, web/fetch | `research.md` |
| `verifier` | Проверка claims, citations, URL и provenance; удаление unsupported statements. | read/edit, search, web/fetch | `cited.md` |
| `reviewer` | Скептический peer review или adversarial verification pass. | Зависит от runtime contract | `review.md` |
| `writer` | Создание связного документа из готовой evidence base без изобретения фактов. | read/write/edit | `draft.md` |

### `researcher`

Требует URL для каждого внешнего источника, читает источник до содержательного
пересказа, использует stable numeric IDs и записывает evidence table на диск.

### `verifier`

Связывает factual claims с citations, проверяет, что URL поддерживает именно
данное утверждение, и удаляет или ослабляет неподтверждённый материал.

### `reviewer`

Ищет слабые baselines, missing ablations, evaluation mismatches, leakage,
reproducibility gaps и claims, которые сильнее фактических результатов.

### `writer`

Синтезирует переданные материалы. Он не должен самостоятельно превращать
отсутствующие данные в polished results.

## 10. Story agents

Для каждой A/S story существует одноимённый agent specification:

```text
.abulafia/agents/story-a01-briefer.md
...
.abulafia/agents/story-a10-reporter.md
.abulafia/agents/story-s01-journal-pool.md
...
.abulafia/agents/story-s11-editorial-board-profile.md
```

Story agent определяет persona и ответственность. Paired story skill определяет
структуру и quality bar. `prompts/story.md` является parent orchestrator, а
`src/workflows/story-runner.ts` реализует local deterministic режим.

Не вызывайте `subagent` с именем `story-*`, если `/agents` или schema tool явно
не показывает такое имя как поддерживаемый runtime mode. Наличие agent-файла не
равно наличию отдельного subagent backend.

## 11. Workflows без отдельного одноимённого skill

Некоторые prompt workflows доступны напрямую, даже если отдельного
`skills/<name>` нет:

| Workflow | Назначение |
| --- | --- |
| `/summarize` | RLM-style иерархическое суммирование большого URL, PDF или файла без помещения всего source в model context. |
| `/story` | Parent orchestrator для A/S contracts. |
| `/evaluate-stories` | Model workflow и локальная evaluator command для готовых артефактов. |

## 12. Packages не являются skills

Core packages добавляют runtime-возможности:

| Package | Назначение |
| --- | --- |
| `@companion-ai/alpha-hub` | Работа с alphaXiv и papers. |
| `pi-subagents` | Делегирование agents. |
| `pi-btw` | Дополнительные runtime-возможности Pi. |
| `pi-docparser` | Parsing документов. |
| `pi-web-access` | Web search и получение контента. |
| `pi-markdown-preview` | Preview Markdown. |
| `@walterra/pi-charts` | Charts. |
| `pi-mermaid` | Mermaid diagrams. |
| `@aliou/pi-processes` | Background processes. |
| `pi-zotero` | Интеграция с Zotero. |
| `@kaiserlich-dev/pi-session-search` | Поиск по сессиям. |
| `pi-schedule-prompt` | Recurring и delayed prompts. |
| `@samfp/pi-memory` | Persistent memory. |
| `@tmustier/pi-ralph-wiggum` | Итеративные agent loops. |

Проверить установленный набор:

```powershell
abulafia packages list
abulafia doctor
```