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
npx skills add scaccogatto/okf-skills --skill validate -a claude-codeЧто делает 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-code2Вручную: положить файлы
~/.claude/skills/validate/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/validate/
1Через Skills CLI (Vercel)
npx skills add scaccogatto/okf-skills --skill validate -a codex2Вручную: положить файлы
.agents/skills/validate/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add scaccogatto/okf-skills --skill validate -a cursor2Вручную: положить файлы
.cursor/skills/validate/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install scaccogatto/okf-skills skills/validate2Вручную: положить файлы
.github/skills/validate/SKILL.md1Через Skills CLI (Vercel)
npx skills add scaccogatto/okf-skills --skill validate -a gemini-cli2Командой платформы
gemini skills install https://github.com/scaccogatto/okf-skills --path skills/validateВручную: положить файлы
.devin/skills/validate/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Через Skills CLI (Vercel)
npx skills add scaccogatto/okf-skills --skill validate -a opencodeClaude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в 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 от других авторов.