okf-repo-organizer

name	okf-repo-organizer
description	Organize a repository, folder, or knowledge corpus into generic Open Knowledge Format (OKF) bundles. Use when you are asked to convert or normalize repo files and folders to OKF, add OKF index/log/concept frontmatter, choose bundle boundaries, migrate idea/project/doc folders into OKF-style structure, or validate generic OKF conformance.

OKF Repo Organizer

Overview

Use this skill to make an existing repo or folder easier for humans and agents to traverse as OKF. Keep the skill generic: OKF is markdown plus YAML frontmatter, not a domain-specific taxonomy.

Reference

Read references/SPEC.md from this skill before changing files. Treat it as the only OKF format reference. Do not assume the target repository contains an okf/ directory or its own copy of the spec.

Do not invent stricter required fields than the spec. For generic OKF conformance, every non-reserved .md concept document needs parseable YAML frontmatter with a non-empty type. title, description, resource, tags, and timestamp are recommended, not mandatory.

Add frontmatter minimally and let content drive it. Always include type; add a recommended field only when it carries information the document body and the file's location do not already make obvious. Prefer the smallest frontmatter that satisfies OKF over a complete one.

Workflow

1. Establish scope and bundle boundaries.

   • Use the path the user names. If none is named, inspect the repo and choose the smallest sensible scope.
   • Prefer treating knowledge-oriented folders as OKF bundles. Do not force a whole software repo to be one OKF bundle unless the user asks for that or the repo is already markdown-first.
   • A nested folder can be its own bundle when it has independent context, for example an ideas/idea_example/ folder with its own index.md, log.md, and concept files.

2. Inventory before editing.

   • Use rg --files to inspect Markdown, source, asset, generated, and vendor paths.
   • Preserve user content and existing frontmatter keys. Move or rename files only when it improves OKF traversal and does not break obvious project conventions.
   • Ignore generated and dependency folders such as .git/, node_modules/, .venv/, dist/, and build/ unless the user explicitly wants them modeled.

3. Organize the bundle.

   • Add or update index.md at the bundle root and important subdirectories for progressive disclosure. Keep index files as plain Markdown; only a bundle-root index.md may use frontmatter, and only for okf_version.
   • Add or update log.md when the folder needs chronological history. Use ## YYYY-MM-DD date headings, newest first.
   • For each non-reserved .md concept file, add or normalize frontmatter. Only type is required; add the other keys only when they earn their place:

---
type: <self-explanatory type>        # required
title: <human-readable title>        # recommended
description: <one-sentence summary>   # recommended
tags: [optional, tags]                # optional
# add resource, timestamp, or other keys only when they carry non-redundant information
---

• Keep frontmatter minimal and content-driven. Do not add a field that merely duplicates the body or the file's position. For example, omit timestamp on a chronological, newest-first log whose top ## YYYY-MM-DD heading already states the last-change date, and omit created when the oldest in-body entry already states it.
• Keep type short and descriptive, such as Idea, Project, Template, Reference, Runbook, Dataset, Note, or Decision. Do not create a central type registry.
• Leave code, data, images, PDFs, and other non-Markdown assets in normal project locations. When useful, create a concept .md that describes or links to the asset instead of modifying the asset.
• Prefer bundle-relative Markdown links that begin with / when links should survive file moves. Relative links are fine for local neighbors.
• For repeatable project workflows, keep templates and instances semantically distinct. A useful generic pattern is projects-folder/templates/<TemplateName>/ for reusable templates and projects-folder/<ProjectName>/ for instantiated projects.

4. Validate.
   • Run bundled scripts from this skill's root directory, using paths relative to the directory that contains this SKILL.md. Pass the bundle root as an absolute path when the target repo is not the current working directory.
   • Run the bundled validator on every OKF bundle root you changed. Prefer uv run so the script can install its declared Python dependency from the inline PEP 723 metadata:

uv run scripts/validate_okf_bundle.py /absolute/path/to/bundle-root

• If uv is unavailable and the environment already has Python 3.11+ plus PyYAML, run it directly:

python scripts/validate_okf_bundle.py /absolute/path/to/bundle-root

• If an OKF reference implementation is available and you want to reuse its parser, pass it explicitly. This is optional; the validator also works with PyYAML when the reference implementation is unavailable.

uv run scripts/validate_okf_bundle.py /absolute/path/to/bundle-root --okf-src /path/to/okf/src

• The validator reuses enrichment_agent.bundle.document.OKFDocument.parse from okf/src when available, then applies the generic conformance rules from this skill's bundled references/SPEC.md. It does not call the stricter enrichment-agent document validator because that validator requires recommended fields that generic OKF does not require.

5. Finish with a concise report.
   • List the bundle root(s), important files changed, and validator result.
   • If validation fails, fix the OKF format issues before finishing unless the user explicitly asks you to stop.
   • Call out deliberate non-OKF areas, such as source-only directories or a top-level README kept outside the selected bundle.