Markdown file directory as Open Knowledge Format (OKF)
A general-purpose skill maintained as a bundle.frontmatter is the single source of truth (SSoT) and
index.md and human-facing tables are treated as derivatives generated from frontmatter.
Project-independent, stdlib only.--bundle-root receives the target directory, so it can be used for any OKF bundle such as ADRs, knowledge bases, and glossaries.
Target: all development documentation that agents read
It is not limited to ADRs or glossaries.Development documentation written on the premise that agents will read it later is recorded using this method regardless of type. Examples of targets:
| Type | type examples |
Typical location |
|---|---|---|
| Design decisions | ADR |
docs/decisions/ |
| Design documents / specifications | Design, Spec |
docs/design/, docs/specs/ |
| Implementation plans / task breakdowns | Plan |
docs/plans/ |
| Investigation notes / verification records | Investigation, Experiment |
docs/investigations/ |
| Procedures | Runbook, Guide |
docs/ |
| Reference materials / lists | Reference |
docs/ |
| Lessons learned / bug patterns | Lesson |
docs/lessons-learned/ |
| Glossaries / concepts | Concept, Glossary |
docs/knowledge/ |
type vocabulary may be fixed per project, butthere is no option to not add frontmatter to new documents.
Excluded are README (human-facing entry point),CLAUDE.md / AGENTS.md (guideline layer), generated artifacts (index.md , etc.), and code comments.
Recommended keys to place in frontmatter:
---
type: Investigation
title: 短い題名
description: 一文の要約 (索引にそのまま出る)
timestamp: 2026-01-01 # ISO 8601。最終更新日
status: draft | active | superseded # 状態はここ。本文の散文に書かない
tags: [hooks, uv]
---
When creating a new document, write the frontmatter before the body. If you make major edits to an existing document, update timestamp .
OKF mandatory rules (SPEC v0.1)
- The mandatory keys of frontmatter are
typeonly。title/description/tags/timestampis optional. - Scalar value metadata (status / timestamp, etc.) is placed in frontmatter. Do not write it in the prose of the body.
index.md/log.mdis a reserved filename. Do not use it for concept documents.log.mddates are ISO 8601.index.md/ generated tables aregenerated artifacts. Do not edit them by hand.
Scripts (scripts/)
all python3 runs standalone (no dependencies).
| scripts | Role |
|---|---|
okf_validate.py --bundle-root DIR |
frontmatter validation (mandatory type / ISO timestamp / --require・--exclude・--skip-missing allowed) |
okf_index.py --bundle-root DIR --index |
OKF index.md (bullet list) is generated |
okf_index.py --bundle-root DIR --table --columns ... --link-column ... |
Generates a Markdown table whose columns are specified by frontmatter keys |
okf_index.py の --check does not write, and only verifies whether the generated artifacts are up to date (drift detection).
--table-output If there is a <!-- OKF-TABLE:START --> / <!-- OKF-TABLE:END --> marker first, only that section is replaced, so the prose before and after the table can be preserved.
okf_validate.py --skip-missing does not treat files without frontmatter as violations and excludes them (for gradual migration / lazy migration). Use it for bundles where you want to allow existing documents without frontmatter while enforcing type mandatory / ISO timestamp only for those that already have it.
Do not add it to bundles where frontmatter is mandatory for all entries (e.g., ADRs).
Workflow (started at the agent's discretion)
When you add, edit, or renumber a target document:
- Validation:
python3 <skill>/scripts/okf_validate.py --bundle-root <DIR> [--exclude README.md]— fill in missing frontmatter and missing mandatory keys. - Regenerate:
python3 <skill>/scripts/okf_index.py --bundle-root <DIR> --index ...(if necessary,--table ...as well) to update the derived views. - commit: Commit including the generated artifacts (some projects allow direct pushes of docs chores to main).
Do not rely on CI running automatically; proceed based on the Agent's judgment. The only thing tolerated is "missed execution (the index is temporarily stale)"; since generation is deterministic, no content drift occurs.Do not hand-write indexes or tables (a breeding ground for formatting inconsistencies and transcription errors).
Project-specific responsibilities (outside the skill)
Drift detection of the "code referencing a concept is newer than the concept" kind (REFERENCE-DRIFT) depends on each project's enactment surface, so it is not included in this skill. It is handled by project-side dedicated tools (e.g., a drift checker that verifies consistency between ADRs and source code).
Usage examples
# ADR バンドル検証 (全件 frontmatter 必須)
python3 <skill-dir>/scripts/okf_validate.py --bundle-root docs/decisions --exclude README.md
# index.md + README テーブルを再生成
make adr-index # 内部で okf_index.py を呼ぶ (Makefile target がある場合)
# 通常ドキュメント検証 (lazy migration: 未付与は skip、付与済みのみ検証)
python3 <skill-dir>/scripts/okf_validate.py --bundle-root docs --skip-missing