Output Schema

Готовый навык создаётся как обычный Claude Code skill:

dist/<skill-name>/
├── SKILL.md
└── references/
    ├── concepts.md
    ├── decision-rules.md
    ├── playbooks.md
    ├── anti-patterns.md
    ├── glossary.md
    ├── source-map.json
    ├── source-index.md
    └── knowledge-manifest.json

SKILL.md

Главный файл должен быть коротким рабочим протоколом:

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

Не превращай SKILL.md в пересказ книги. Главные детали живут в references/.

Тезисы и ссылки

Каждый тезис из source-map.json имеет уникальный claim_id: строчные латинские буквы и цифры, слова разделены одиночными дефисами, например concept-event-sourcing. Точные имена вида seg-<число> зарезервированы для сегментов и не подходят для тезисов. В файле, указанном в artifact, должен быть ровно один заголовок второго уровня ## <claim_id> вне блоков кода и HTML-комментариев. Другие заголовки не должны давать тот же якорь: например, # Concept Event Sourcing конфликтует с ## concept-event-sourcing. Отдельные поля для заголовка и якоря не нужны.

Явные HTML-якоря (id у элементов и name у <a>) в том же файле также не должны совпадать с claim_id. Сравниваются точные значения с учётом регистра; такие якоря не меняют автоматические суффиксы заголовков.

Предпочитай кликабельный источник: в файлах непосредственно внутри references/ это [seg-001](source-index.md#seg-001), из SKILL.md — [seg-001](references/source-index.md#seg-001). Для вложенных файлов подстрой относительный путь. Если ссылка содержит отдельный идентификатор seg-<число> в тексте или якоре, она должна вести в references/source-index.md этого навыка, к существующему сегменту с тем же номером. Внешний адрес, другой файл или другой номер не подходят.

Идентификатор сегмента распознаётся отдельно от соседних букв, цифр, _ и -, а не как подстрока другого имени. Например, concept-seg-001 — допустимый claim_id, и ссылка [Тезис](concepts.md#concept-seg-001) не является ссылкой на сегмент. Но явная подпись seg-001 требует точного якоря #seg-001, даже если адрес содержит другое составное имя. Проверка произвольных ссылок между документами в этот контракт не входит.

Простые указатели Источник: seg-001 также допустимы: номер должен существовать в карте источников, а перейти к нему можно через указатель. Превращать все упоминания в гиперссылки не обязательно.

Происхождение тезиса задаёт source_segments в карте; указатель строит обратные ссылки только из этого списка. Повторять все источники в тексте карточки не обязательно, а ссылка для сравнения или пояснения не становится источником тезиса автоматически. Явные подписи «Источник» согласуй с картой при компиляции. Скрипт проверяет существование сегментов и назначение ссылок, но не определяет роль каждого упоминания в тексте и не сверяет множество упоминаний раздела с source_segments.

concepts.md

Карточки понятий:

## concept-id

**Смысл:** одно-два предложения.
**Когда применять:** ситуации.
**Как распознать:** признаки в задаче пользователя.
**Связано:** другие concept-id.
**Источник:** [seg-001](source-index.md#seg-001).

decision-rules.md

Правила принятия решений:

## rule-id

Если <условие>, то <действие>, потому что <принцип>.

- Проверь: контрольные вопросы.
- Не делай: типовая ошибка.
- Источник: [seg-001](source-index.md#seg-001).

playbooks.md

Плейбук — прикладной сценарий, который можно выполнить:

## playbook-id

**Задача:** где помогает.
**Шаги:** 3-7 действий.
**Выход:** что должно получиться.
**Контроль качества:** как понять, что сработало.
**Источник:** [seg-001](source-index.md#seg-001).

source-map.json

Минимальная схема:

{
  "source_id": "sha256:<hash>",
  "segments": [
    {
      "segment_id": "seg-001",
      "title": "Глава 1",
      "char_start": 0,
      "char_end": 12000,
      "line_start": 1,
      "line_end": 340,
      "confidence": 0.82
    }
  ],
  "claims": [
    {
      "claim_id": "concept-event-sourcing",
      "artifact": "references/concepts.md",
      "source_segments": ["seg-001"],
      "extraction_type": "synthesized",
      "verbatim_quote_words": 0,
      "confidence": 0.86
    }
  ]
}

segments, claims и source_segments — непустые списки. segment_id имеет вид seg-<число> и уникален. source_segments содержит ссылки на существующие сегменты. artifact — относительный путь к существующему Markdown-файлу внутри references/, кроме производного source-index.md и других имён, ведущих к тому же файлу. Регистр расширения .md при проверке файлов не учитывается; сам путь сохраняется без изменений. Для примера выше в references/concepts.md нужен заголовок ## concept-event-sourcing.

source_id обязателен: строка sha256: и 64 строчных шестнадцатеричных символа. Он должен совпадать с source_sha256 в объекте knowledge-manifest.json. Заготовка копирует в оба поля хеш байтов исходного PDF/EPUB/TXT/Markdown из метаданных извлечения, а не хеш полученного source.txt.

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

У сегмента обязательны непустое название в корректном UTF-8, целочисленные координаты и confidence от 0 до 1. Символы считаются с 0, диапазон [char_start, char_end) непустой; строки — с 1, обе границы включены. Уверенность сегмента описывает разметку, а не достоверность связанных тезисов.

Диапазоны не должны выходить за пределы source.txt. Символы считаются в декодированном UTF-8 тексте, не в байтах; CRLF/CR при чтении приводятся к LF, как в сегментаторе. Число строк определяется через splitlines(): завершающий перенос не создаёт дополнительную строку, разделитель страниц \f учитывается.

Координаты должны согласовываться: line_start — строка символа char_start, line_end — строка последнего включённого символа char_end - 1. Разделитель строки относится к завершаемой строке. Проверка использует тот же расчёт, что и segment_text.py.

У каждого тезиса обязательны extraction_type, verbatim_quote_words и confidence. Число дословно процитированных слов — целое, неотрицательное; уверенность — число от 0 до 1 включительно. Логические значения вместо чисел не допускаются. Проверка контролирует эти поля, но не определяет фактическую достоверность тезиса и не пересчитывает цитаты.

Допустимые значения extraction_type:

synthesized — переработанная идея;
named-framework — сохранено авторское название метода;
short-quote — короткая цитата, если она действительно нужна;
inferred — вывод агента на основе нескольких мест источника.

source-index.md

Указатель генерирует quality_gate.py --write-source-index из заполненного source-map.json после успешных проверок. Заготовка навыка его не создаёт; вручную указатель не редактируй.

Сам путь указателя не должен быть символической ссылкой, а его файл не должен иметь жёстких ссылок под другими именами: это защищает самостоятельные документы от перезаписи. Дополнительные символические ссылки на указатель сами по себе не запрещены, но не могут использоваться в artifact тезиса; их содержимое проверяется по общим правилам Markdown.

Для каждого сегмента он содержит якорь seg-*, название, диапазоны строк и символов, уверенность и относительные ссылки на связанные тезисы в готовом навыке. Координаты относятся к извлечённому source.txt, а не к страницам PDF. Исходный текст, фрагменты источника и абсолютные локальные пути в указатель не входят; сам источник остаётся в кеше сборки.

knowledge-manifest.json

Фиксирует происхождение:

{
  "title": "Название",
  "author": "Автор",
  "scope": "individual",
  "source_file": "/path/to/file.pdf",
  "source_sha256": "sha256:...",
  "extraction_method": "pdftotext",
  "epub_title": "Название из OPF, если есть",
  "epub_author": "Автор из OPF, если есть",
  "epub_toc_source": "ncx",
  "created_at": "2026-05-07T12:00:00Z",
  "limitations": ["OCR not performed"]
}

/knowledge-compiler

referencesOUTPUT_SCHEMA.md