用途
validate 用于对 Open Knowledge Format（OKF）包运行确定性的一致性校验，判断其是否符合 OKF v0.2 规范（§11）。适用于需要验证、lint 或检查 OKF 包的场景，也可在提交或发布前作为检查环节。未指定路径时，默认检查项目的 .okf/ 目录。
主要能力
- 对目标 OKF 包运行确定性一致性检查，输出 ERROR 与 warn 两类结果。
- ERROR 代表硬性违反 §11 一致性要求，包括：没有可解析的 frontmatter、type 缺失或为空、文件无法按 UTF-8 读取。出现 ERROR 即表示该包不符合规范，需逐一修复。
- warn 代表软性提示，涉及：缺少推荐字段、日志日期非 ISO 格式、交叉链接失效、v0.2 系列格式错误、脚注未指名来源、actor 不符合 §7 形态、Attested Computation 缺少 runtime、计算路径无法解析、保留文件中出现 frontmatter（§8、§9）、根 index.md 携带额外键或声明了不同的 okf_version（§12）。警告从不阻断校验。
- 保留文件规则：只有 index.md 与 log.md 是保留文件；§11.1 规定目录树中其他所有 .md 文件都是 concept，包括约定文件。因此放在包旁边的 AGENTS.md 或 README.md 会产生 ERROR，除非其携带带 type 的 frontmatter（Document 即可），这就是修复方式；使用跳过列表会让检查器不符合规范。若该文件不属于知识内容，应将其移到包根目录之上。
- 特别提醒：§7 近似错误（如 Human:dana 或 human/dana）值得优先修复。§5.3 依据精确的小写 human: 前缀判定信任层级，写错会导致该 concept 在人工审阅的情况下被静默读作机器确认。
- v0.1 包同样可校验：遗留 timestamp 或 # Citations 段会以警告形式报告，并指出其在 v0.2 中的替代（generated.at、sources），而不会报错（§13.1）。在 --strict 下这些警告会导致运行失败，这是迁移提示；--migrate 是迁移入口。
使用方式
默认运行：
uv run "${CLAUDE_SKILL_DIR}/scripts/okf_validate.py" $ARGUMENTS
若 uv 不可用，可改用：
python3 -m pip install --quiet pyyaml &&
python3 "${CLAUDE_SKILL_DIR}/scripts/okf_validate.py" $ARGUMENTS
${CLAUDE_SKILL_DIR} 无论该技能是作为 okf 插件的一部分运行，还是独立安装（例如通过 npx skills add），都会解析到正确位置，因此检查器始终与该技能放在一起。
解读结果：
- ERROR → §11 硬性一致性失败，包不符合规范，需全部修复。
- warn → 软性指引，不阻断；尤其是失效链接，规范（§6.1）明确容忍。修复成本低时建议修复。
退出码：只要存在任何 ERROR，或警告数超过门槛，退出码即非零。--strict 不允许任何警告，--max-warnings N 允许 N 个警告，默认允许任意数量。添加 --json 可获得机器可读输出（适用于 CI）。
迁移 v0.1 包
--migrate 会在校验前就地重写包，这是该技能唯一非只读的模式。因此对用户未要求迁移的包运行前，应先说明它将改动哪些内容。该迁移是文本性的（注释、键顺序和引号都会保留），并且是幂等的。
uv run "${CLAUDE_SKILL_DIR}/scripts/okf_validate.py" .okf --migrate --strict
迁移会：将 timestamp 提升为 generated: { by: process:okf-migrate, at }；把 # Citations 列表提升为 sources；并提升 okf_version。有两点限制值得向用户重申：对于 v0.2 之前的内容，generated.by 无法恢复（因此使用 process: actor，该 concept 在 §5.3 下保持正确地未验证状态）；逐条 [^id] 归属在 v0.1 中从未被编码，因此只有来源列表会被提升。
适用场景
- 在修改或提交 OKF 包前做一致性把关。
- 在 CI 中通过 --json 与退出码进行自动化校验。
- 将旧版 v0.1 包迁移到 v0.2 规范。
限制
- 校验结果分为 ERROR 与 warn 两类，warn 不阻断校验。
- --migrate 是唯一会修改文件的模式，运行前需明确告知用户改动范围。
- v0.2 之前内容的 generated.by 无法恢复；v0.1 中的逐条归属未被编码，迁移仅提升来源列表。
- 本资料未提供收费、价格、平台支持范围等其他信息。