validate · scaccogatto — Claude Code skill: OKF bundle conformance checks
The validate skill checks Open Knowledge Format bundles against the v0.2 spec with a deterministic Python checker. Run it before commits; it also migrates v0.1 bundles in place.
MIT 1,000 installs ★ 455 updated 2026-10-21
npx skills add scaccogatto/okf-skills --skill validate -a claude-codeWhat validate does
The skill runs okf_validate.py over an OKF bundle and reports conformance against §11 of the v0.2 spec. Hard failures cover three cases: frontmatter that will not parse, a missing or empty type, or a file that cannot be read as UTF-8. Every error means the bundle is non-conformant and needs a fix before commit.
Warnings are softer. A missing recommended field, a non-ISO date in the log, a broken cross-link, a malformed family, a footnote that names no source. The spec tolerates broken links in §6.1, so warnings never block the run by default. One warning deserves attention: a near-miss actor like Human:dana or human/dana. Trust tiers key off the exact lowercase human: prefix per §5.3, so that concept silently reads as machine-confirmed. Fix it when you see it.
The only mode that writes is --migrate. It rewrites the bundle in place: timestamp becomes generated: { by: process:okf-migrate, at }, a # Citations list moves into sources, and okf_version is bumped. The rewrite is textual and idempotent, comments and key order survive. generated.by cannot be recovered for pre-v0.2 content, hence the process: actor. You need uv, or the script falls back to installing pyyaml via pip and running on python3.
What it helps with
- run a deterministic checker instead of eyeballing the bundle
- catch stray
.mdfiles without atypein frontmatter before they land in a commit - spot near-miss actor prefixes like
Human:danathat break trust tiers - migrate a v0.1 bundle to v0.2 in place with one flag
- emit
--jsonoutput for CI checks
Example prompts for the agent
- Validate the bundle in
.okf/against the v0.2 spec - Run the checker before commit and show errors only
- Run with
--strictso warnings fail the build
How to install validate
1Skills CLI (Vercel)
npx skills add scaccogatto/okf-skills --skill validate -a claude-code2Manually: put the files in place
~/.claude/skills/validate/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/validate/
1Skills CLI (Vercel)
npx skills add scaccogatto/okf-skills --skill validate -a codex2Manually: put the files in place
.agents/skills/validate/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add scaccogatto/okf-skills --skill validate -a cursor2Manually: put the files in place
.cursor/skills/validate/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install scaccogatto/okf-skills skills/validate2Manually: put the files in place
.github/skills/validate/SKILL.md1Skills CLI (Vercel)
npx skills add scaccogatto/okf-skills --skill validate -a gemini-cli2Platform CLI
gemini skills install https://github.com/scaccogatto/okf-skills --path skills/validateManually: put the files in place
.devin/skills/validate/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add scaccogatto/okf-skills --skill validate -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about validate
How do I install validate in Claude Code?
Run npx skills add scaccogatto/okf-skills --skill validate -a claude-code. The skill lands in ~/.claude/skills/validate/SKILL.md.
What counts as an error versus a warning?
Errors are unparseable frontmatter, a missing or empty type, or a file not readable as UTF-8. Warnings cover missing recommended fields, non-ISO dates, broken links, and malformed families. Errors block; warnings do not by default.
What does --migrate change in a v0.1 bundle?
It rewrites files in place: timestamp moves to generated.at, a # Citations section becomes sources, and the version bumps to v0.2. generated.by stays unrecoverable, so the actor is set to process:okf-migrate.
Source text
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
Similar skills
All skills for Agent setup: memory, context, orchestration →validate by other authors comes first.