okf
Skill63 starsChanged 3 months agoMITView on GitHub
Create, read, and maintain Open Knowledge Format documentation bundles in repositories. Use this skill when the user asks for /okf, OKF, Open Knowledge Format, docs-as-knowledge, reading project context from docs, reorganizing docs into an agent-readable bundle, updating docs/specs/ADRs after a session or PR, or adding AGENTS.md instructions for agents to consume and maintain the docs bundle. Supports /okf read, /okf init, and /okf update workflows.
17 other projects use a version of this.
Adopted by
Most recently taken up by
- superwebpros/claude-skillstheir own version, first seen Nov 16, 2026
- narr07/skillstheir own version, first seen Nov 15, 2026
- cofin/flowtheir own version, first seen Nov 15, 2026
- MMACABRE/SKILLStheir own version, first seen Nov 8, 2026
- saschb2b/okf-bundlestheir own version, first seen Oct 20, 2026
- gradigit/claude-skillstheir own version, first seen Oct 15, 2026
Other versions17 projects use a version of this.
Word for word · 2
- gannonh/kata★ 67100% same
- gannonh/skills★ 2100% same
Edited · 0
None found.
Wrote their own version · 15
- scaccogatto/okf-skills★ 444same name
- sniperunder123/okf-knowledge★ 65same name
- saschb2b/skills★ 22same name
- cofin/flow★ 20same name
- k3ybladewielder/skills★ 7same name
- eloybar/okf-skills★ 5same name
- EwenSellitto/skills★ 4same name
- 18studio/simple_okf★ 3same name
- saschb2b/okf-bundles★ 2same name
- jeromeetienne/issue_autofix★ 1same name
5 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository6 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- debug-symphonySkill
- mintlifySkill
- plan-build-verify-githubSkill
- releasing-kataSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
66 rules. 0 are common, 41 are distinctive, and 25 are very specific to this project.
0
Common
Most of the 15 edited versions we read keep these.
41
Distinctive
This author's own choices. Worth a look.
25
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 8
Use this skill to read, initialize, or update an Open Knowledge Format bundle for a repository.
- Very specific: line 10
Before editing, read references/SPEC.md from this skill directory.
- Distinctive: line 12
When validating a bundle, use the bundled helper when available:
- Very specific: line 18
Use --strict-links when broken local Markdown links should fail validation instead of warn.
- Distinctive: line 32
Create and maintain these sections in every repository OKF bundle:
- Distinctive: line 52
Create additional sections when the repository has durable knowledge that belongs there.
- Distinctive: line 61
Use the repo's existing language.
- Very specific: line 65
Every Markdown file under ./docs is a concept document unless its filename is index.md or log.md.
- Very specific: line 79
Only type is required by OKF, but include title and description whenever you can infer them confidently.
- Distinctive: line 81
Use type names that explain what the document is, for example:
- Distinctive: line 97
Use cross-links for durable relationships such as:
- Very specific: line 105
Prefer bundle-relative absolute links, such as /specs/auth-redesign.md, when linking within the OKF bundle.
- Distinctive: line 107
Add links in both directions when both concepts benefit from traversal.
- Distinctive: line 109
Do not invent relationships.
- Distinctive: line 121
Use this read-only workflow when the user asks to load OKF context, understand the project before work, inspect the roadmap, review …
- Very specific: line 124
Use ./docs unless the user names another bundle root.
- Very specific: line 125
If ./docs/index.md is missing, report that no OKF bundle was found and suggest /okf init if appropriate.
- Very specific: line 126
Do not edit files, update logs, or create new documents during /okf read.
- Distinctive: line 128
Read the top-level map.
- Very specific: line 130
Read ./docs/specs/index.md when present because it is the roadmap.
- Very specific: line 131
Read ./docs/adrs/index.md when present to identify relevant decisions.
- Distinctive: line 135
Follow Markdown links from the roadmap and relevant indexes into specs, ADRs, architecture notes, guides, runbooks, reference docs, and …
- Distinctive: line 136
Prefer documents directly related to the user's task, changed files, named features, architecture areas, APIs, migrations, or operational …
- Distinctive: line 137
Stop when the context is sufficient for the requested work.
- Distinctive: line 142
Call out constraints, accepted decisions, open questions, stale links, missing docs, or docs gaps.
- Distinctive: line 147
Use this workflow when the repo does not already have a coherent OKF bundle or the user asks to reorganize existing documentation.
- Distinctive: line 151
If there are unrelated dirty changes, ask before moving or rewriting docs.
- Very specific: line 155
Search for Markdown docs in ./docs, root-level files, and common documentation locations such as adr/, adrs/, spec/, specs/, plans/, …
- Distinctive: line 157
Read enough content to classify each document by purpose and freshness.
- Distinctive: line 158
If you are uncertain whether a file should be migrated into OKF format or moved into an OKF location, ask the user for clarification before …
- Distinctive: line 161
Use the required sections above.
- Distinctive: line 162
Add optional sections only when existing docs or repo needs justify them.
- Distinctive: line 163
Prefer git mv for file moves when the repo is under git.
- Very specific: line 167
Add missing frontmatter to non-reserved Markdown files under ./docs.
- Distinctive: line 170
Create cross-links between related specs, ADRs, guides, runbooks, reference docs, architecture notes, and roadmap entries.
- Very specific: line 171
Use bundle-relative links from the docs root when stable, such as /specs/my-plan.md.
- Distinctive: line 174
Create indexes and logs.
- Very specific: line 175
Write ./docs/index.md as the top-level roadmap and navigation page.
- Very specific: line 176
Write ./docs/specs/index.md as the roadmap for planned and completed work.
- Very specific: line 177
Write index.md for every created optional section.
- Very specific: line 178
Create log.md files at the root, specs/, adrs/, and other sections that receive substantive changes.
- Very specific: line 182
Add clear instructions that agents should read ./docs/index.md before substantial work.
- Distinctive: line 186
Keep project-specific AGENTS.md instructions intact.
- Very specific: line 189
Run python <skill-dir>/scripts/validate_okf.py <repo-root> when this skill's helper script is available.
- Very specific: line 190
Check every non-reserved Markdown file under ./docs has parseable YAML frontmatter with non-empty type.
- Very specific: line 191
Check reserved index.md and log.md files match OKF structure.
- Distinctive: line 192
Check important moved links.
- Distinctive: line 193
Run available docs lint or tests if the repo has them.
- Distinctive: line 202
Use this workflow near the end of a session, feature branch, or PR.
- Distinctive: line 206
Read recent commits or PR context if available.
- Distinctive: line 209
Read the current OKF map.
- Distinctive: line 212
Read relevant ADRs, specs, runbooks, or domain docs before editing.
- Distinctive: line 214
Update the right concepts.
- Distinctive: line 215
Update existing documents when the concept already exists.
- Distinctive: line 216
Create new concept documents only for durable knowledge worth preserving.
- Distinctive: line 217
Add or update ADRs for architecture decisions with lasting consequences.
- Distinctive: line 218
Update specs when scope, status, acceptance criteria, rollout, or implementation details changed.
- Distinctive: line 219
Update runbooks, guides, or reference docs when operators or future agents need the information.
- Very specific: line 222
Update affected index.md files so readers can discover new or changed concepts.
- Very specific: line 223
Keep ./docs/specs/index.md current as the roadmap.
- Distinctive: line 224
Add or refresh cross-links between related specs, ADRs, guides, runbooks, reference docs, architecture notes, and roadmap entries.
- Distinctive: line 225
Add reciprocal links when both documents benefit from traversal.
- Very specific: line 228
Add a newest-first entry to the nearest relevant log.md files.
- Distinctive: line 230
Keep log entries factual and brief.
- Distinctive: line 235
Run docs lint/tests when available.
- Very specific: line 273
Every non-reserved ./docs//*.md file has frontmatter with type.
“Common” is measured: kept by at least 6 in 10 of the 15 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
OKF
Use this skill to read, initialize, or update an Open Knowledge Format bundle for a repository.
Before editing, read references/SPEC.md from this skill directory. Treat that file as the source of truth for OKF v0.1 conformance.
When validating a bundle, use the bundled helper when available:
python <skill-dir>/scripts/validate_okf.py <repo-root>Use --strict-links when broken local Markdown links should fail validation instead of warn.
Core idea
An OKF bundle is a directory tree of Markdown files with YAML frontmatter for concept documents, plus index.md and log.md files for navigation and history. In repositories, the bundle root is ./docs unless the user explicitly chooses another path.
The skill has three workflows:
/okf read: read the OKF bundle to load project context before planning or changing code./okf init: reorganize existing project documentation into an OKF-compliant./docsbundle and add AGENTS.md instructions for future agents./okf update: update the OKF bundle at the end of a session, feature branch, or PR so the docs reflect completed work.
Required OKF shape for this skill
Create and maintain these sections in every repository OKF bundle:
./docs/
├── index.md # Roadmap and top-level progressive-disclosure index
├── log.md # Chronological bundle update history, newest first
├── specs/ # Product specs, technical plans, issue plans, roadmaps
│ ├── index.md # Specs roadmap and current work map
│ └── log.md # Specs update history
└── adrs/ # Architecture Decision Records
├── index.md # ADR listing grouped by accepted/proposed/superseded if known
└── log.md # ADR update history./docs/specs/index.md is the roadmap. It should make active, planned, blocked, and completed work easy to scan.
./docs/adrs is required even if the repo has no ADRs yet. Seed it with index.md and log.md so future decisions have a stable home.
Flexible sections
Create additional sections when the repository has durable knowledge that belongs there. Common examples:
architecture/for system maps, boundaries, modules, data flow, and integration notes.guides/for contributor, setup, release, deployment, and operational guides.reference/for APIs, schemas, config, CLI commands, generated references, and external-source mirrors.runbooks/for troubleshooting, incidents, maintenance, on-call, and recovery procedures.domains/for product concepts, business concepts, terminology, metrics, and domain models.research/for exploration notes that should remain discoverable but are not committed plans.
Use the repo's existing language. Do not force all optional sections into every project.
Concept document rules
Every Markdown file under ./docs is a concept document unless its filename is index.md or log.md.
For concept documents, include YAML frontmatter:
---
type: <short descriptive type>
title: <human display title>
description: <single sentence summary>
tags: [<tag>, <tag>]
timestamp: <ISO 8601 datetime>
---Only type is required by OKF, but include title and description whenever you can infer them confidently. Preserve unknown frontmatter keys when updating an existing concept.
Use type names that explain what the document is, for example:
SpecPlanADRGuideRunbookReferenceArchitecture NoteDomain ConceptResearch Note
Cross-linking
OKF uses standard Markdown links between concepts to express relationships. Create and maintain these cross-links deliberately so agents can traverse related knowledge.
Use cross-links for durable relationships such as:
- specs that implement or supersede other specs
- ADRs that decide, constrain, or supersede specs and architecture notes
- runbooks that operate systems described by architecture or reference concepts
- guides that explain concepts in
domains/,reference/, orarchitecture/ - roadmap items that point to their current spec, ADR, or delivery notes
Prefer bundle-relative absolute links, such as /specs/auth-redesign.md, when linking within the OKF bundle. Use relative links only when they are clearer and stable.
Add links in both directions when both concepts benefit from traversal. For example, a spec should link to the ADR that constrains it, and the ADR should link back to the affected spec or architecture concept.
Do not invent relationships. If a link target is plausible but unsupported by the repo or user context, leave it out or ask for clarification.
index.md files normally contain no frontmatter. The bundle-root ./docs/index.md may include frontmatter only when declaring the OKF version, for example:
---
okf_version: "0.1"
---/okf read workflow
Use this read-only workflow when the user asks to load OKF context, understand the project before work, inspect the roadmap, review decisions, or prepare for a task in a repo that already has an OKF bundle.
- Locate the OKF bundle.
- Use
./docsunless the user names another bundle root. - If
./docs/index.mdis missing, report that no OKF bundle was found and suggest/okf initif appropriate. - Do not edit files, update logs, or create new documents during
/okf read.
- Use
- Read the top-level map.
- Read
./docs/index.md. - Read
./docs/specs/index.mdwhen present because it is the roadmap. - Read
./docs/adrs/index.mdwhen present to identify relevant decisions. - Skim other section indexes that appear relevant to the user's task, such as
architecture/,guides/,reference/,runbooks/, ordomains/.
- Read
- Follow relevant cross-links.
- Follow Markdown links from the roadmap and relevant indexes into specs, ADRs, architecture notes, guides, runbooks, reference docs, and domain concepts.
- Prefer documents directly related to the user's task, changed files, named features, architecture areas, APIs, migrations, or operational concerns.
- Stop when the context is sufficient for the requested work. Do not exhaustively read the whole bundle unless the user asks for a full audit.
- Report the loaded context.
- Summarize active roadmap items relevant to the task.
- List relevant specs, ADRs, runbooks, guides, references, and domain concepts read.
- Call out constraints, accepted decisions, open questions, stale links, missing docs, or docs gaps.
- Recommend the next source files or docs to inspect before implementation.
/okf init workflow
Use this workflow when the repo does not already have a coherent OKF bundle or the user asks to reorganize existing documentation.
- Confirm the repo state.
- Run
git status --short. - If there are unrelated dirty changes, ask before moving or rewriting docs.
- Identify the default branch if you need to compare historical docs.
- Run
- Inventory existing documentation.
- Search for Markdown docs in
./docs, root-level files, and common documentation locations such asadr/,adrs/,spec/,specs/,plans/,design/,architecture/,notes/,.github/, and package subdirectories. - Include root
README.md,AGENTS.md,CONTRIBUTING.md, and similar project-level files in the inventory, but do not move root files that tools or humans expect at the repo root unless the user asks. - Read enough content to classify each document by purpose and freshness.
- If you are uncertain whether a file should be migrated into OKF format or moved into an OKF location, ask the user for clarification before moving or rewriting it.
- Search for Markdown docs in
- Plan the bundle shape.
- Use the required sections above.
- Add optional sections only when existing docs or repo needs justify them.
- Prefer
git mvfor file moves when the repo is under git. - Preserve useful history and content. Avoid deleting docs unless they are duplicates and the retained location is clear.
- Normalize documents into OKF concepts.
- Add missing frontmatter to non-reserved Markdown files under
./docs. - Convert plans and specs into
./docs/specs/. - Convert ADRs into
./docs/adrs/. - Create cross-links between related specs, ADRs, guides, runbooks, reference docs, architecture notes, and roadmap entries.
- Use bundle-relative links from the docs root when stable, such as
/specs/my-plan.md. - Fix links affected by moves when practical.
- Add missing frontmatter to non-reserved Markdown files under
- Create indexes and logs.
- Write
./docs/index.mdas the top-level roadmap and navigation page. - Write
./docs/specs/index.mdas the roadmap for planned and completed work. - Write
index.mdfor every created optional section. - Create
log.mdfiles at the root,specs/,adrs/, and other sections that receive substantive changes. - Log initialization with an ISO
YYYY-MM-DDheading and concise bullets.
- Write
- Update AGENTS.md.
- Add clear instructions that agents should read
./docs/index.mdbefore substantial work. - Tell agents to follow links into relevant specs, ADRs, runbooks, and domain docs.
- Tell agents to run
/okf updateor manually update the OKF bundle after substantial work, PRs, architecture decisions, behavior changes, or docs-moving work. - Tell agents to keep
./docs/specs/index.mdas the roadmap and add ADRs for durable architecture decisions. - Keep project-specific AGENTS.md instructions intact.
- Add clear instructions that agents should read
- Validate.
- Run
python <skill-dir>/scripts/validate_okf.py <repo-root>when this skill's helper script is available. - Check every non-reserved Markdown file under
./docshas parseable YAML frontmatter with non-emptytype. - Check reserved
index.mdandlog.mdfiles match OKF structure. - Check important moved links.
- Run available docs lint or tests if the repo has them.
- Run
- Report.
- Summarize exactly what changed, including files moved, files created, files updated, and files intentionally left in place.
- List AGENTS.md instruction changes.
- Note validation performed and any remaining docs gaps or user follow-ups.
/okf update workflow
Use this workflow near the end of a session, feature branch, or PR.
- Determine what changed.
- Review
git status --shortand relevant diffs. - Read recent commits or PR context if available.
- Identify new behavior, public APIs, architecture decisions, migrations, operational changes, product decisions, and completed or changed plans.
- Review
- Read the current OKF map.
- Read
./docs/index.md. - Read
./docs/specs/index.md. - Read relevant ADRs, specs, runbooks, or domain docs before editing.
- Read
- Update the right concepts.
- Update existing documents when the concept already exists.
- Create new concept documents only for durable knowledge worth preserving.
- Add or update ADRs for architecture decisions with lasting consequences.
- Update specs when scope, status, acceptance criteria, rollout, or implementation details changed.
- Update runbooks, guides, or reference docs when operators or future agents need the information.
- Maintain navigation and cross-links.
- Update affected
index.mdfiles so readers can discover new or changed concepts. - Keep
./docs/specs/index.mdcurrent as the roadmap. - Add or refresh cross-links between related specs, ADRs, guides, runbooks, reference docs, architecture notes, and roadmap entries.
- Add reciprocal links when both documents benefit from traversal.
- Update affected
- Maintain logs.
- Add a newest-first entry to the nearest relevant
log.mdfiles. - Include the date, what changed, and links to updated concepts.
- Keep log entries factual and brief.
- Add a newest-first entry to the nearest relevant
- Validate.
- Run
python <skill-dir>/scripts/validate_okf.py <repo-root>when this skill's helper script is available. - Re-check OKF conformance for changed docs.
- Run docs lint/tests when available.
- Run
- Report.
- Summarize exactly what changed, including concepts created, concepts updated, indexes refreshed, and logs updated.
- Note validation performed and any remaining docs gaps or user follow-ups.
AGENTS.md snippet
Adapt this snippet during /okf init:
## Open Knowledge Format docs
This repository maintains an [OKF](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) bundle at `./docs`.
- Use `/okf read` when available, or read `./docs/index.md` directly before substantial work, to understand the current documentation map.
- Follow cross-links into relevant specs, ADRs, runbooks, guides, architecture notes, reference docs, and domain docs before changing related code.
- Keep `./docs/specs/index.md` current as the roadmap for active, planned, blocked, and completed work.
- Add or update ADRs in `./docs/adrs` for durable architecture decisions.
- After substantial work, PRs, behavior changes, architecture decisions, migrations, or documentation moves, update the OKF bundle and add concise entries to the relevant `log.md` files.
- Maintain Markdown cross-links between related OKF concepts so future agents can traverse decisions, specs, architecture, runbooks, guides, and references.
- Every non-reserved Markdown file under `./docs` should have OKF frontmatter with at least a non-empty `type` field. `index.md` and `log.md` are reserved navigation/history files.Helper scripts
scripts/validate_okf.py: validates the required OKF structure, concept frontmatter, reservedindex.mdandlog.mdrules, log date headings, and local Markdown links.
Validation checklist
Before finishing, verify:
./docs/index.mdexists and points to the main sections../docs/log.mdexists and has newest-firstYYYY-MM-DDentries../docs/specs/index.mdexists and serves as the roadmap../docs/specs/log.mdexists../docs/adrs/index.mdexists../docs/adrs/log.mdexists.- Every non-reserved
./docs/**/*.mdfile has frontmatter withtype. - Moved or newly created docs have useful
titleanddescriptionfields when known. - Important cross-links still resolve or are intentionally forward references.
- New or changed durable relationships are represented with Markdown links between relevant concepts.
- AGENTS.md tells future agents how to consume and maintain the OKF bundle.
When to ask the user
Ask before:
- Moving root-level files that common tools expect, such as
README.md,CONTRIBUTING.md, orAGENTS.md. - Deleting documentation instead of preserving or superseding it.
- Inventing product direction, architecture rationale, or roadmap commitments that are not supported by the repo or the user's instructions.
- Choosing between two plausible documentation taxonomies when the choice affects long-term navigation.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

