Neue Skills, Referenzen & OpenWiki-Doku integriert

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.
2026-07-26 14:00:58 +02:00
parent 070727d5cd
commit 01046b01e4
202 changed files with 31290 additions and 0 deletions
--- a/.github/skills/okf-open-knowledge-format/SKILL.md
+++ b/.github/skills/okf-open-knowledge-format/SKILL.md
@@ -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 ✅"