okf:validate

Files (1)

• SKILL.md

SKILL.md (first lines)

You are validating an OKF (Open Knowledge Format) bundle for conformance.

## 1. Setup

Determine the bundle root:
- If `$ARGUMENTS` contains a path, use it as the bundle root.
- Otherwise use the current working directory.

Find the OKF specification:
- Look for `SPEC.md` at the bundle root.
- If not found, search parent directories up to the filesystem root.
- If still not found, fetch it from the upstream repository:
  `https://raw.githubusercontent.com/GoogleCloudPlatform/knowledge-catalog/main/okf/SPEC.md`
- Extract the conformance rules from the "Conformance" section of that file (match sections by title, not by number, since numbering changes between spec versions). This ensures validation always reflects the current version of the spec, not hardcoded rules.

If `SPEC.md` cannot be found or fetched, report the error and stop.

## 2. Scan the bundle

Collect all `.md` files in the bundle tree recursively. Classify each as:
- **Reserved**: filename is `index.md` or `log.md` (at any level).
- **Infrastructure**: `README.md` or `SPEC.md` located directly at the bundle root, or any file inside a hidden directory (path component starting with `.`, e.g. `.claude/`). These are not OKF concept files and must be silently skipped — do not validate them and do not report them as errors.
- **Concept**: all other `.md` files.

## 3. Hard conformance checks (errors — make the bundle non-conformant per the "Conformance" section)

For each **concept** file:
- [ ] File contains a valid YAML frontmatter block delimited by `---`.
- [ ] Frontmatter contains a non-empty `type` field.

For each **`index.md`**:
- [ ] Contains no frontmatter, EXCEPT the bundle-root `index.md` which MAY have frontmatter containing `okf_version`.
- [ ] Body uses the list format described in the "Index files" section (headings + bullet list of links).

For each **`log.md`**:
- [ ] Date headings are in ISO 8601 `YYYY-MM-DD` format as described in the "Log files" section.

## 4. Soft checks (warnings — spec guidance, not hard requirements)

For each concept file:
- [ ] Has a `title` field (recommended).
- [ ] Has a `description` field (recommended).
- [ ] `timestamp`, if present, is a valid ISO 8601 datetime.
- [ ] Cross-links to other `.md` files within the bundle resolve to existing files.

For each directory:
- [ ] An `index.md` exists (not required, but recommended).
- [ ] All concept files in the directory are listed in the local `index.md`, when one exists.

## 5. Report

Print the report in this exact format:

```
OKF Validation Report
─────────────────────────────────────────
Bundle : <absolute bundle root path>
Spec   : OKF <version from SPEC.md, e.g. 0.1>
Scanned: <N> concept files, <M> reserved files

ERRORS (<count>)
  path/to/file.md — Missing frontmatter
  path/to/file.md — Missing required field: type
  path/to/index.md — Frontmatter present on non-root index

WARNINGS (<count>)
  path/to/file.md — Missing recommended field: title
  path/to/file.md — Broken link → ./missing.md
  tables/ — index.md missing entries for: orders.md, customers.md

RESULT: ✓ Conformant   (or)   ✗ Not conformant — <N> error(s)
Skill version : 1.0
```

## 6. Offer to fix

After reporting:
- If there are **errors**: ask the user whether to fix them automatically (add missing frontmatter skeleton with a placeholder `type: Unknown`, fix malformed date headings in log.md, etc.). Apply fixes only with user approval.
- If there are only **warnings**: offer to auto-fix safe ones (add missing `index.md` entries, sort log entries by date descending). Apply only with user approval.
- If the bundle has a git repository at its root, after any fixes offer to stage and commit the changes with a message like `fix: OKF conformance corrections (okf:validate)`.

## 7. Write invocation log

Follow `okf:_okf-skill-write-log` with:
- `skill`: `okf:validate`, `version`: `1.0`
- `bundle`: absolute path to the bundle root validated
- `outcome`: `success`
- `concepts_added`: `null`
- `concepts_updated`: `null`
- `concepts_split`: `null`
- `conflicts`: `null`
- `note`: `"Conformant"` if the bundle passed all hard checks; `"Not conformant — <N> error(s)"` otherwise

From siculo/okf-skills, Unlicense.

More from siculo/okf-skills