{
  "markdown": "# Open Doc Format — OKF Skills for AI Coding Agents\n\n> **30 seconds to understand. 3 minutes to install.** Portable knowledge bundles for humans and AI agents, now with first-class tooling for Claude Code, Factory Droid, and Pi.\n\n## ⏱️ 30 Seconds: What Is This?\n\nThis project gives your AI coding agent the ability to create, validate, and navigate **[Open Knowledge Format (OKF) v0.1](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)** bundles — directories of Markdown files with YAML frontmatter that represent a knowledge catalog (datasets, tables, APIs, playbooks, metrics, etc.).\n\n```\nmy-catalog/                  # ← An OKF bundle — plain files, lives in git\n├── index.md                 # Progressive disclosure listing\n├── log.md                   # Chronological change history\n├── datasets/\n│   ├── index.md\n│   └── sales.md             # Concept: describes the Sales dataset\n├── tables/\n│   ├── index.md\n│   ├── orders.md            # Concept: table schema + joins\n│   └── customers.md\n└── playbooks/\n    └── revenue-review.md\n```\n\n**Three things every concept file has:**\n\n```markdown\n---\ntype: BigQuery Table           # ← Only required field\ntitle: Customer Orders\ndescription: One row per completed order across all channels.\nresource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders\ntags: [sales, orders, revenue]\ntimestamp: 2026-06-15T12:00:00Z\n---\n\n# Schema\n| Column     | Type    | Description              |\n|------------|---------|--------------------------|\n| order_id   | STRING  | Unique order identifier. |\n...\n```\n\n**3 conformance rules. No SDK. No lock-in. MIT-licensed spec by Google Cloud.**\n\n---\n\n## 🚀 3 Minutes: Install the Skill\n\nChoose your agent. Each install takes ~60 seconds.\n\n### Claude Code\n\n```bash\n# From your project root:\nmkdir -p .claude/skills/okf/templates\ncp SKILL.md .claude/skills/okf/\ncp spec-reference.md .claude/skills/okf/\ncp templates/*.md .claude/skills/okf/templates/\n```\n\nOr clone into any project and Claude Code auto-discovers it. Verify:\n```\n/claude-skills    # Should show /okf\n```\n\n**Triggers automatically** when you ask Claude to create knowledge catalogs, validate OKF bundles, or write concept documents. Supports:\n- Auto-activation on `.md` files and `okf/` directories (`paths`)\n- Pre-approved `git *`, `Read`, `Glob`, `Grep`, `WebSearch` tools\n- `when_to_use` descriptions for context-aware discovery\n\n### Factory Droid\n\n```bash\n# From your project root:\nmkdir -p .factory/skills/okf/templates\ncp SKILL.md .factory/skills/okf/\ncp spec-reference.md .factory/skills/okf/\ncp templates/*.md .factory/skills/okf/templates/\n```\n\nRestart `droid`. Creates the `/okf` command automatically. Droid invokes the skill when you describe OKF-related tasks.\n\n### Pi\n\n```bash\n# From your project root:\nmkdir -p .pi/extensions\ncp okf.ts .pi/extensions/\n```\n\nOr for global availability (all projects):\n\n```bash\nmkdir -p ~/.pi/agent/extensions/okf/\ncp okf.ts ~/.pi/agent/extensions/okf/index.ts\n```\n\nRestart pi. Registers **7 custom tools** the LLM can call plus **3 slash commands**:\n\n| Tool / Command | Description |\n|---|---|\n| `okf_scaffold_bundle` | Create a new bundle directory with index + log |\n| `okf_create_concept` | Create a conformant concept `.md` with validated frontmatter |\n| `okf_validate_bundle` | Validate against all 3 OKF conformance rules |\n| `okf_generate_index` | Auto-generate `index.md` from concepts in a directory |\n| `okf_read_frontmatter` | Parse and display concept metadata |\n| `/okf-validate` | TUI validation report viewer |\n| `/okf-scaffold` | Quick-scaffold a bundle in the current directory |\n\n---\n\n## 🧪 Quick Start — Try It in 30 Seconds\n\n### Claude Code\n```\nCreate an OKF bundle for our AWS infra. Include tables for EC2 instances,\nRDS databases, and a playbook for cost review.\n```\n\n### Factory Droid\n```\nScaffold an OKF bundle in ./catalog/ and add a concept for the users table\nin our PostgreSQL database.\n```\n\n### Pi\n```\nUse okf_scaffold_bundle to create a new bundle at ./knowledge.\nThen use okf_create_concept to add a BigQuery Table called \"user_events\"\nwith columns: event_id (STRING), user_id (STRING), event_type (STRING),\ncreated_at (TIMESTAMP).\nFinally run okf_validate_bundle on ./knowledge.\n```\n\nOr try the interview:\n```\n/okf-interview\n```\n\n---\n\n## 📁 Project Structure\n\n```\nopen-doc-format/\n├── README.md\n│\n├── .claude/skills/okf/          # Claude Code skill\n│   ├── SKILL.md                 #   Main instructions (320 lines)\n│   ├── spec-reference.md        #   Condensed OKF v0.1 spec\n│   └── templates/\n│       ├── concept.md           #   Concept document template\n│       ├── index.md            #   Index file template\n│       └── log.md              #   Log file template\n│\n├── .factory/skills/okf/         # Factory Droid skill\n│   ├── SKILL.md                 #   Main instructions (280 lines)\n│   ├── spec-reference.md\n│   └── templates/               #   Same templates as above\n│\n└── .pi/extensions/\n    └── okf.ts                   # Pi extension (1284 lines)\n                                 #   4 tools + 2 commands + TUI viewer\n```\n\n## 📖 What Each Skill Teaches Your Agent\n\n| Capability | Details |\n|---|---|\n| **Create bundles** | Scaffold directories, root `index.md` with `okf_version`, `log.md` initialization |\n| **Write concepts** | YAML frontmatter with required `type`, recommended fields (`title`, `description`, `resource`, `tags`, `timestamp`), structural Markdown body, conventional sections (`# Schema`, `# Examples`, `# Citations`) |\n| **Cross-link** | Absolute bundle-relative links (`/tables/orders.md`), relative links |\n| **Generate indexes** | Progressive disclosure format, auto-grouping by type, tags, or flat |\n| **Validate** | 3 conformance rules (frontmatter presence, `type` field, reserved files) + soft warnings (broken links, missing descriptions) |\n| **Consume** | Navigate via `index.md`, extract frontmatter, follow cross-links |\n\n## 🔗 About OKF\n\nThe [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) is a vendor-neutral, MIT-licensed specification by Google Cloud for representing knowledge as plain Markdown with YAML frontmatter. It formalizes the \"LLM wiki\" pattern — teams already dump markdown docs into repos for agents to read — into an interoperable standard.\n\n- **Spec:** [OKF v0.1 SPEC.md](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)\n- **Reference implementation:** [GoogleCloudPlatform/knowledge-catalog](https://github.com/GoogleCloudPlatform/knowledge-catalog)\n- **Community site:** [okf.md](https://okf.md/)\n\n## 📄 License\n\nThis skill collection is MIT licensed. OKF itself is a separate specification licensed under MIT by Google Cloud.\n",
  "bytes": 6752,
  "sha": "36a059caa3fa50ace0845f5ce8059ee66470ea24a3f3e8fe0a352eed7577e285",
  "repo_slug": "leonj1/open-doc-format",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_leonj1_open_doc_format_personal_knowledg_836185d5/readme"
}