tim/SlipItIn
1
0
Fork 0
Code Pull Requests 1 Actions 1 Packages Releases Wiki Activity

Neue Skills, Referenzen & OpenWiki-Doku integriert

Browse Source 
Umfangreiche Erweiterung der Skill-Bibliothek: Neue Skills für Humanisierung (Englisch/PT-BR), Design-Validierung, AI-SEO und Coolify-Deployment inkl. Regelwerke, Presets, Pattern-Referenzen, Testfälle und Automatisierungsskripte. Zusätzliche Skills für Revenue-Centric Design, Pier Cloud, OKF, Lebenslauf- und LinkedIn-Optimierung sowie zahlreiche Referenzdateien, Checklisten und YAML/JSON/Markdown-Templates. Einführung einer vollständigen OpenWiki-Dokumentation mit Architektur-, Domain- und Workflow-Beschreibungen, zentralem Index und automatisierten Updates. Modularer Aufbau, restriktive Lizenzen und umfassende Qualitäts- und Evaluationsmechanismen für alle neuen Inhalte.
This commit is contained in:
Tim Krampitz
2026-07-26 14:00:58 +02:00
parent 070727d5cd
commit 01046b01e4
202 changed files with 31290 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

424
.github/skills/okf-open-knowledge-format/SKILL.md vendored Normal file
View File

@@ -0,0 +1,424 @@
---
name: okf-open-knowledge-format
description: >
Create, validate, and enrich Open Knowledge Format (OKF) bundles — the open
spec for representing organizational knowledge as markdown files with YAML
frontmatter. Use when the user mentions 'OKF', 'Open Knowledge Format',
'knowledge bundle', 'OKF bundle', 'create a knowledge base for agents',
'validate OKF', 'convert to OKF', 'enrich knowledge docs', 'agent-readable
knowledge', 'LLM wiki', 'knowledge catalog', 'kcmd', or wants to structure
knowledge as markdown files for AI agent consumption. Also use when the user
has a directory of markdown files and wants to make them interoperable or
conformant with the OKF standard. Even for simple requests like 'make this
folder OKF conformant' — the skill has critical structural rules the agent
needs.
metadata:
author: ft.ia.br
version: "1.1"
date: 2026-06-17
repository: https://github.com/fabricioctelles/skills
license: Apache-2.0
category: library-and-api-reference
---
# Open Knowledge Format (OKF)
OKF is a vendor-neutral, open spec (v0.1, announced June 12, 2026 by Sam McVeety & Amir Hormati at Google Cloud) for representing knowledge as a directory of markdown files with YAML frontmatter. No SDK required — if you can `cat` a file, you can read OKF.
It formalizes the "LLM Wiki" pattern ([Karpathy's gist](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)) into an interoperable format: wikis written by different producers can be consumed by different agents without translation.
For the full spec, see [references/spec-v01.md](references/spec-v01.md).
### Design Principles
1. **Minimally opinionated** — Only `type` is required. The spec defines interoperability surface, not content model.
2. **Producer/consumer independence** — Who writes and who reads are decoupled. Human-authored bundles feed agents; LLM-generated bundles are browsed by humans.
3. **Format, not platform** — No cloud, SDK, or vendor dependency. Value comes from how many parties speak it.
---
## Key Terminology
- **Bundle** — A directory tree of `.md` files. The unit of distribution (git repo, tarball, or subdirectory).
- **Concept** — One markdown file = one unit of knowledge (table, metric, playbook, API, etc.)
- **Concept ID** — File path within the bundle, minus `.md` suffix. Example: `tables/users.md` → ID `tables/users`
- **Frontmatter** — YAML block between `---` delimiters at file top.
- **Body** — Everything after the frontmatter. Standard markdown.
- **Link** — Standard markdown link expressing a relationship between concepts.
- **Citation** — Link to an external source backing a claim in the body.
---
## Quick Reference — Frontmatter Fields
| Field | Required? | Description |
|-------|-----------|-------------|
| `type` | **YES** | Kind of concept (free-form string, e.g. `BigQuery Table`, `Metric`, `Playbook`, `API Endpoint`) |
| `title` | Recommended | Human-readable display name |
| `description` | Recommended | One-sentence summary |
| `resource` | Recommended | URI identifying the underlying asset (omit for abstract concepts) |
| `tags` | Optional | YAML list for cross-cutting categorization |
| `timestamp` | Optional | ISO 8601 datetime of last meaningful change |
Additional producer-defined keys are allowed. Never reject unknown fields.
## Reserved Filenames
| File | Purpose | Has frontmatter? |
|------|---------|-----------------|
| `index.md` | Directory listing for progressive disclosure | NO* |
| `log.md` | Change history, newest first | NO |
*Exception: bundle-root `index.md` MAY have frontmatter with `okf_version: "0.1"` to declare spec version.
## Conventional Body Headings
| Heading | When to use |
|---------|-------------|
| `# Schema` | Data assets — describe columns/fields |
| `# Examples` | Show concrete usage (code blocks, queries) |
| `# Citations` | List external sources backing claims (numbered) |
---
## Create a Bundle
When the user wants to create an OKF bundle from scratch:
### 1. Determine scope and structure
Ask: What knowledge are we capturing? (tables, metrics, APIs, playbooks, etc.)
Organize into a directory tree that makes sense for the domain.
### 2. Create concept documents
Each concept = one `.md` file. Minimal conformant example:
```markdown
---
type: Metric
title: Monthly Recurring Revenue
description: Sum of all active subscription revenue normalized to monthly.
tags: [revenue, saas]
timestamp: 2026-06-13T10:00:00Z
---
# Monthly Recurring Revenue (MRR)
## Definition
Sum of all active subscriptions normalized to a monthly amount.
Excludes one-time fees and overages.
## Formula
`MRR = Σ(active_subscription_monthly_value)`
## Related
- [Churn Rate](./churn.md) uses MRR as denominator
- [ARR](./arr.md) = MRR × 12
```
For more examples across domains, see [references/examples.md](references/examples.md).
### 3. Cross-link concepts
Use standard markdown links. Two forms:
- **Absolute** (bundle-relative, starts with `/`): `[customers](/tables/customers.md)` — **preferred** (stable when files move)
- **Relative**: `[churn](./churn.md)`
Links assert relationships. The kind of relationship is conveyed by surrounding prose, not by the link syntax. Broken links are explicitly permitted — they represent knowledge not yet written.
### 4. Generate index.md
Place in any directory for progressive disclosure. No frontmatter. Format:
```markdown
# Metrics
- [MRR](./mrr.md) - Monthly recurring revenue
- [Churn](./churn.md) - Monthly churn rate
- [NPS](./nps.md) - Net Promoter Score
```
Entries should include the description from the linked concept's frontmatter.
### 5. Generate log.md (optional)
Chronological change history, newest first, ISO 8601 date headings:
```markdown
# Update Log
## 2026-06-13
- **Creation**: Added MRR, Churn, and NPS metrics.
- **Creation**: Established directory structure.
## 2026-06-10
- **Initialization**: Bundle created.
```
The bold leading word (`**Update**`, `**Creation**`, `**Deprecation**`) is convention, not requirement.
### 6. Declare version (optional)
Bundle-root `index.md` may include frontmatter declaring the spec version:
```markdown
---
okf_version: "0.1"
---
# My Knowledge Bundle
- [Tables](./tables/) - Database tables
- [Metrics](./metrics/) - Business KPIs
```
This is the only place frontmatter is permitted in an `index.md`.
### 7. Distribution
A bundle can be distributed as:
- A **git repository** (recommended — history, attribution, diffs)
- A tarball or zip archive
- A subdirectory within a larger repository
### 8. Verify conformance
Three rules — all must pass:
1. Every non-reserved `.md` file has parseable YAML frontmatter
2. Every frontmatter has a non-empty `type` field
3. Reserved files (`index.md`, `log.md`) follow their defined structure when present
---
## Validate a Bundle
### Preferred: okflint (when available)
[okflint](https://github.com/mattdav/okflint) is a dedicated Python linter for OKF bundles with 18 rules across 3 tiers (OKF core, profile, hygiene). If installed, always prefer it over the built-in bash script.
**Agent behavior:** Before validating, check if okflint is installed (`command -v okflint`). If NOT installed, ask the user:
> "okflint (linter dedicado para OKF com 18 regras, profiles via manifesto e suporte a wikilinks) não está instalado. Quer que eu instale? Opções:
> 1. `uv tool install okflint` (recomendado, isolado)
> 2. `pip install okflint`
> 3. Seguir sem ele (validação básica com o script bash embutido)"
If the user agrees to install:
```bash
# Option 1: uv (recommended — installs isolated, no venv needed)
uv tool install okflint
# Option 2: pip (installs in current environment)
pip install okflint
# Verify installation
okflint --version
```
After installation (or if already available):
```bash
# Full validation with manifest (if okf-base.yaml exists)
if [ -f okf-base.yaml ]; then
okflint validate --manifest okf-base.yaml ./bundle/
else
# Core OKF validation only (no manifest needed)
okflint validate ./bundle/
fi
```
**okflint advantages over the built-in script:**
- Manifest-driven profiles (enforce custom required fields, status vocabularies, per-type constraints)
- Wikilink resolution against full Obsidian vault
- JSON output (`--json`) for CI pipeline parsing
- Detects broken markdown links and ambiguous wikilinks
- Exit codes: `0` = pass, `1` = conformance failure, `2` = bad manifest
### Fallback: built-in bash script
When okflint is not installed, use [scripts/validate.sh](scripts/validate.sh) which checks the 3 core conformance rules.
When asked to validate, check the 3 conformance rules. Report:
```
✅ PASS: 12/12 concept files have valid frontmatter with type field
✅ PASS: index.md follows list structure (no frontmatter)
✅ PASS: log.md uses ISO 8601 date headings, newest first
⚠ WARNING: 3 files missing 'description' field (recommended)
⚠ WARNING: 2 broken cross-links (permitted but worth noting)
```
For a script-based check, see [scripts/validate.sh](scripts/validate.sh).
### Errors (conformance failures)
- `E1`: File `{path}` has no YAML frontmatter
- `E2`: File `{path}` has frontmatter but no `type` field (or empty)
- `E3`: Reserved file `{path}` has unexpected structure
### Warnings (non-blocking, spec allows these)
- `W1`: Missing recommended field `title` or `description`
- `W2`: Broken cross-link `{link}` in `{file}`
- `W3`: No `timestamp` field
- `W4`: No `index.md` in directory `{dir}`
- `W5`: `log.md` dates not in ISO 8601 format
Consumers MUST NOT reject a bundle because of: missing optional fields, unknown type values, unknown frontmatter keys, broken links, or missing index files.
---
## Enrich Concepts
When the user has existing OKF concepts that need enrichment:
### Add schema section
For data assets, add `# Schema` with a columns table:
```markdown
# Schema
| Column | Type | Description |
|--------|------|-------------|
| `order_id` | STRING | Unique identifier |
| `customer_id` | STRING | FK to [customers](/tables/customers.md) |
```
### Add examples section
For APIs, queries, or tools, add `# Examples` with fenced code blocks showing usage.
### Add citations
When claims reference external sources, add `# Citations` at the bottom, numbered:
```markdown
# Citations
[1] [Official docs](https://example.com/docs)
[2] [Internal runbook](https://wiki.internal/quality)
```
Citations may be absolute URLs, bundle-relative paths, or paths into a `references/` subdirectory.
### Add cross-links
Weave links into natural prose. Don't create a standalone "links" section — express relationships in context where they're meaningful.
### Fill recommended fields
If `title`, `description`, `tags`, or `timestamp` are missing, add them. Derive values from body content when possible.
### Enrichment workflow reference
The official enrichment agent follows this pattern — apply the same logic manually:
1. Start with metadata-only docs (just frontmatter + minimal body)
2. Add schema/structure from source system
3. Add citations from authoritative documentation
4. Weave cross-links based on discovered relationships (FKs, shared tags, join paths)
5. Generate `index.md` files for progressive disclosure
---
## Convert Sources to OKF
For detailed conversion guides, see [references/conversion.md](references/conversion.md).
### Quick rules
**Notion export:** Properties → frontmatter. Remove UUID suffixes from filenames. Convert Notion links → relative markdown links.
**Obsidian vault:** Convert `[[wikilinks]]` → `[title](./file.md)`. Ensure `type` field exists. Move inline `#tags` to frontmatter.
**CSV/spreadsheet:** Each row = one concept. Map columns to frontmatter fields. First column = filename.
---
## Guardrails
1. **NEVER invent data.** If you don't know the correct `type`, ask. If you don't have schema info, leave it out. No fabricated URLs or column names.
2. **Preserve unknown fields.** OKF explicitly allows extension. Don't delete fields you don't recognize.
3. **Don't impose taxonomy.** Type values are free-form strings. Suggest descriptive values but never reject a bundle for having unexpected types.
4. **Broken links are OK.** The spec explicitly permits them — they represent not-yet-written knowledge.
5. **Minimal by default.** Generate only `type` (required) + recommended fields that are warranted. Don't pad with empty values.
6. **Ask before assuming.** If the domain is unclear, ask what types and structure make sense.
---
## Serve via Google Cloud Knowledge Catalog
Google Cloud's Knowledge Catalog **natively ingests OKF bundles** and serves them to agents. This is the enterprise path — optional but powerful.
### kcmd CLI (Metadata as Code)
`kcmd` is a bidirectional sync tool between OKF-like local metadata and Knowledge Catalog. Think "git for metadata."
```bash
# Initialize from BigQuery dataset
kcmd init --bigquery-dataset <project>.<dataset>
# Pull current state from catalog
kcmd pull
# Push local changes
kcmd push --dry-run
kcmd push
```
Also ships as an **MCP server** for agent integration:
```json
{
"mcpServers": {
"kc-mac": {
"command": "kcmd",
"args": ["mcp", "--path", "/path/to/root"]
}
}
}
```
MCP tools: `pull`, `push`, `list-entries`, `lookup-entry`, `modify-entry`.
### Reference Enrichment Agent
The official enrichment agent (Python, ADK, Gemini) auto-generates OKF bundles from BigQuery metadata. Two-pass architecture:
1. **BQ pass** — one OKF doc per table/view from metadata
2. **Web pass** — LLM crawls seed URLs and for each page decides to:
- **(a) Enrich** existing concepts with citations/schemas
- **(b) Mint** a new `references/<slug>` doc
- **(c) Skip** irrelevant content
Controls: `--web-seed-file`, `--web-max-pages`, `--web-allowed-host`, `--no-web`.
**When to mention this to users:** If they're enriching BigQuery datasets, point them to the [reference agent](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf). If they want enterprise catalog integration, point to [kcmd](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/toolbox/mdcode) and the [ingest demo](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/toolbox/mdcode/demo).
---
## Output Format
When creating a bundle, present results as:
1. **Directory tree** showing the full structure
2. **Each file's content** in fenced code blocks
3. **Conformance check** confirming the bundle passes the 3 rules
```
saas-metrics/
├── index.md
├── log.md
├── mrr.md
├── churn.md
└── nps.md
```
Then show each file, then confirm: "Bundle is OKF v0.1 conformant ✅"

141
.github/skills/okf-open-knowledge-format/references/conversion.md vendored Normal file
View File

@@ -0,0 +1,141 @@
# Converting Sources to OKF
Guides for transforming existing knowledge into conformant OKF bundles.
---
## From Notion Export
Notion exports as markdown with properties in YAML-like format.
### Steps
1. **Export** from Notion as Markdown & CSV
2. **Clean filenames** — remove UUID suffixes (`Page Name abc123def.md` → `page-name.md`)
3. **Map properties to frontmatter:**
| Notion Property | OKF Field |
|-----------------|-----------|
| Type (select) | `type` (required) |
| Name | `title` |
| Tags (multi-select) | `tags` |
| Last Edited | `timestamp` |
| URL | `resource` |
4. **Convert links** — Notion uses `[Page Name](Page%20Name%20abc123def.md)`. Convert to clean relative paths: `[Page Name](./page-name.md)`
5. **Remove Notion artifacts** — empty toggle blocks, breadcrumb headers, cover image references
6. **Add missing `type` field** — if Notion had no "Type" property, ask the user what type to assign
### Edge cases
- Notion databases: each row becomes a concept. Database title becomes the directory name.
- Nested pages: respect the hierarchy. Child pages go in subdirectories.
- Inline databases: flatten into a list in the parent concept's body.
- Notion formulas/rollups: drop them — they don't translate to static markdown.
---
## From Obsidian Vault
Obsidian vaults are already close to OKF. Main differences: wikilinks and potentially missing `type` field.
### Steps
1. **Convert wikilinks to standard links:**
- `[[Note Name]]` → `[Note Name](./note-name.md)`
- `[[Note Name|Display Text]]` → `[Display Text](./note-name.md)`
- `[[Note Name#Heading]]` → `[Note Name](./note-name.md#heading)`
2. **Ensure `type` field exists** in every frontmatter block. Common mappings:
| Obsidian pattern | Suggested OKF type |
|------------------|--------------------|
| Daily notes | `Log` |
| MOC / index note | Convert to `index.md` (reserved file) |
| Permanent notes | `Reference` |
| Literature notes | `Reference` |
| Project notes | `Playbook` or domain-specific |
3. **Convert tags:**
- Inline `#tag` → move to frontmatter `tags: [tag]`
- Nested `#parent/child` → flatten to `tags: [parent, child]` or keep as `parent/child`
4. **Handle embeds:**
- `![[Note]]` — convert to a regular link or inline the content
- `![[image.png]]` — keep as standard markdown image `![](./image.png)`
5. **Remove Obsidian-specific syntax:**
- `%%comments%%` → remove
- `> [!callout]` → convert to blockquote or heading
- Dataview queries → remove (dynamic, not portable)
### What to keep as-is
- Standard markdown formatting (headings, lists, tables, code blocks)
- Existing YAML frontmatter (just add `type` if missing)
- Standard markdown links (already OKF-compatible)
- Mermaid diagrams (standard markdown fenced blocks)
---
## From CSV / Spreadsheet
Each row becomes one concept document.
### Steps
1. **Identify column mapping:**
| Column role | Maps to |
|-------------|---------|
| Primary identifier / name | Filename (slugified) |
| Category / kind | `type` field |
| Short description | `description` field |
| Tags / labels | `tags` field |
| URL / link | `resource` field |
| Last modified date | `timestamp` field |
| All other columns | Body content (as table or sections) |
2. **Generate one `.md` per row:**
```markdown
---
type: {category_column}
title: {name_column}
description: {description_column}
tags: [{tag1}, {tag2}]
timestamp: {date_column}T00:00:00Z
---
# {name_column}
| Field | Value |
|-------|-------|
| Column3 | {value} |
| Column4 | {value} |
```
3. **Generate index.md** from the full list:
```markdown
# {Sheet Name}
- [{row1_name}](./{row1_slug}.md) - {row1_description}
- [{row2_name}](./{row2_slug}.md) - {row2_description}
```
4. **Generate log.md** with creation entry:
```markdown
# Update Log
## {today_iso8601}
- **Creation**: Generated {N} concepts from spreadsheet import.
```
### Edge cases
- Empty cells: omit the field entirely (don't write empty strings)
- Multi-value cells (comma-separated): parse into YAML list for `tags`
- Very long text cells: put in body as a section, not in frontmatter
- Duplicate names: append a disambiguator (e.g., `widget-v1.md`, `widget-v2.md`)

302
.github/skills/okf-open-knowledge-format/references/examples.md vendored Normal file
View File

@@ -0,0 +1,302 @@
# OKF Bundle Examples
Three complete, conformant bundles across different domains.
---
## 1. E-commerce Analytics
```
ecommerce/
├── index.md
├── tables/
│ ├── index.md
│ ├── orders.md
│ └── customers.md
└── metrics/
├── index.md
└── gross-revenue.md
```
### tables/orders.md
```markdown
---
type: BigQuery Table
title: Orders
description: One row per completed customer order across all channels.
resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
tags: [sales, orders, revenue]
timestamp: 2026-05-28T14:30:00Z
---
# Schema
| Column | Type | Description |
|--------|------|-------------|
| `order_id` | STRING | Globally unique order identifier |
| `customer_id` | STRING | FK to [customers](./customers.md) |
| `total_usd` | NUMERIC | Order total in US dollars |
| `placed_at` | TIMESTAMP | When the customer submitted the order |
| `channel` | STRING | Acquisition channel (web, mobile, pos) |
# Joins
- Join with [customers](./customers.md) on `customer_id`
- Referenced by [gross revenue](/metrics/gross-revenue.md) metric
# Citations
[1] [BigQuery schema docs](https://cloud.google.com/bigquery/docs/schemas)
```
### tables/customers.md
```markdown
---
type: BigQuery Table
title: Customers
description: One row per registered customer with profile and lifetime data.
resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=customers
tags: [sales, customers]
timestamp: 2026-05-28T14:30:00Z
---
# Schema
| Column | Type | Description |
|--------|------|-------------|
| `customer_id` | STRING | Primary key |
| `email` | STRING | Customer email (hashed in prod) |
| `created_at` | TIMESTAMP | Registration date |
| `ltv_usd` | NUMERIC | Lifetime value in USD |
# Joins
- Referenced by [orders](./orders.md) on `customer_id`
```
### metrics/gross-revenue.md
```markdown
---
type: Metric
title: Gross Revenue
description: Total revenue before refunds and discounts.
tags: [revenue, finance, kpi]
timestamp: 2026-05-28T14:30:00Z
---
# Definition
Sum of `total_usd` from [orders](/tables/orders.md) for a given period.
Does not subtract refunds — see Net Revenue for that.
# SQL
```sql
SELECT DATE_TRUNC(placed_at, MONTH) as month,
SUM(total_usd) as gross_revenue
FROM `acme.sales.orders`
GROUP BY 1
```
# Related
- Source table: [orders](/tables/orders.md)
- Counterpart: Net Revenue (gross minus refunds)
```
### index.md (root)
```markdown
# E-commerce Analytics Bundle
- [Tables](./tables/) - Database tables powering the analytics stack
- [Metrics](./metrics/) - Business KPIs derived from tables
```
---
## 2. SaaS Incident Playbooks
```
incidents/
├── index.md
├── alerts/
│ ├── index.md
│ ├── api-latency-p99.md
│ └── db-connections.md
└── runbooks/
├── index.md
└── escalate-incident.md
```
### alerts/api-latency-p99.md
```markdown
---
type: Alert
title: API Latency P99 > 2s
description: Fires when 99th percentile API latency exceeds 2 seconds for 5 minutes.
tags: [api, latency, critical]
severity: critical
timestamp: 2026-06-01T09:00:00Z
---
# Trigger Condition
```promql
histogram_quantile(0.99, rate(http_request_duration_seconds_bucket[5m])) > 2
```
# Impact
Users experience timeouts. Downstream services may cascade-fail.
# Response
1. Check [DB connections alert](./db-connections.md) — often the root cause
2. Follow [escalation runbook](/runbooks/escalate-incident.md) if not resolved in 10 min
3. Check deployment log for recent changes
# Citations
[1] [SLA definition](https://wiki.internal/sla/api-latency)
```
### runbooks/escalate-incident.md
```markdown
---
type: Runbook
title: Escalate Incident
description: Steps to escalate when on-call cannot resolve within SLA.
tags: [oncall, incident, escalation]
timestamp: 2026-06-01T09:00:00Z
---
# When to Escalate
- Alert not resolved within 10 minutes
- Customer-facing impact confirmed
- Multiple alerts firing simultaneously
# Steps
1. Post in #incidents Slack channel with alert link
2. Page the secondary on-call (PagerDuty)
3. If P1: page Engineering Manager
4. Start incident document from template
5. Update status page if customer-facing
# Contacts
| Role | Who | Method |
|------|-----|--------|
| Secondary on-call | Rotation | PagerDuty |
| Eng Manager | @manager | Slack DM |
| Infra lead | @infra-lead | Slack DM |
```
---
## 3. API Documentation
```
api/
├── index.md
├── auth/
│ ├── index.md
│ └── oauth2-flow.md
├── endpoints/
│ ├── index.md
│ └── create-order.md
└── policies/
├── index.md
└── rate-limits.md
```
### endpoints/create-order.md
```markdown
---
type: API Endpoint
title: Create Order
description: Creates a new order for an authenticated customer.
resource: https://api.acme.com/v2/orders
tags: [orders, write, v2]
method: POST
timestamp: 2026-05-20T10:00:00Z
---
# POST /v2/orders
Creates a new order. Requires [OAuth2 authentication](/auth/oauth2-flow.md).
# Request
```json
{
"customer_id": "cust_abc123",
"items": [{"sku": "WIDGET-01", "quantity": 2}],
"idempotency_key": "unique-request-id"
}
```
# Response (201 Created)
```json
{
"order_id": "ord_xyz789",
"status": "pending",
"total_usd": 49.98,
"created_at": "2026-05-20T10:30:00Z"
}
```
# Errors
| Code | Meaning |
|------|---------|
| 400 | Invalid request body |
| 401 | Missing or invalid auth token |
| 409 | Duplicate idempotency_key |
| 429 | [Rate limit](/policies/rate-limits.md) exceeded |
# Rate Limits
Subject to [rate limiting](/policies/rate-limits.md). See `X-RateLimit-*` headers.
```
### policies/rate-limits.md
```markdown
---
type: Policy
title: Rate Limits
description: Per-plan rate limits for all API endpoints.
tags: [policy, rate-limit, api]
timestamp: 2026-05-20T10:00:00Z
---
# Limits by Plan
| Plan | Requests/min | Burst |
|------|-------------|-------|
| Free | 60 | 10 |
| Pro | 600 | 100 |
| Enterprise | 6000 | 1000 |
# Response Headers
Every response includes:
- `X-RateLimit-Limit`: max requests per window
- `X-RateLimit-Remaining`: requests left in window
- `X-RateLimit-Reset`: Unix timestamp of window reset
# When Exceeded
Returns `429 Too Many Requests`. Retry after `X-RateLimit-Reset`.
Applies to all endpoints including [create order](/endpoints/create-order.md).
```

451
.github/skills/okf-open-knowledge-format/references/spec-v01.md vendored Normal file
View File

@@ -0,0 +1,451 @@
# Open Knowledge Format (OKF)
**Version 0.1 — Draft**
OKF is an open, human- and agent-friendly format for representing
*knowledge* — the metadata, context, and curated insight that surrounds
data and systems. It is designed to be authored by people, generated by
agents, exchanged across organizations, and consumed by both.
The format is intentionally minimal: a directory of markdown files with
YAML frontmatter. There is no schema registry, no central authority, and
no required tooling. If you can `cat` a file, you can read OKF; if you
can `git clone` a repo, you can ship it.
---
## 1. Motivation
The space of knowledge representation for AI agents is evolving quickly,
and many incompatible conventions are emerging. OKF takes the position
that knowledge is best represented in commonly accessible, established
formats that are:
- **Readable** by humans without tooling.
- **Parseable** by agents without bespoke SDKs.
- **Diffable** in version control.
- **Portable** across tools, organizations, and time.
The format is minimally opinionated. It standardizes only the small set
of structural conventions needed to make a knowledge corpus
*self-describing* — anything beyond that is left to the producer.
### Goals
1. Define a universal format that **enrichment agents** can write into.
2. Inform how **consumption agents** should read and traverse it.
3. Facilitate **exchange** of knowledge across systems and organizations.
4. Standardize the small number of **required** fields that must be
present for content to be meaningfully consumed.
### Non-goals
- Defining a fixed taxonomy of concept types.
- Prescribing storage, serving, or query infrastructure.
- Replacing domain-specific schemas (Avro, Protobuf, OpenAPI, etc.) —
OKF *references* them; it does not subsume them.
---
## 2. Terminology
- **Knowledge Bundle** — A self-contained, hierarchical collection of
knowledge documents. The unit of distribution.
- **Concept** — A single unit of knowledge within a bundle. Represented
as one markdown document. May describe a tangible asset (a table, an
API), an abstract idea (a metric, a business process), or anything in
between.
- **Concept ID** — The path of the concept's file within the bundle,
with the `.md` suffix removed. For example, `tables/users.md` has
concept ID `tables/users`.
- **Frontmatter** — YAML metadata block delimited by `---` at the top of
a markdown file.
- **Body** — Everything in the file after the frontmatter.
- **Link** — A standard markdown link from one concept to another, used
to express relationships beyond the implicit parent/child hierarchy.
- **Citation** — A link from a concept to an external source that
supports a claim in the body.
---
## 3. Bundle Structure
A bundle is a directory tree of markdown files. The directory structure
is independent of the domain — producers organize concepts however makes
sense for the knowledge being captured.
```
path/to/bundle/
├── index.md # Optional. Directory listing for progressive disclosure.
├── log.md # Optional. Chronological history of updates.
├── <concept>.md # A concept at the bundle root.
└── <subdirectory>/ # Subdirectories organize concepts into groups.
├── index.md
├── <concept>.md
└── <subdirectory>/
└── …
```
A bundle MAY be distributed as:
- A git repository (recommended — provides history, attribution, diffs).
- A tarball or zip archive of the directory.
- A subdirectory within a larger repository.
### 3.1 Reserved filenames
The following filenames have defined meaning at any level of the
hierarchy and MUST NOT be used for concept documents:
| Filename | Purpose |
|--------------|--------------------------------------------------------|
| `index.md` | Directory listing. See §6. |
| `log.md` | Update history. See §7. |
All other `.md` files are concept documents.
Tags themselves remain a first-class concept — see the `tags`
frontmatter field in §4.1. OKF does not specify a separate file format
for aggregating documents by tag; producers that want a tag-browsing
view can synthesize one at consumption time by scanning frontmatter.
---
## 4. Concept Documents
Every concept is a UTF-8 markdown file. It has two parts:
1. A **YAML frontmatter block**, delimited by `---` on its own line at
the start of the file and a closing `---` on its own line.
2. A **markdown body**, containing free-form content.
### 4.1 Frontmatter
```yaml
---
type: <Type name> # REQUIRED
title: <Optional display name>
description: <Optional one-line summary>
resource: <Optional canonical URI for the underlying asset>
tags: [<tag>, <tag>, …] # Optional
timestamp: <ISO 8601 datetime> # Optional last-modified time
# … other producer-defined key/value pairs
---
```
**Required:**
- `type` — A short string identifying the kind of concept. Consumers
use this for routing, filtering, and presentation. Example values:
`BigQuery Table`, `BigQuery Dataset`, `API Endpoint`, `Metric`,
`Playbook`, `Reference`.
Type values are **not** registered centrally. Producers SHOULD pick
values that are descriptive and self-explanatory; consumers MUST
tolerate unknown types gracefully (typically by treating them as
generic concepts).
**Recommended (in priority order):**
- `title` — Human-readable display name. If omitted, consumers MAY
derive a title from the filename.
- `description` — A single sentence summarizing the concept. Used by
`index.md` generators, search snippets, and previews.
- `resource` — A URI that uniquely identifies the underlying asset the
concept describes. Absent for concepts that describe abstract ideas
rather than physical resources.
- `tags` — A YAML list of short strings for cross-cutting categorization.
- `timestamp` — ISO 8601 datetime of last meaningful change.
**Extensions:** Producers MAY include any additional keys. Consumers
SHOULD preserve unknown keys when round-tripping and SHOULD NOT reject
documents with unrecognized fields.
### 4.2 Body
The body is standard markdown. Producers SHOULD favor structural
markdown — headings, lists, tables, fenced code blocks — over freeform
prose, since structure aids both human reading and agent retrieval.
There are no required body sections. The following section headings have
**conventional** meaning and SHOULD be used when applicable:
| Heading | Purpose |
|----------------|--------------------------------------------------------|
| `# Schema` | Structured description of an asset's columns/fields. |
| `# Examples` | Concrete usage examples, often as fenced code blocks. |
| `# Citations` | External sources backing claims in the body. See §8. |
### 4.3 Example: a concept bound to a resource
```markdown
---
type: BigQuery Table
title: Customer Orders
description: One row per completed customer order across all channels.
resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
tags: [sales, orders, revenue]
timestamp: 2026-05-28T14:30:00Z
---
# Schema
| Column | Type | Description |
|---------------|-----------|------------------------------------------|
| `order_id` | STRING | Globally unique order identifier. |
| `customer_id` | STRING | Foreign key into [customers](/tables/customers.md). |
| `total_usd` | NUMERIC | Order total in US dollars. |
| `placed_at` | TIMESTAMP | When the customer submitted the order. |
# Joins
Joined with [customers](/tables/customers.md) on `customer_id`.
# Citations
[1] [BigQuery table schema](https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders)
```
### 4.4 Example: a concept not bound to a resource
```markdown
---
type: Playbook
title: Incident response — data freshness alert
description: Steps to triage a freshness alert on the orders pipeline.
tags: [oncall, incident]
timestamp: 2026-04-12T09:00:00Z
---
# Trigger
A freshness alert fires when `orders` lags more than 30 minutes behind
its expected SLA. See the [orders table](/tables/orders.md).
# Steps
1. Check the [ingestion job dashboard](https://example.com/dash).
2. …
```
---
## 5. Cross-linking
Concepts MAY link to other concepts using standard markdown links. Two
forms are supported:
### 5.1 Absolute (bundle-relative) links
Begin with `/`, interpreted relative to the bundle root.
```markdown
See the [customers table](/tables/customers.md) for the join key.
```
This is the **recommended** form because it is stable when documents are
moved within their subdirectory.
### 5.2 Relative links
Standard markdown relative paths.
```markdown
See the [neighboring concept](./other.md).
```
### 5.3 Link semantics
A link from concept A to concept B asserts a *relationship*. The
specific kind of relationship (parent/child, references, joins-with,
depends-on, etc.) is conveyed by the surrounding prose, not by the link
itself. Consumers that build a graph view typically treat all links as
directed edges of an untyped relationship.
Consumers MUST tolerate broken links — a link whose target does not
exist in the bundle is not malformed; it may simply represent
not-yet-written knowledge.
---
## 6. Index Files
An `index.md` file MAY appear in any directory, including the bundle
root. It enumerates the directory's contents to support **progressive
disclosure** — letting a human or agent see what is available before
opening individual documents.
Index files contain no frontmatter. The body uses one or more sections,
each grouping concepts under a heading:
```markdown
# Section / Group Heading
* [Title 1](relative-url-1) - short description of item 1
* [Title 2](relative-url-2) - short description of item 2
# Another Section
* [Subdirectory](subdir/) - short description of the subdirectory
```
Entries SHOULD include the description from the linked concept's
frontmatter. Producers MAY generate `index.md` automatically; consumers
MAY synthesize one on the fly when none is present.
---
## 7. Log Files (optional)
A `log.md` file MAY appear at any level of the hierarchy to record the
history of changes to that scope. The format is a flat list of
date-grouped entries, newest first:
```markdown
# Directory Update Log
## 2026-05-22
* **Update**: Added new BigQuery table reference for [Customer Metrics](/tables/customer-metrics.md).
* **Creation**: Established the [Dataplex Playbook](/playbooks/dataplex.md).
## 2026-05-15
* **Initialization**: Created foundational directory structure.
* **Update**: Added progressive-disclosure guidelines to the root [index](/index.md).
```
Date headings MUST use ISO 8601 `YYYY-MM-DD` form. Log entries are
prose; the leading bold word (`**Update**`, `**Creation**`,
`**Deprecation**`, etc.) is a convention, not a requirement.
---
## 8. Citations
When a concept's body makes claims sourced from external material,
those sources SHOULD be listed under a `# Citations` heading at the
bottom of the document, numbered:
```markdown
# Citations
[1] [BigQuery public dataset announcement](https://cloud.google.com/blog/products/data-analytics/...)
[2] [Internal data quality runbook](https://wiki.acme.internal/data/quality)
```
Citation links MAY be absolute URLs, bundle-relative paths, or paths
into a `references/` subdirectory that mirrors external material as
first-class OKF concepts.
---
## 9. Conformance
A bundle is **conformant** with OKF v0.1 if:
1. Every non-reserved `.md` file in the tree contains a parseable YAML
frontmatter block.
2. Every frontmatter block contains a non-empty `type` field.
3. Every reserved filename (`index.md`, `log.md`) follows the structure
described in §6 and §7 respectively when present.
Consumers SHOULD treat all other constraints as soft guidance. In
particular, consumers MUST NOT reject a bundle because of:
- Missing optional frontmatter fields.
- Unknown `type` values.
- Unknown additional frontmatter keys.
- Broken cross-links.
- Missing `index.md` files.
This permissive consumption model is intentional: OKF is meant to
remain useful as bundles grow, get refactored, and are partially
generated by agents.
---
## 10. Relationship to other formats
OKF is intentionally close to several established patterns:
- **LLM "wiki" repositories** that use markdown + frontmatter as
agent-readable knowledge bases.
- **Personal knowledge tools** like Obsidian and Notion, which use
hierarchical markdown with cross-links.
- **"Metadata as code"** approaches that store catalog metadata
alongside source code rather than in a separate registry.
OKF differs primarily in being **specified** — pinning down the small
set of rules needed for interoperability without dictating tooling.
---
## 11. Versioning
This document specifies OKF version **0.1**. Future revisions will be
versioned in the form `<major>.<minor>`:
- A **minor** version bump introduces backward-compatible additions
(new optional fields, new conventional section headings).
- A **major** version bump may make breaking changes (renaming required
fields, changing reserved filenames).
Bundles MAY declare the OKF version they target by including
`okf_version: "0.1"` in a bundle-root `index.md` frontmatter block (the
only place frontmatter is permitted in an `index.md`). Consumers that
do not understand the declared version SHOULD attempt best-effort
consumption rather than refusing the bundle.
---
## Appendix A — Minimal example bundle
```
my_bundle/
├── index.md
├── datasets/
│ ├── index.md
│ └── sales.md
└── tables/
├── index.md
├── orders.md
└── customers.md
```
`datasets/sales.md`:
```markdown
---
type: BigQuery Dataset
title: Sales
description: All sales-related tables for the retail business.
resource: https://console.cloud.google.com/bigquery?p=acme&d=sales
tags: [sales]
timestamp: 2026-05-28T00:00:00Z
---
The sales dataset contains transactional tables, including
[orders](/tables/orders.md) and [customers](/tables/customers.md).
```
`tables/orders.md`:
```markdown
---
type: BigQuery Table
title: Orders
description: One row per completed customer order.
resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
tags: [sales, orders]
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. |
Part of the [sales dataset](/datasets/sales.md).
```

102
.github/skills/okf-open-knowledge-format/scripts/validate.sh vendored Normal file
View File

@@ -0,0 +1,102 @@
#!/usr/bin/env bash
# OKF Bundle Validator v0.1
# Usage: validate.sh <bundle-path>
# Checks conformance with OKF v0.1 spec:
# E1: All non-reserved .md files have YAML frontmatter
# E2: All frontmatter has non-empty 'type' field
# E3: Reserved files follow structure rules
set -euo pipefail
BUNDLE="${1:-.}"
ERRORS=0
WARNINGS=0
TOTAL=0
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[0;33m'
NC='\033[0m'
if [ ! -d "$BUNDLE" ]; then
echo -e "${RED}Error: '$BUNDLE' is not a directory${NC}"
exit 1
fi
echo "Validating OKF bundle: $BUNDLE"
echo "---"
# Find all .md files
while IFS= read -r -d '' file; do
TOTAL=$((TOTAL + 1))
relative="${file#$BUNDLE/}"
basename=$(basename "$file")
# Skip reserved files (validate separately)
if [[ "$basename" == "index.md" || "$basename" == "log.md" ]]; then
# E3: Check reserved file structure
if [[ "$basename" == "index.md" ]]; then
# index.md should NOT have frontmatter (except bundle root may have okf_version)
if head -1 "$file" | grep -q "^---$"; then
# Allow only if it's bundle root and contains okf_version
if [[ "$relative" != "index.md" ]]; then
echo -e "${RED}E3: $relative — index.md should not have frontmatter${NC}"
ERRORS=$((ERRORS + 1))
fi
fi
fi
if [[ "$basename" == "log.md" ]]; then
# log.md should have date headings in YYYY-MM-DD format
if ! grep -qE "^## [0-9]{4}-[0-9]{2}-[0-9]{2}" "$file" 2>/dev/null; then
if [ -s "$file" ]; then
echo -e "${YELLOW}W: $relative — log.md has no ISO 8601 date headings${NC}"
WARNINGS=$((WARNINGS + 1))
fi
fi
fi
continue
fi
# E1: Check for YAML frontmatter
if ! head -1 "$file" | grep -q "^---$"; then
echo -e "${RED}E1: $relative — no YAML frontmatter${NC}"
ERRORS=$((ERRORS + 1))
continue
fi
# Extract frontmatter (between first --- and second ---)
frontmatter=$(sed -n '2,/^---$/p' "$file" | sed '$d')
# E2: Check for non-empty type field
type_value=$(echo "$frontmatter" | grep -E "^type:" | sed 's/^type:\s*//' | tr -d '"' | tr -d "'" | xargs)
if [ -z "$type_value" ]; then
echo -e "${RED}E2: $relative — missing or empty 'type' field${NC}"
ERRORS=$((ERRORS + 1))
continue
fi
# Warnings for recommended fields
if ! echo "$frontmatter" | grep -qE "^title:"; then
echo -e "${YELLOW}W1: $relative — missing recommended 'title' field${NC}"
WARNINGS=$((WARNINGS + 1))
fi
if ! echo "$frontmatter" | grep -qE "^description:"; then
echo -e "${YELLOW}W1: $relative — missing recommended 'description' field${NC}"
WARNINGS=$((WARNINGS + 1))
fi
done < <(find "$BUNDLE" -name "*.md" -type f -print0 | sort -z)
# Summary
echo "---"
echo "Files scanned: $TOTAL"
if [ $ERRORS -eq 0 ]; then
echo -e "${GREEN}✅ Bundle is OKF v0.1 conformant${NC}"
else
echo -e "${RED}❌ $ERRORS error(s) — bundle is NOT conformant${NC}"
fi
if [ $WARNINGS -gt 0 ]; then
echo -e "${YELLOW}⚠ $WARNINGS warning(s)${NC}"
fi
exit $ERRORS