К основному содержанию
скилл CX Codex

validate · scaccogatto — скилл для Claude Code: проверка OKF-бандлов по v0.2

Скилл validate детерминированно проверяет бандл Open Knowledge Format по спецификации v0.2 с помощью Python-чекера. Запускает проверку перед коммитом и мигрирует бандлы v0.1 в v0.2 на месте.

MIT 1 000 установок ★ 455 обновлён 2026-10-21

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add scaccogatto/okf-skills --skill validate -a claude-code
Открыть на GitHub

Что делает validate

Скилл прогоняет бандл OKF через Python-скрипт okf_validate.py, который сверяет структуру с разделом §11 спецификации v0.2. Ошибки — это жёсткие нарушения: фронтматтер не парсится, поле type пустое или файл не читается как UTF-8. Всё это нужно чинить до коммита.

Предупреждения мягче: пропущенное рекомендованное поле, не-ISO дата в логе, битая перекрёстная ссылка, кривой формат v0.2 family. По спецификации §6.1 сломанные ссылки терпимы, так что warn никогда не блокирует запуск. Но одно предупреждение важнее остальных — near-miss вида Human:dana или human/dana. Из-за §5.3 уровни доверия завязаны на точный префикс human:, поэтому такой концепт молча читается как подтверждённый машиной. Это стоит поправить сразу.

Единственный не read-only режим — --migrate. Он переписывает бандл на месте: поднимает timestamp в generated, список # Citations в sources, обновляет okf_version. Миграция текстовая, идемпотентная, комментарии и порядок ключей сохраняются. generated.by для контента до v0.2 восстановить нельзя, поэтому подставляется актор process:okf-migrate — концепт остаётся unverified. Для запуска нужен uv, иначе скрипт сам поставит pyyaml через pip и запустится на python3.

Какие задачи решает

  • прогнать бандл через детерминированный чекер вместо ручного просмотра
  • найти файлы .md без фронтматтера с type до того, как они попадут в коммит
  • отловить near-miss акторов вида Human:dana, которые ломают уровни доверия
  • мигрировать бандл v0.1 в v0.2 на месте без ручной правки файлов
  • получить машиночитаемый результат через --json для CI

Примеры запросов агенту

  • Проверь бандл в .okf/ на соответствие спецификации v0.2
  • Прогони валидацию перед коммитом и покажи только ошибки
  • Запусти проверку с --strict, чтобы предупреждения роняли сборку

Как установить validate

1Через Skills CLI (Vercel)

npx skills add scaccogatto/okf-skills --skill validate -a claude-code

2Вручную: положить файлы

~/.claude/skills/validate/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/validate/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о validate

Как установить validate в Claude Code?

Выполни npx skills add scaccogatto/okf-skills --skill validate -a claude-code. Скилл появится в ~/.claude/skills/validate/SKILL.md.

Что скилл считает ошибкой, а что предупреждением?

Ошибка — это нечитаемый фронтматтер, пустое поле type или файл не в UTF-8. Предупреждения — мягкие замечания: пропущенное поле, не-ISO дата, битая ссылка, кривой family. Ошибки блокируют, warn по умолчанию нет.

Что --migrate делает с бандлом v0.1?

Переписывает файлы на месте: timestamp переносится в generated.at, секция # Citations становится sources, версия поднимается до v0.2. generated.by восстановить нельзя, ставится актор process:okf-migrate.

Исходный текст

SKILL.md · MIT
---
name: validate
description: >-
  Check that an Open Knowledge Format (OKF) bundle is conformant with the v0.2
  spec (§11). Use when asked to validate, lint, or check an OKF bundle, or before
  committing changes to one. Runs a deterministic Python checker — not an
  eyeball pass. Also migrates a v0.1 bundle to v0.2 in place with `--migrate`.
user-invocable: true
argument-hint: "[bundle-dir] [--strict | --max-warnings N] [--migrate]"
allowed-tools: Bash
---

# Validate an OKF bundle

Run the deterministic conformance checker against the target bundle. Default to
the project's `.okf/` directory when no path is given.

```bash
uv run "${CLAUDE_SKILL_DIR}/scripts/okf_validate.py" $ARGUMENTS
```

If `uv` is unavailable, fall back to:

```bash
python3 -m pip install --quiet pyyaml && \
python3 "${CLAUDE_SKILL_DIR}/scripts/okf_validate.py" $ARGUMENTS
```

`${CLAUDE_SKILL_DIR}` resolves whether this skill runs as part of the `okf`
plugin or is installed standalone (e.g. via `npx skills add`), so the checker is
always found alongside the skill.

Interpret the result:

- **ERROR** → a hard §11 conformance failure (no parseable frontmatter, a
  missing/empty `type`, or a file the checker cannot read as UTF-8). The bundle
  is non-conformant. Fix every one.

Only `index.md` and `log.md` are reserved: §11.1 makes *every* other `.md` in
the tree a concept, convention files included. An `AGENTS.md` or `README.md`
dropped next to a bundle is therefore an ERROR until it carries frontmatter with
a `type` (`Document` reads well), which is the fix; a skip-list would put the
checker out of conformance. Move the file above the bundle root if it is not
knowledge.
- **warn** → soft guidance (missing recommended field, non-ISO log date, broken
  cross-link, a malformed v0.2 family, a footnote naming no source, an actor
  that misses the §7 shapes, an Attested Computation missing `runtime`, a
  computation path that resolves nowhere, frontmatter in a reserved file (§8,
  §9), a root `index.md` carrying extra keys or declaring a different
  `okf_version` (§12)). Never blocks; broken links in particular are explicitly
  tolerated by the spec (§6.1). Fix when cheap.

One warning is worth more than the others: a §7 near-miss such as `Human:dana`
or `human/dana`. §5.3 keys trust tiers off the exact lowercase `human:` prefix,
so the concept silently reads as machine-confirmed when a person did review it.
Fix that one on sight.

v0.1 bundles validate too: a legacy `timestamp` or `# Citations` section is
reported as a warning naming its v0.2 replacement (`generated.at`, `sources`),
never as an error (§13.1). Under `--strict` those warnings do fail the run —
that is the migration nudge, and `--migrate` is the door.

## Migrating a v0.1 bundle

`--migrate` **rewrites the bundle in place** before validating — the one mode of
this skill that is not read-only, so say what it will touch before running it on
a bundle the user has not asked to migrate. It is textual (comments, key order
and quoting survive) and idempotent.

```bash
uv run "${CLAUDE_SKILL_DIR}/scripts/okf_validate.py" .okf --migrate --strict
```

It hoists `timestamp` to `generated: { by: process:okf-migrate, at }`, lifts a
`# Citations` list into `sources`, and bumps `okf_version`. Two limits worth
repeating to the user: `generated.by` cannot be recovered for pre-v0.2 content
(hence the `process:` actor — the concept stays correctly `unverified` under
§5.3), and per-claim `[^id]` attribution was never encoded in v0.1, so only the
source list moves up.

## Exit codes

Non-zero if any error is present, or if warnings exceed the gate:
`--strict` allows none, `--max-warnings N` allows N, the default allows any.
Add `--json` for machine-readable output (useful in CI).

© scaccogatto · MIT · scaccogatto/okf-skills

Похожие скиллы

Все скиллы по теме «Настройка агента: память, контекст, субагенты» →

Сначала — validate от других авторов.

validate Rudolf S. Скилл validate запускает проверку спецификаций, кода, расхождений с реализацией и правил конституции проекта через специализированных субагентов. CX Codex +1 ★ 587звёзд репо validate yahor-punko Скилл validate запускает валидатор MavP для сверки BACKLOG.md и TASK_STATUS.md. Помогает убедиться в синхронности задач перед началом работы. CX Codex +1 ★ 121звёзд репо kb-lint stjbrown Скилл kb-lint проверяет базу знаний агента на соответствие спецификации и накопленные расхождения. Безопасные ошибки скилл исправляет сам. CX Codex +1 ★ 45звёзд репо arquiteto-de-empresa leoal Скилл arquiteto-de-empresa проводит основателя по 12 фазам интервью и складывает компанию в набор связанных markdown-файлов, которые читают и люди, и ИИ-агенты. CX Codex +1 51установок okf-answer wmahfoudh Скилл okf-answer для Claude Code отвечает на вопросы по наборам знаний Open Knowledge Format. Он также запускает вычисления из набора и сохраняет ответы по просьбе. CX Codex +1 ★ 105звёзд репо MCP Hook Conformance studiomeyer-io MCP-сервер MCP Hook Conformance для Claude Code, который проверяет готовность инструментов к вызовам из хуков жизненного цикла. Прогоняет тесты идемпотентности, латентности и побочных эффектов и выдаёт отчёт с кодами находок. CX Codex +1 migrate-validate ruvnet Скилл migrate-validate автоматически проверяет незавершённые миграции на ошибки: несуществующие внешние ключи, неполные откаты, нарушения соглашений об именовании. Ловит проблемы до того, как миграция попадёт в БД. CX Codex +1 729установок okf-produce wmahfoudh Скилл okf-produce для Claude Code собирает материал в бандл Open Knowledge Format (OKF) и описывает его источники. Запускается по просьбе создать или обновить базу знаний, даже без упоминания OKF. CX Codex +1 ★ 105звёзд репо

Из того же набора4

Спонсоры проекта

Компании, которые помогают держать аналитику открытой