Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add scaccogatto/okf-skills --skill validate -a claude-code
Open on GitHub

What 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 .md files without a type in frontmatter before they land in a commit
  • spot near-miss actor prefixes like Human:dana that break trust tiers
  • migrate a v0.1 bundle to v0.2 in place with one flag
  • emit --json output 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 --strict so warnings fail the build

How to install validate

1Skills CLI (Vercel)

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

2Manually: put the files in place

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

Copy the whole skill folder; for one project use .claude/skills/validate/

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.

validate Rudolf S. validate orchestrates spec reviews, file audits, spec-to-code drift detection, and constitution rule checks across specialist subagents. CX Codex +1 ★ 587repo stars validate yahor-punko validate runs the MavP validator to verify artifact synchronization between BACKLOG.md and TASK_STATUS.md before starting new tasks. CX Codex +1 ★ 121repo stars kb-lint stjbrown kb-lint audits an agent knowledge bundle for specification conformance and drift. Safely repairs minor link and metadata defects upon request. CX Codex +1 ★ 45repo stars arquiteto-de-empresa leoal arquiteto-de-empresa interviews a founder across 12 business phases and turns the answers into a linked markdown bundle that both people and AI agents can read. CX Codex +1 51installs okf-answer wmahfoudh The okf-answer Claude Code skill answers questions using Open Knowledge Format bundles. It can also run bundle computations and save answers on request. CX Codex +1 ★ 105repo stars MCP Hook Conformance studiomeyer-io MCP Hook Conformance — an MCP server for Claude Code that checks whether tools are safe to call from lifecycle hooks. It runs idempotency, latency and side-effect tests and prints a report with finding codes. CX Codex +1 migrate-validate ruvnet migrate-validate — a skill that automatically validates pending database migrations for errors: broken foreign key references, incomplete rollbacks, naming violations. Catches issues before they reach the database. CX Codex +1 729installs okf-produce wmahfoudh The okf-produce Claude Code skill turns readable source material into an Open Knowledge Format (OKF) bundle and records its context. It activates for requests to create or update a knowledge base, even when OKF is not named. CX Codex +1 ★ 105repo stars

From the same set4

Project sponsors

Companies that keep this analytics open