OKF Bundle Index

Audit and repair index.md files throughout an Open Knowledge Format (OKF) v0.1 knowledge bundle tree.

For the full OKF specification, see load_skill(name: "okf-bundle-setup/references/okf-spec-summary.md").

Prerequisites

Inputs

The skill accepts an optional bundle root path argument:

Input Example Behaviour
(none) "check my bundle index links" Use ~/.agents/knowledge/ as the bundle root
Explicit path "fix index links in docs/catalog" Use the given path as the bundle root

OKF index.md Rules (reference)

These rules govern every index.md in the bundle tree:

Procedure

Execute these phases in order.

Phase 1 — Resolve the bundle root

  1. If no path was given, set BUNDLE_ROOT to ~/.agents/knowledge/.
  2. If an explicit path was given, resolve it against the current working directory.
  3. Verify the directory exists: 
    [[ -d "$BUNDLE_ROOT" ]] || { echo "Bundle root not found: $BUNDLE_ROOT"; exit 1; }

Phase 2 — Discover all auditable directories

Find every directory in the bundle tree that should have an index.md. This includes the bundle root and all sub-bundle directories.

Exclude:

find "$BUNDLE_ROOT" -type d \( \
    -name '.*' -o -name assets -o -name samples \
    -o -name references -o -name scripts \
    -o -name templates -o -name archive \
  \) -prune -o -type d -print | sort

Phase 3 — Audit each directory

For each directory found in Phase 2, run:

bash <skill-dir>/scripts/audit-index.sh "$DIR"

Output format

=== AUDIT: <dir-path> ===
INDEX: EXISTS | MISSING
[WARNING: index.md has YAML frontmatter (violates OKF §6)]

--- BROKEN LINKS ---
<link-path>
(none)

--- MISSING ENTRIES ---
CONCEPT|<filename>|<title>|<description>
SUB-BUNDLE|<dirname>/|<title>|
(none)

Collect all audit results before proceeding to fixes. This gives a complete picture and avoids unnecessary re-scans.

Phase 4 — Fix: Create missing index.md files

For any directory where the audit reports INDEX: MISSING, generate a fresh index.md using the rebuild script:

bash <skill-dir>/scripts/rebuild-index.sh "$DIR" > "$DIR/index.md"

The rebuild script:

After generating, review the output and adjust if needed (e.g., add descriptive prose, reorder entries, group by theme).

Optional title override:

bash <skill-dir>/scripts/rebuild-index.sh "$DIR" "Custom Title" > "$DIR/index.md"

Phase 5 — Fix: Repair broken links

For each broken link found in Phase 3:

  1. Search for the target — it may have been renamed or moved: 
    find "$BUNDLE_ROOT" -name "$(basename "$BROKEN_PATH")" -not -path '*/.*'
  2. If found at a new location — update the link path in index.md to the correct relative path.
  3. If truly deleted — remove the entire entry line from index.md.

Use the edit tool for surgical link fixes. If many links are broken, regenerate the entire index.md via rebuild-index.sh instead.

Phase 6 — Fix: Add missing entries

For each missing entry reported in Phase 3, add a properly formatted line to the directory’s index.md.

Concept files — use the title and description from the audit output:

* [<title>](<filename>) - <description>

If no description was reported, either omit the ` - ` suffix or generate a brief one by reading the file's content.

Sub-bundle directories — use the title from the audit output:

* [<title>](<dirname>/index.md)

Insertion position

Phase 7 — Re-audit to verify

Re-run the audit script on every directory that had issues:

bash <skill-dir>/scripts/audit-index.sh "$DIR"

All directories should now report:

If any issues remain, repeat Phases 5–6 for those directories.

Phase 8 — Log changes

If any changes were made, record them in the bundle root’s log.md.

Preferred — use the merge-log-entry.sh script from agentfs-setup:

bash ~/.agents/skills/agentfs-setup/scripts/merge-log-entry.sh \
  "$BUNDLE_ROOT/log.md" \
  "* **Update**: Audited index.md files — fixed N broken link(s), added M missing entry/entries, created K new index file(s)."

Manual alternative (if okf-bundle-gen is not available) — prepend a dated entry to log.md in reverse chronological order (newest ## YYYY-MM-DD section first):

TODAY="$(date +%Y-%m-%d)"
{
  head -2 "$BUNDLE_ROOT/log.md"              # preserve heading + blank line
  echo "## $TODAY"
  echo ""
  echo "* **Update**: Audited index.md files — fixed N broken link(s), added M missing entry/entries, created K new index file(s)."
  echo ""
  tail -n +3 "$BUNDLE_ROOT/log.md"           # existing entries
} > "$BUNDLE_ROOT/log.md.tmp"
mv "$BUNDLE_ROOT/log.md.tmp" "$BUNDLE_ROOT/log.md"

If no changes were made (all audits clean), skip logging.

Quality Checklist

After completing all phases, confirm:

Example

Before

~/.agents/knowledge/
├── index.md              ← links to deleted-concept.md (broken)
│                           missing entry for new-concept.md
├── new-concept.md        ← not listed in index.md
├── log.md
└── session-alpha/        ← sub-bundle
    ├── index.md          ← missing entry for design.md
    ├── overview.md
    └── design.md         ← not listed in session-alpha/index.md

Audit output

=== AUDIT: ~/.agents/knowledge ===
INDEX: EXISTS

--- BROKEN LINKS ---
deleted-concept.md

--- MISSING ENTRIES ---
CONCEPT|new-concept.md|New Concept|A recently added concept

=== AUDIT: ~/.agents/knowledge/session-alpha ===
INDEX: EXISTS

--- BROKEN LINKS ---
(none)

--- MISSING ENTRIES ---
CONCEPT|design.md|Design|System design decisions

After

~/.agents/knowledge/
├── index.md              ← broken link removed, new-concept.md added
├── new-concept.md
├── log.md                ← updated with audit entry
└── session-alpha/
    ├── index.md          ← design.md entry added
    ├── overview.md
    └── design.md

Supporting Files

Skill directory: ~/.agents/skills/okf-bundle-index

Cross-skill dependencies

Run okf-bundle-index after okf-bundle-gen or okf-bundle-harvest to ensure all index entries are present and links are valid in ~/.agents/knowledge/. This catches gaps such as a new sub-bundle not listed in the root index.md, or concept files added without corresponding index entries.

Changelog

See CHANGELOG.md for version history.