From fa0776efaef736f7dc38c001ea41627d035970ce Mon Sep 17 00:00:00 2001 From: duyetbot Date: Sun, 14 Jun 2026 13:55:01 +0700 Subject: [PATCH] fix(okf): satisfy super-linter markdown rules - MD034: wrap bare source URL in angle brackets (SPEC.md) - MD040: add language to two directory-tree fences (text) (SPEC.md) - MARKDOWN_PRETTIER: apply prettier formatting to SKILL.md and SPEC.md Co-Authored-By: duyetbot --- okf/skills/okf/SKILL.md | 36 +++++++++++++------------ okf/skills/okf/reference/SPEC.md | 45 +++++++++++++++++--------------- 2 files changed, 43 insertions(+), 38 deletions(-) diff --git a/okf/skills/okf/SKILL.md b/okf/skills/okf/SKILL.md index 1f9bc51..689bfe5 100644 --- a/okf/skills/okf/SKILL.md +++ b/okf/skills/okf/SKILL.md @@ -58,8 +58,8 @@ When asked to init/scaffold an OKF bundle at ``: # - * [Datasets](datasets/) - - * [Tables](tables/) - + - [Datasets](datasets/) - + - [Tables](tables/) - ``` 4. Add a `references/` directory only if you expect standalone citation docs. @@ -73,28 +73,29 @@ asset name where possible. ```markdown --- -type: # REQUIRED — e.g. "BigQuery Table", "API Endpoint", "Playbook" -title: # strongly recommended -description: # strongly recommended — used in indexes/previews -resource: # for assets that have one -tags: [, ] # optional, cross-cutting -timestamp: # optional, last meaningful change +type: # REQUIRED — e.g. "BigQuery Table", "API Endpoint", "Playbook" +title: # strongly recommended +description: # strongly recommended — used in indexes/previews +resource: # for assets that have one +tags: [, ] # optional, cross-cutting +timestamp: # optional, last meaningful change --- -# Schema (when the concept has structured fields — prefer a table) +# Schema (when the concept has structured fields — prefer a table) -| Column | Type | Description | -|--------|------|-------------| +| Column | Type | Description | +| ------ | ---- | ------------------------------ | | ... | ... | FK to [other](/group/other.md) | -# Examples (concrete usage in code blocks) +# Examples (concrete usage in code blocks) -# Citations (external sources) +# Citations (external sources) [1] [Title](https://example.com) ``` Guidance: + - Prefer structural markdown (tables, lists, code blocks) over prose paragraphs. - Express relationships by **linking** related concepts inline in the prose; the link is an undirected edge in the knowledge graph. @@ -109,8 +110,8 @@ pull each bullet's description from the linked concept's `description`: ```markdown # Tables -* [Orders](orders.md) - one row per completed customer order -* [Customers](customers.md) - one row per customer +- [Orders](orders.md) - one row per completed customer order +- [Customers](customers.md) - one row per customer ``` Use relative links inside an index (they sit beside their targets). Regenerate the @@ -124,7 +125,8 @@ Append directory-level history, newest first, ISO dates: # Directory Update Log ## 2026-06-14 -* **Creation**: Added orders and customers tables. + +- **Creation**: Added orders and customers tables. ``` ## Validate a bundle for OKF v0.1 conformance @@ -136,7 +138,7 @@ check, then eyeball the report. It verifies: - `index.md` / `log.md` carry no frontmatter (root `index.md` may carry only `okf_version`). - Reports broken bundle-relative cross-links as warnings (broken links are - *tolerated* by the spec — surface them, don't fail on them). + _tolerated_ by the spec — surface them, don't fail on them). ```bash python3 ${CLAUDE_PLUGIN_ROOT}/skills/okf/scripts/validate_okf.py ./bundles/my_bundle diff --git a/okf/skills/okf/reference/SPEC.md b/okf/skills/okf/reference/SPEC.md index 264a8f7..79218c4 100644 --- a/okf/skills/okf/reference/SPEC.md +++ b/okf/skills/okf/reference/SPEC.md @@ -6,7 +6,7 @@ > anyone can consume it (file servers, Obsidian/Notion/MkDocs, LLMs, search > indexes, graph viewers). > -> Source: https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md +> Source: ## Core principles @@ -26,7 +26,7 @@ A knowledge bundle is a hierarchical directory of markdown files: -``` +```text bundle_root/ ├── index.md (optional; only place frontmatter is allowed in an index) ├── log.md (optional) @@ -38,6 +38,7 @@ bundle_root/ ``` **Reserved filenames:** + - `index.md` — progressive-disclosure directory listings. - `log.md` — chronological update history. @@ -51,12 +52,12 @@ Two sections: required YAML frontmatter, then a markdown body. ```yaml --- -type: # REQUIRED — non-empty string -title: # Recommended -description: # Recommended -resource: # Recommended for assets -tags: [, ] # Optional -timestamp: # Optional +type: # REQUIRED — non-empty string +title: # Recommended +description: # Recommended +resource: # Recommended for assets +tags: [, ] # Optional +timestamp: # Optional # Producers may add arbitrary custom keys. --- ``` @@ -78,11 +79,11 @@ on round-trips. Standard markdown. Conventional section headings (prefer structural markdown — tables, lists, code blocks — over prose): -| Section | Purpose | -|---------------|-----------------------------------------------| -| `# Schema` | Structured description of columns/fields. | -| `# Examples` | Concrete usage examples in code blocks. | -| `# Citations` | External sources supporting claims. | +| Section | Purpose | +| ------------- | ----------------------------------------- | +| `# Schema` | Structured description of columns/fields. | +| `# Examples` | Concrete usage examples in code blocks. | +| `# Citations` | External sources supporting claims. | ## Cross-linking @@ -102,12 +103,12 @@ Optional, support progressive disclosure. Sections group concepts. No frontmatte ```markdown # Section Heading -* [Title](relative-url) - description from the linked concept -* [Subdirectory](subdir/) - group description +- [Title](relative-url) - description from the linked concept +- [Subdirectory](subdir/) - group description # Another Section -* [Title](url) - description +- [Title](url) - description ``` Producers may generate them automatically; consumers may synthesize dynamically. @@ -121,11 +122,13 @@ Date headings must use ISO 8601 `YYYY-MM-DD`. Leading bold words are conventiona # Directory Update Log ## 2026-05-22 -* **Update**: Description of change -* **Creation**: Description of new content + +- **Update**: Description of change +- **Creation**: Description of new content ## 2026-05-15 -* **Initialization**: Foundational changes + +- **Initialization**: Foundational changes ``` ## Citations @@ -166,7 +169,7 @@ Best-effort consumption is preferred over rejection. ## Minimal example -``` +```text my_bundle/ ├── index.md ├── datasets/ @@ -209,7 +212,7 @@ timestamp: 2026-05-28T00:00:00Z # Schema | Column | Type | Description | -|---------------|---------|------------------------------------------| +| ------------- | ------- | ---------------------------------------- | | `order_id` | STRING | Unique order identifier. | | `customer_id` | STRING | FK to [customers](/tables/customers.md). | | `total_usd` | NUMERIC | Order total in USD. |