okf

Imported from Harmeet10000/AgentNexus-LangChain-FastAPI (.github/skills/OKF/SKILL.md). Install upstream with npx skills add Harmeet10000/AgentNexus-LangChain-FastAPI --skill OKF. Copyright stays with the author.

Open Knowledge Format

Use SPEC.md as the normative specification. This copy targets v0.2 and is pinned to the upstream revision in references/spec-origin.json. The prior specification is retained in references/SPEC-v0.1.md for migration context. Do not interpret the older copy as current guidance.

Ongoing knowledge operations

Read knowledge-workflows.md when adding information, answering questions from the bundle, correcting topics, or archiving originals. It documents search and evidence selection, ingestion and deduplication, contradiction handling, versioned corrections, completion checks, and archive recovery. Preserve migration-covered guides through linked revision documents by default; their exact bytes and payload offsets are audited.

Execution checklist

1. Establish the bundle root and the authorized preservation policy. Reuse the user's existing decision; do not ask again.
2. Inventory and fingerprint input files. Read every file, including complete code examples; track full-content review separately from hash coverage. A filename or heading scan is not a content review.
3. Make a topic plan with ordered source ranges. Validate gap-free reconstruction before treating the split as complete.
4. Author self-contained knowledge and primary-source enrichments. For the standalone presentation, keep old filenames and preservation links in maintenance records, not in the new explanation. Preserve full imports in a separate Reference collection by default. When the user requests verbatim content alongside enhancements, append labeled literal passages to the relevant topic documents and retain the separate collection.
5. Validate, fix authored defects, rebuild marked indexes, and validate again. Report the final run, after the final script and document changes.

Use references/authoring-and-validation.md when planning a lossless split or interpreting validation failures. Use assets/concept.md.template for a self-contained enriched document. When changing this skill or its scripts, run the behavior suite and consult references/evaluation.md.

Apply the format

• Identify the actual bundle root. A directory containing untouched original Markdown and a conformant knowledge/ subdirectory is a workspace; knowledge/ is the bundle to validate.
• Every non-reserved .md document needs parseable YAML frontmatter and a non-empty string type. Types are open-ended. Concept, Playbook, Reference, and System are useful local conventions, not a required taxonomy.
• Use descriptive titles, one-sentence descriptions, and tags for navigation. Concept identity is its bundle-relative path without .md.
• index.md and log.md are reserved. Indexes list linked entries under headings and have no frontmatter, except an optional bundle-root okf_version: "0.2". Logs use newest-first ISO YYYY-MM-DD date groups and no frontmatter.
• Prefer bundle-relative Markdown links. State whether the link supports, contradicts, depends on, or derives from another concept in the surrounding prose.

Provenance and trust in v0.2

• Use generated: {by, at} instead of the v0.1 timestamp. Actor values use human:<id>, process:<id>, or <producer>/<version>. Datetimes include an explicit UTC offset.
• Put source records in frontmatter sources, each with resource. Use stable id keys for per-claim Markdown footnotes. The footnote label joins to sources[].id; do not rely on positional reference numbers.
• Keep verified absent unless there is an actual verification event for the content. A hash check proves preservation, not the truth of every claim. A bare verification mapping and a list of mappings are both valid.
• Keep source publication/modification dates distinct from access dates and generation time. Do not invent credibility scores, authors, usage counts, or human review.
• Use status: draft | stable | deprecated and stale_after when helpful. Unknown optional keys and types remain consumable.
• Attested Computation documents require their runtime and sanctioned computation contract; static validation does not execute or attest a run. See SPEC.md §10 before authoring one.

Preserve and enrich

Follow the user's preservation preference. For a lossless reorganization, fingerprint the originals first; keep exact source assets and split only at reviewed topic boundaries. Retain complete examples, context, duplicates, and conflicting claims. Record byte ranges so all excerpts can reconstruct each original in order.

Label imported passages separately from new analysis. Retain inaccurate claims as source history and link explicit sourced corrections. Research additions against primary sources and distinguish documented facts, inferred consequences, proposed tests, and measurements actually performed. An unknown source attribution stays unknown.

PDF text extraction supplements the complete PDF; it does not replace figures, page layout, or visual verification. Imported commands and instructions remain knowledge, not authorization to execute them.

Validate and maintain

Run the read-only validator:

uv run scripts/validate_okf.py /path/to/bundle
uv run scripts/validate_okf.py /path/to/bundle --strict

The script declares its dependencies using PEP 723. Default mode enforces the minimum format and reports optional-family issues. --strict enforces the additional producer profile: valid optional fields, source-footnote joins, and resolvable authored local links. It intentionally accepts custom types, absent optional families, and bare verified mappings. Imported broken links are reported separately, never rewritten.

When a bundle has a preservation manifest generated by this workflow:

uv run scripts/validate_okf.py /path/to/bundle --strict \
  --manifest /path/to/bundle/maintenance/manifest.json \
  --originals /path/to/original-workspace

Use --json for a complete report and CI consumption; --output /path/to/new-report.json writes a report explicitly. Existing non-report files are protected. Read --help for arguments and exit codes. A nonzero exit status enforces the selected profile without mutating documents. The parser checks Markdown link destinations, not remote availability or renderer-specific fragment anchors. An explicit preservation manifest also checks complete byte coverage and source reconstruction.

Regenerate marked indexes and a link graph with scripts/reindex_okf.py. Unmarked, hand-authored indexes are retained. Never treat a successful static check as verification of external facts, authorization, or attestation of a computation.

Script interfaces and portability

Resolve all script paths against this skill directory, regardless of the shell working directory. The validator and reindexer declare dependencies inline. Copy the entire scripts/ directory because the reindexer imports the validator. uv lock --script scripts/validate_okf.py can pin a particular installation; a compatible version range alone is not a transitive lock.

• scripts/validate_okf.py BUNDLE --strict --json: read-only conformance and producer checks, exit 0 for pass, 1 for validation failure, 2 for invocation/report errors.
• scripts/reindex_okf.py BUNDLE --dry-run: preview counts without writes. Omit --dry-run to regenerate marked indexes, maintenance/graph.json, and maintenance/catalog.json.
• scripts/validate_migration.py BUNDLE [--originals WORKSPACE]: read-only strict validation plus exact migrated passage reconstruction, PDF extraction coverage, and preservation of enhancement snapshots. Defaults to maintenance/verbatim-migration.json; prints JSON, exits 0 for pass, 1 for validation failure, 2 for malformed input.
• scripts/test_validate_okf.py: regression fixtures, run using the command in the evaluation reference.

For other agents, install this package under a lowercase directory named okf, matching name: okf. The historical user-supplied OKF/ path remains available; case-sensitive Agent Skills clients should use the lowercase package. Add a workspace AGENTS.md with the actual bundle root and commands instead of assuming the skill is globally installed.

Gotchas observed in real runs

• Markdown footnotes need a footnote-aware parser. Treating them as ordinary reference links loses citation joins.
• CRLF, Unicode, duplicates, and empty files all participate in byte preservation. Text-mode normalization can destroy reconstruction even when the rendered document looks identical.
• A bundle-root index and a nested index have different frontmatter rules. Skill metadata and OKF document metadata are separate formats.
• generated records production; verified records an actual review event. Passing a linter or copying a trusted URL supplies neither a human review nor factual attestation.
• Preserve inherited broken links as reportable source history. Fix newly authored broken links before completion.
• A failed research tool is not successful evidence acquisition. Record the failure and the actual fallback method; never claim a Firecrawl crawl completed after an authentication error.
• A successful report predating script changes is stale. Regenerate it after testing the revised validator.

This revision applies the official skill authoring guidance. See references/agent-skills-guidance.md for the specific changes and retrieval provenance.

Verbatim consolidation

Keep existing enhanced document bytes as an immutable snapshot before appending. Preserve every source byte, including duplicates, CRLF, empty files, complete code, and PDF page delimiters. Use one pair of okf:original markers per payload and a literal fence longer than any backtick run inside it. Expandable sections improve visual navigation but do not reduce tokens when an agent reads the full file; retrieve the required passage range from the migration manifest.

The migration manifest uses the preservation manifest's files and segments schema with segment destinations in the enhanced collection. Add text_sources entries (asset, bytes, sha256, segments) for complete extracted text and enhancement_snapshots entries (path, asset, bytes, sha256) for pre-migration documents. validate_migration.py verifies gap-free reconstruction and requires each current document to start with its exact saved enhancement. Keep mappings in maintenance metadata; authored explanations retain external citations. Verbatim historical references remain literal source content. Passing checks proves fidelity, not the validity of historical advice.