Как превратить техническую книгу в AI Skill

Быстрый вывод

Симптом: после загрузки технической книги агент уверенно пересказывает отдельные главы, но теряет условия, исключения и связь с источником.

Самое быстрое решение: не превращайте книгу в один большой промпт. Сначала подтвердите право на обработку и сформулируйте задачи, затем извлеките главы с координатами, разделите концепции и процедуры, вынесите подробности в references и только после этого проверьте Skill на реальных сценариях.

В официальной спецификации Agent Skills основной файл SKILL.md используется как инструкция и навигационный слой, а дополнительные материалы и скрипты подключаются по мере необходимости. В документации также указаны ограничения для полей name и description: имя должно быть уникальным, состоять из строчных букв, цифр и дефисов, а описание должно объяснять назначение Skill и условия его применения. (официальная документация Agent Skills)

Кому пригодится эта схема

Эта статья предназначена разработчикам, которые хотят превратить собственную техническую книгу в рабочий инструмент для ежедневных задач. Она также подходит специалистам по инженерии знаний, переводящим внутренние учебные материалы в командный процесс.

Если вы опасаетесь, что сжатие длинной книги удалит важные ограничения и исключения, ниже приведена процедура с контрольными точками, а не набор общих советов.

Перед обработкой: права и назначение

Проверка разрешений

Обрабатывайте только материалы, которые вы вправе использовать в выбранном сценарии. Это может быть ваша книга, материал с открытой лицензией, корпоративный документ или экземпляр, для которого получено разрешение правообладателя.

Наличие файла на вашем компьютере само по себе не означает право распространять его содержание. Особенно осторожно относитесь к командному Skill: внутреннее использование небольшой группой и публикация полного набора извлечённых материалов — разные сценарии.

Правовые режимы зависят от юрисдикции и обстоятельств использования. Например, официальные разъяснения по fair use подчёркивают, что оценка строится по совокупности факторов, а универсального правила о допустимом количестве слов или проценте книги не существует. Поэтому правовую границу нельзя заменять формулой вроде «достаточно взять одну десятую текста». (разъяснения U.S. Copyright Office о fair use)

Определение конечной задачи

До извлечения текста запишите, что именно должен делать агент. Хорошая формулировка выглядит так:

проверять архитектурное решение по принципам из книги;
объяснять выбор алгоритма с указанием ограничений;
составлять план внедрения по заданной методике;
находить пропущенные этапы в техническом проекте;
обучать сотрудника через вопросы и практические задания.

Фраза «знать всю книгу» не является рабочей задачей. Она не помогает определить, какие главы нужны, какие примеры можно отбросить и как измерять качество ответа.

Важное ограничение: Skill — это ориентированный на задачу продукт знаний, а не архив книги. Не включайте в него полный текст только потому, что технически можете его извлечь.

Решение по объёму

Если задача касается одного процесса, начните с нескольких релевантных глав. Например, для проверки проектирования API могут понадобиться разделы о принципах, ограничениях, обработке ошибок и тестировании, но не биография автора и не исторический обзор предметной области.

Так вы уменьшите три скрытые проблемы:

агент получает много нерелевантного контекста и хуже выбирает нужное правило;
проверка источников становится медленной;
ошибки трудно локализовать, потому что непонятно, на каком этапе появилась неверная формулировка.

Извлечение: структура важнее сплошного текста

Сохранение координат источника

Результат извлечения должен позволять вернуться к исходной книге. Минимальная запись для каждого фрагмента:

идентификатор книги и версия файла;
номер главы и подглавы;
страница или другая позиция в документе;
тип фрагмента: обычный текст, код, список, таблица, подпись к рисунку;
извлечённое содержимое;
отметка о качестве распознавания.

Не ограничивайтесь файлом book.txt. В нём быстро теряются границы разделов, а одинаковые термины из разных глав начинают выглядеть как одно утверждение.

Удобный промежуточный формат может содержать записи с полями chapter, section, page, content_type, text и ocr_status. Формат не обязан быть именно таким; важно, чтобы каждая будущая карточка знания имела обратную ссылку.

Обработка PDF и сканов

Текстовый PDF и скан требуют разных процедур. В первом случае можно извлечь текстовый слой, но всё равно нужно проверить код, математические выражения, переносы строк и таблицы. Во втором понадобится OCR, после которого обязательна выборочная сверка с изображением страницы.

Проблемы OCR особенно опасны для:

имён функций и параметров;
символов -, _, / и =;
версий библиотек;
числовых ограничений;
фрагментов кода с отступами;
таблиц, где порядок строк и столбцов несёт смысл.

Если инструмент извлечения поддерживает разбор PDF по элементам, используйте его для разделения заголовков, абзацев, таблиц и списков, а не только для получения одной строки текста. Документация инструментов извлечения обычно отдельно описывает OCR, структуру элементов и ограничения конкретных форматов; перед конвейером проверьте актуальные возможности выбранного решения. (официальная документация по Agent Skills и дополнительным ресурсам)

Контроль качества извлечения

Сделайте три проверки до суммирования:

Сравните оглавление с найденными заголовками и найдите пропавшие разделы.
Случайно выберите страницы из начала, середины и конца книги и сопоставьте их с извлечённым результатом.
Отдельно проверьте все страницы с кодом, таблицами, схемами и сносками.

Если на этом этапе встречаются ошибки, не переходите к генерации Skill. Модель может красиво исправить очевидный OCR-шум, но она также способна «додумать» пропущенный параметр и выдать правдоподобный, но не существующий в книге вывод.

Разметка знаний: концепции и процедуры

Карточка утверждения

Для каждого существенного фрагмента создайте структурированную карточку:

тезис — что утверждается;
условия — когда это применимо;
исключения — когда правило не работает;
пример — иллюстрация из книги или ваш новый пример;
источник — глава и страница;
тип — определение, принцип, шаг, проверка, предупреждение или контрпример;
уверенность — дословно подтверждено, аккуратно обобщено или требует ручной проверки.

Такая разметка отвечает на вопрос, что из технической книги нужно сохранять в Agent Skill. Сохранять следует не только «главную мысль», но и условия, при которых она перестаёт быть верной.

Разделение типов знания

Определения помогают агенту объяснять термины. Принципы задают направление решения. Процедуры описывают последовательность действий. Проверки позволяют оценить результат. Исключения ограничивают область применения.

Не смешивайте эти типы в одном абзаце. Правило «сначала проверьте X, затем выберите Y» должно отличаться от объяснения, почему X важен. Иначе при генерации ответа агент может выдать объяснение вместо действия или применить процедуру без предварительной проверки.

Особенно опасны условные советы:

«если система имеет ограничение по памяти, используйте…»;
«для небольших проектов достаточно…, но при росте нагрузки…»;
«этот метод работает при условии…»;
«не применяйте подход, когда…».

При сжатии удаляйте повторения, но не слова, меняющие область действия правила.

Самостоятельные примеры

Примеры из книги полезны для проверки понимания, но не всегда должны копироваться. Если материал защищён авторским правом, создайте собственный пример с тем же принципом и явно отделите его от содержания источника.

Например, книга может объяснять стратегию тестирования на примере платёжной системы. В Skill можно использовать вымышленный сервис бронирования, сохранив структуру рассуждения, но не воспроизводя оригинальный текст и уникальную последовательность примеров.

Проектирование Skill: слой инструкций и слой знаний

Содержимое `SKILL.md`

Основной файл должен отвечать на четыре вопроса:

Для каких запросов Skill активируется?
Какой результат должен подготовить агент?
Каков краткий порядок работы?
Где находятся подробные материалы и проверки?

В начале задайте корректные метаданные:

---
name: technical-book-review
description: Помогает проверять технические решения по выбранной книге; использовать при анализе архитектуры, сравнении подходов и поиске нарушенных условий применимости.
---

Значения должны соответствовать актуальной спецификации. Поле description является не рекламным слоганом, а важной частью механизма выбора Skill: в нём нужно описывать и назначение, и ситуации запуска. (официальная спецификация формата Skill)

После метаданных разместите:

краткую роль Skill;
входные данные и ожидаемый формат результата;
пошаговый алгоритм;
правило обязательной проверки условий;
формат ссылок на главу и страницу;
указания, когда агент должен сообщить о недостатке данных;
навигацию по дополнительным файлам.

Не помещайте сюда полный конспект. Основной файл должен оставаться читаемым для автора и достаточно компактным для надёжной загрузки.

Содержимое `references`

В references вынесите материалы, которые нужны не при каждом запуске:

подробный конспект глав;
словарь терминов;
список правил и исключений;
разбор типичных ошибок;
примеры решений;
карту «задача → релевантные главы»;
сведения о версии и редакции книги.

Вопрос «книгу размещать в SKILL.md или в references» решается по частоте использования и роли материала. Инструкция, которая управляет поведением агента, остаётся в SKILL.md. Фактический материал для поиска и проверки переносится в references.

Официальная модель Skills использует поэтапное раскрытие: сначала доступны метаданные, затем инструкции, а дополнительные документы и код читаются только при необходимости. Это снижает лишнюю загрузку контекста и позволяет разделять гибкие рекомендации, справочные данные и детерминированные операции. (официальное описание поэтапной загрузки ресурсов)

Содержимое `scripts`

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

проверка наличия обязательных полей в карточках;
поиск фрагментов без координат;
проверка ссылок на страницы;
разбиение документа на части;
формирование отчёта о пропусках;
запуск фиксированного набора тестов.

Не переносите в скрипт смысловую интерпретацию, если она требует оценки контекста. Программа может надёжно проверить, что у записи есть page, но не сможет без дополнительных правил решить, правильно ли автор обобщил исключение.

Сжатие и фактологическая проверка

Контроль потерь

После подготовки чернового Skill пройдите книгу по главам и задайте пять вопросов:

Не исчезли ли предварительные условия?
Не перепутаны ли рекомендация и обязательное требование?
Не потерялась ли версия технологии или исторический контекст?
Остались ли контрпримеры?
Есть ли ссылка на источник у каждого критического тезиса?

Затем удалите материал, не связанный с целевыми задачами. Нерелевантная информация опасна не только размером: она даёт агенту дополнительные варианты ответа и может конкурировать с более точным правилом.

Защита от добавленных выводов

Модель способна дополнить книгу общеизвестным объяснением, современной практикой или собственным предположением. Это допустимо только при явной маркировке внешнего знания. Если Skill должен отражать именно одну книгу, используйте режим:

«утверждение подтверждено источником»;
«это аккуратное обобщение»;
«в книге не найден ответ»;
«требуется внешний источник или проверка специалиста».

Так вы не создаёте ложное впечатление, будто автор книги поддерживает вывод, которого в ней нет.

Приёмка на реальных задачах

Четыре класса тестов

Чтобы проверить AI Skill, созданный по книге, сформируйте набор задач из четырёх групп.

Прямые вопросы. Ответ находится в одной главе. Проверяйте точность термина, ссылку на источник и отсутствие лишних утверждений.

Связанные задачи. Нужно объединить материал из нескольких глав. Например, сопоставить принцип проектирования с процедурой тестирования. Здесь проверяется не только поиск, но и порядок рассуждения.

Граничные случаи. В запросе нарушено условие, отсутствует параметр или выбран неподходящий подход. Хороший Skill не должен автоматически выдавать инструкцию; он должен сначала обозначить ограничение.

Неподходящие сценарии. Задача выглядит похожей по ключевым словам, но книга её не покрывает. Правильный ответ — честно сообщить об ограничении, а не заполнить пробел догадкой.

Для каждой проверки зафиксируйте ожидаемые свойства ответа:

нужное решение или корректный отказ;
перечисленные условия;
ссылка на главу и страницу;
отсутствие выдуманных фактов;
одинаковый порядок действий при повторном запуске.

Официальное руководство по созданию Skill также рекомендует проверять как срабатывание на подходящих запросах, так и отказ на близких, но неподходящих сценариях. Это важно, потому что слишком широкое описание вызывает Skill там, где агенту нужен другой процесс. (официальный шаблон создания Skill)

Сравнение до и после

Проведите тесты в двух режимах: без Skill и с ним. Не ограничивайтесь субъективным ощущением «ответ стал лучше». Считайте:

сколько ключевых условий сохранено;
сколько утверждений имеют обратную ссылку;
сколько ответов содержат неподтверждённые добавления;
насколько меняется результат при повторной формулировке запроса;
правильно ли агент отказывается от задач вне области книги.

Если после подключения Skill ответы стали длиннее, но количество проверяемых условий не выросло, конвейер, вероятно, производит расширенный пересказ, а не рабочий инструмент.

Решающий инструмент: выбор по условиям

Перед обработкой пройдите список сверху вниз. Отмечайте пункт только после проверки фактов. Если условие не выполнено, используйте указанную ветку, а не переходите к следующему этапу.

[ ] Право на обработку подтверждено.
Если да, переходите к постановке задачи. Если нет, остановите процесс и сначала уточните лицензию, разрешение правообладателя или допустимый внутренний сценарий. Не переходите к OCR и генерации Skill.
[ ] Определены одна-две конкретные задачи агента.
Если да, выбирайте узкий Skill по релевантным главам. Если нет, сначала сформулируйте входные данные, ожидаемый результат и критерии успеха; цель «знать всю книгу» недостаточна.
[ ] Агенту нужно выполнять последовательный анализ или проверку.
Если да, помещайте триггеры, алгоритм и формат результата в SKILL.md, а подробные объяснения и исключения — в references. Если нет и нужны только ответы по фактам, начните с references и карты источников.
[ ] В книге есть сканы, код, таблицы или схемы.
Если да, добавьте OCR и ручную сверку выборки до суммирования. Если нет, всё равно проверьте заголовки, переносы и координаты страниц перед созданием карточек.
[ ] Операция повторяется механически и имеет проверяемый результат.
Если да, выносите её в scripts: например, проверку поля page или наличие ссылки на источник. Если операция требует смысловой оценки, оставляйте её инструкцией для агента.
[ ] Материал обновляется или используется командой.
Если да, храните редакцию, дату проверки, владельца обновлений и приёмочный набор задач. Если нет, зафиксируйте хотя бы версию исходного файла, чтобы позже отличить изменение книги от ошибки Skill.
[ ] Каждый критический тезис имеет координату источника.
Если да, переходите к тестированию. Если нет, вернитесь к извлечению и разметке; Skill без трассируемости нельзя считать готовым.
[ ] Skill проходит прямые, связанные, граничные и неподходящие тесты.
Если да, его можно передавать в рабочий процесс с ограниченным применением. Если нет, не расширяйте набор материалов: сначала исправьте потерянные условия, слишком широкое описание или неверную навигацию.

Итоговая развилка выглядит так: подтверждены права и задача — создавайте узкий Skill; нужны только справочные ответы — начинайте с references; нужны повторяемые проверки — добавляйте scripts; есть сомнения в источнике или условиях — останавливайтесь и выполняйте ручную сверку.

Практический сценарий внедрения

Представьте, что у вас есть легально приобретённое руководство по проектированию распределённых систем, а цель — помогать команде проверять технические решения.

Сначала вы оставляете главы о согласованности, отказоустойчивости и наблюдаемости. Затем извлекаете заголовки, страницы, схемы и примеры кода, помечая места с неуверенным OCR. После этого создаёте карточки: «принцип», «условие», «контрпример» и «проверка».

В SKILL.md помещаете алгоритм ревью: определить тип системы, запросить ограничения, выбрать релевантные разделы, проверить решение по условиям и выдать замечания с координатами источника. В references оставляете подробные объяснения и карту глав. В scripts добавляете проверку, что каждое замечание содержит ссылку на исходный фрагмент.

На приёмке одна задача просит оценить кэширование, другая связывает кэширование с отказом хранилища, третья специально нарушает условие применимости. Если агент одинаково уверенно рекомендует один подход во всех трёх случаях, проблема находится не в объёме книги, а в недостаточно выраженных ограничениях Skill.

Частые ошибки при подготовке

Один огромный файл вместо слоёв. Агент получает чрезмерный контекст, а навигация становится непрозрачной.
Суммирование без координат. После ошибки нельзя быстро установить, где исказился исходный тезис.
Удаление исключений ради краткости. Краткий текст выглядит аккуратно, но становится опаснее для практического применения.
Смешение книги и общего знания модели. Пользователь не понимает, что подтверждено источником, а что добавлено извне.
Проверка только прямых вопросов. Такой тест не показывает, умеет ли Skill работать с конфликтующими условиями.
Копирование больших фрагментов. Это ухудшает качество Skill и создаёт отдельные риски, связанные с распространением защищённого материала.

Для командного процесса полезно хранить исходную редакцию, промежуточные карточки, итоговые файлы и отчёт о тестах раздельно. Тогда обновление книги не превращается в ручную переделку всего Skill.