Validate Agent Skill

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.

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

If uv is unavailable, fall back to:

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, or a

missing/empty type). The bundle is non-conformant. Fix every one.

• 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, a computation path that resolves nowhere). 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.

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).