agentleFS
gannonhgannonh/kata/.agents/skills/okf/SKILL.md

okf

Skill67 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

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
  1. Distinctive:

    Use this skill to read, initialize, or update an Open Knowledge Format bundle for a repository.

    line 8
  2. Very specific:

    Before editing, read references/SPEC.md from this skill directory.

    line 10
  3. Distinctive:

    When validating a bundle, use the bundled helper when available:

    line 12
  4. Very specific:

    Use --strict-links when broken local Markdown links should fail validation instead of warn.

    line 18
  5. Distinctive:

    Create and maintain these sections in every repository OKF bundle:

    line 32
  6. Distinctive:

    Create additional sections when the repository has durable knowledge that belongs there.

    line 52
  7. Distinctive:

    Use the repo's existing language.

    line 61
  8. Very specific:

    Every Markdown file under ./docs is a concept document unless its filename is index.md or log.md.

    line 65
  9. Very specific:

    Only type is required by OKF, but include title and description whenever you can infer them confidently.

    line 79
  10. Distinctive:

    Use type names that explain what the document is, for example:

    line 81
  11. Distinctive:

    Use cross-links for durable relationships such as:

    line 97
  12. Very specific:

    Prefer bundle-relative absolute links, such as /specs/auth-redesign.md, when linking within the OKF bundle.

    line 105
  13. Distinctive:

    Add links in both directions when both concepts benefit from traversal.

    line 107
  14. Distinctive:

    Do not invent relationships.

    line 109
  15. Distinctive:

    Use this read-only workflow when the user asks to load OKF context, understand the project before work, inspect the roadmap, review …

    line 121
  16. Very specific:

    Use ./docs unless the user names another bundle root.

    line 124
  17. Very specific:

    If ./docs/index.md is missing, report that no OKF bundle was found and suggest /okf init if appropriate.

    line 125
  18. Very specific:

    Do not edit files, update logs, or create new documents during /okf read.

    line 126
  19. Distinctive:

    Read the top-level map.

    line 128
  20. Very specific:

    Read ./docs/specs/index.md when present because it is the roadmap.

    line 130
  21. Very specific:

    Read ./docs/adrs/index.md when present to identify relevant decisions.

    line 131
  22. Distinctive:

    Follow Markdown links from the roadmap and relevant indexes into specs, ADRs, architecture notes, guides, runbooks, reference docs, and …

    line 135
  23. Distinctive:

    Prefer documents directly related to the user's task, changed files, named features, architecture areas, APIs, migrations, or operational …

    line 136
  24. Distinctive:

    Stop when the context is sufficient for the requested work.

    line 137
  25. Distinctive:

    Call out constraints, accepted decisions, open questions, stale links, missing docs, or docs gaps.

    line 142
  26. Distinctive:

    Use this workflow when the repo does not already have a coherent OKF bundle or the user asks to reorganize existing documentation.

    line 147
  27. Distinctive:

    If there are unrelated dirty changes, ask before moving or rewriting docs.

    line 151
  28. Very specific:

    Search for Markdown docs in ./docs, root-level files, and common documentation locations such as adr/, adrs/, spec/, specs/, plans/, …

    line 155
  29. Distinctive:

    Read enough content to classify each document by purpose and freshness.

    line 157
  30. Distinctive:

    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 …

    line 158
  31. Distinctive:

    Use the required sections above.

    line 161
  32. Distinctive:

    Add optional sections only when existing docs or repo needs justify them.

    line 162
  33. Distinctive:

    Prefer git mv for file moves when the repo is under git.

    line 163
  34. Very specific:

    Add missing frontmatter to non-reserved Markdown files under ./docs.

    line 167
  35. Distinctive:

    Create cross-links between related specs, ADRs, guides, runbooks, reference docs, architecture notes, and roadmap entries.

    line 170
  36. Very specific:

    Use bundle-relative links from the docs root when stable, such as /specs/my-plan.md.

    line 171
  37. Distinctive:

    Create indexes and logs.

    line 174
  38. Very specific:

    Write ./docs/index.md as the top-level roadmap and navigation page.

    line 175
  39. Very specific:

    Write ./docs/specs/index.md as the roadmap for planned and completed work.

    line 176
  40. Very specific:

    Write index.md for every created optional section.

    line 177
  41. Very specific:

    Create log.md files at the root, specs/, adrs/, and other sections that receive substantive changes.

    line 178
  42. Very specific:

    Add clear instructions that agents should read ./docs/index.md before substantial work.

    line 182
  43. Distinctive:

    Keep project-specific AGENTS.md instructions intact.

    line 186
  44. Very specific:

    Run python <skill-dir>/scripts/validate_okf.py <repo-root> when this skill's helper script is available.

    line 189
  45. Very specific:

    Check every non-reserved Markdown file under ./docs has parseable YAML frontmatter with non-empty type.

    line 190
  46. Very specific:

    Check reserved index.md and log.md files match OKF structure.

    line 191
  47. Distinctive:

    Check important moved links.

    line 192
  48. Distinctive:

    Run available docs lint or tests if the repo has them.

    line 193
  49. Distinctive:

    Use this workflow near the end of a session, feature branch, or PR.

    line 202
  50. Distinctive:

    Read recent commits or PR context if available.

    line 206
  51. Distinctive:

    Read the current OKF map.

    line 209
  52. Distinctive:

    Read relevant ADRs, specs, runbooks, or domain docs before editing.

    line 212
  53. Distinctive:

    Update the right concepts.

    line 214
  54. Distinctive:

    Update existing documents when the concept already exists.

    line 215
  55. Distinctive:

    Create new concept documents only for durable knowledge worth preserving.

    line 216
  56. Distinctive:

    Add or update ADRs for architecture decisions with lasting consequences.

    line 217
  57. Distinctive:

    Update specs when scope, status, acceptance criteria, rollout, or implementation details changed.

    line 218
  58. Distinctive:

    Update runbooks, guides, or reference docs when operators or future agents need the information.

    line 219
  59. Very specific:

    Update affected index.md files so readers can discover new or changed concepts.

    line 222
  60. Very specific:

    Keep ./docs/specs/index.md current as the roadmap.

    line 223
  61. Distinctive:

    Add or refresh cross-links between related specs, ADRs, guides, runbooks, reference docs, architecture notes, and roadmap entries.

    line 224
  62. Distinctive:

    Add reciprocal links when both documents benefit from traversal.

    line 225
  63. Very specific:

    Add a newest-first entry to the nearest relevant log.md files.

    line 228
  64. Distinctive:

    Keep log entries factual and brief.

    line 230
  65. Distinctive:

    Run docs lint/tests when available.

    line 235
  66. Very specific:

    Every non-reserved ./docs//*.md file has frontmatter with type.

    line 273

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 ./docs bundle 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:

  • Spec
  • Plan
  • ADR
  • Guide
  • Runbook
  • Reference
  • Architecture Note
  • Domain Concept
  • Research 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/, or architecture/
  • 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.

  1. Locate the OKF bundle.
    • Use ./docs unless the user names another bundle root.
    • If ./docs/index.md is missing, report that no OKF bundle was found and suggest /okf init if appropriate.
    • Do not edit files, update logs, or create new documents during /okf read.
  2. Read the top-level map.
    • Read ./docs/index.md.
    • Read ./docs/specs/index.md when present because it is the roadmap.
    • Read ./docs/adrs/index.md when present to identify relevant decisions.
    • Skim other section indexes that appear relevant to the user's task, such as architecture/, guides/, reference/, runbooks/, or domains/.
  3. 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.
  4. 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.

  1. 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.
  2. Inventory existing documentation.
    • Search for Markdown docs in ./docs, root-level files, and common documentation locations such as adr/, 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.
  3. Plan the bundle shape.
    • Use the required sections above.
    • Add optional sections only when existing docs or repo needs justify them.
    • Prefer git mv for 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.
  4. 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.
  5. Create indexes and logs.
    • Write ./docs/index.md as the top-level roadmap and navigation page.
    • Write ./docs/specs/index.md as the roadmap for planned and completed work.
    • Write index.md for every created optional section.
    • Create log.md files at the root, specs/, adrs/, and other sections that receive substantive changes.
    • Log initialization with an ISO YYYY-MM-DD heading and concise bullets.
  6. Update AGENTS.md.
    • Add clear instructions that agents should read ./docs/index.md before substantial work.
    • Tell agents to follow links into relevant specs, ADRs, runbooks, and domain docs.
    • Tell agents to run /okf update or manually update the OKF bundle after substantial work, PRs, architecture decisions, behavior changes, or docs-moving work.
    • Tell agents to keep ./docs/specs/index.md as the roadmap and add ADRs for durable architecture decisions.
    • Keep project-specific AGENTS.md instructions intact.
  7. 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 ./docs has parseable YAML frontmatter with non-empty type.
    • Check reserved index.md and log.md files match OKF structure.
    • Check important moved links.
    • Run available docs lint or tests if the repo has them.
  8. 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.

  1. Determine what changed.
    • Review git status --short and 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.
  2. Read the current OKF map.
    • Read ./docs/index.md.
    • Read ./docs/specs/index.md.
    • Read relevant ADRs, specs, runbooks, or domain docs before editing.
  3. 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.
  4. Maintain navigation and cross-links.
    • Update affected index.md files so readers can discover new or changed concepts.
    • Keep ./docs/specs/index.md current 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.
  5. Maintain logs.
    • Add a newest-first entry to the nearest relevant log.md files.
    • Include the date, what changed, and links to updated concepts.
    • Keep log entries factual and brief.
  6. 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.
  7. 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, reserved index.md and log.md rules, log date headings, and local Markdown links.

Validation checklist

Before finishing, verify:

  • ./docs/index.md exists and points to the main sections.
  • ./docs/log.md exists and has newest-first YYYY-MM-DD entries.
  • ./docs/specs/index.md exists and serves as the roadmap.
  • ./docs/specs/log.md exists.
  • ./docs/adrs/index.md exists.
  • ./docs/adrs/log.md exists.
  • Every non-reserved ./docs/**/*.md file has frontmatter with type.
  • Moved or newly created docs have useful title and description fields 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, or AGENTS.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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.