SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsokf-site-kit

okf-site-kit

Frontend & websites

View repository

Updated 10-15 21:09

About this skill

okf-site-kit

The key words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY in this skill are to be interpreted as described in BCP 14 (RFC 2119, RFC 8174) when, and only when, they appear in all capitals.

Generate a browsable website from an Open Knowledge Format bundle. OKF (Google's open spec for agent-readable knowledge) deliberately ships no required tooling — a bundle is just markdown with YAML frontmatter — which means "browsable" is left to consumers. This skill is that consumer: assets/okf_site.py (stdlib-only) reads any OKF bundle and emits a complete Astro + Starlight static-site project with search, navigation, and OKF-aware presentation. The bundle stays the canonical knowledge; the site is a generated view of it, regenerated whenever the bundle changes.

Locating this skill's helpers (do this first). The steps below run bundled scripts. You execute from the target repo, not from this skill's directory, so a path written relative to this skill will not resolve. Resolve the base directory once and use it everywhere — including in any subagent prompt, which MUST receive the literal absolute path:

SKILL_DIR="<this skill's base directory>"   # your harness provides it when the skill loads
# If you don't have it, discover it:
SKILL_DIR=$(find ~/.claude ~/.config ~/.agents -type d -name 'okf-site-kit' 2>/dev/null | head -1)
test -d "$SKILL_DIR/assets" || test -d "$SKILL_DIR/scripts"   # verify before proceeding

Ground rules

  • The bundle is read-only. The generator MUST NOT mutate the source bundle, because the bundle belongs to its producer and the site is disposable output. When the scan finds problems worth fixing at the source (missing type, broken links), surface them to the user and fix the bundle only if they ask.
  • Tolerance over rejection. Per the OKF spec's consumer rules, unknown types, extra frontmatter keys, missing optional files, and broken links MUST degrade gracefully. The generator renders everything it can and prints WARN: lines for the rest — pass the warnings on, don't suppress them.
  • Spec tracking. The generator targets OKF v0.1. If the spec has moved (check references/okf-spec.md for the URL and update rule), you SHOULD update the generator before emitting a stale dialect.

Workflow

Python interpreter. Most commands in this skill and its references are written with python3. Find the interpreter once, before the first of them. If $SKILL_PYTHON is set, use it. Otherwise, on macOS, if command -v python3 prints /usr/bin/python3 and xcode-select -p fails, that python3 is the install stub: skip it without running it. Use the first of python3, python and py -3 that is not skipped and for which <interpreter> -c 'import sys; sys.exit(sys.version_info < (3, 10))' exits 0. Write the interpreter you found in place of python3 in every command, and in any Bash(...) permission rule you suggest. Commands that start with uv run or {python} keep their own form. In a session resumed under a Bash(...) allowlist, skip this lookup and use the interpreter that the allowlist names. If none passes, follow this skill's own fallback for running without Python where it gives one; otherwise stop and tell the user that this skill needs Python 3.10 or newer.

  1. Locate and inspect the bundle. The bundle root is the directory whose index.md (or concept tree) the user means — for bundles made by the feynman-walkthrough skill it's the knowledge root (e.g. docs/knowledge/). Run python3 "$SKILL_DIR/assets/okf_site.py" inspect <bundle> and read the report: concept count and routes, declared okf_version, and conformance warnings. Relay warnings that the user can act on (concepts missing type, files without frontmatter).
  2. Generate the site. python3 "$SKILL_DIR/assets/okf_site.py" generate <bundle> --out <dir> with flags from references/parameters.md: --title (defaults to the root index's H1), --tagline, --base /<repo> + --site https://<user>.github.io + --deploy-workflow when the target is GitHub Pages. The output is a self-contained project — nothing in it references the skill.
  3. Build and verify. cd <dir> && npm install && npm run build MUST complete with zero errors; treat generator WARN: lines about unresolved links as content issues to report. Where a browser is available, npm run preview and check the two pages that prove the generation: the homepage (hero, one card per section, working links) and one concept page (type badge, tags, metadata panel, rewritten links, table of contents). Fix and regenerate until clean.
  4. Deliver. Hand over the built site the best way the surface allows: the project directory (plus dist/ for the static build), a rendered artifact of a key page when the harness supports it, or a pushed branch with the deploy workflow when the user wants GitHub Pages. State plainly which bundle warnings remain unfixed.
  5. Regenerate on change. The site is disposable output: when the bundle changes, rerun generate … --force with the same flags. It rebuilds src/content/docs/ and public/bundle-assets/ and rewrites the scaffolding files (astro.config.mjs, package.json and the rest listed in references/parameters.md), so hand-edits to them are lost; tell the user so before regenerating. For continuous publishing, the emitted --deploy-workflow rebuilds on every push to main.

Output style. Write reports and explanations for the user in about 80% ASD-STE100 Simplified Technical English. Use short sentences, common words, active voice and one action per step. This style is for prose to the user, not for the code, prompts or files that this skill makes.

What the generator handles

Every OKF bundle dialect observed in the wild is covered — the survey, with sources and per-variation handling rules, is in references/bundle-variations.md:

  • Google's sample bundles (ga4, stackoverflow, crypto_bitcoin in the spec repo): block-list tags, folded multi-line descriptions, quoted timestamps, .md-suffixed relative links, no okf_version, no log.md, non-markdown assets (viz.html), trailing-underscore filenames, H1-sectioned bodies.
  • Spec-canonical bundles: okf_version in the root index frontmatter, log.md update history (becomes the site's Changelog), bundle-absolute /dir/file.md links, inline [a, b] tag lists.
  • Producer-extended bundles (e.g. feynman-walkthrough's explainers): arbitrary extra frontmatter keys including block lists of dicts — rendered generically in the metadata panel, never dropped.
  • Violations, gracefully: concepts without frontmatter or without type render as generic concepts with a warning; unresolvable links are left as written and reported; an empty directory tree fails inspect with INSPECT_RESULT: EMPTY instead of emitting a hollow site.

The emitted site

  • Homepage — splash hero (title, tagline from the root index's first paragraph or --tagline) with a link card per top-level section, descriptions lifted from the root index's own link annotations.
  • One page per concept — OKF metadata panel up top (color-coded type badge, tag chips, resource link, updated timestamp, producer-defined keys), body with internal links rewritten to site routes, assets served from bundle-assets/, headings normalized so the page outline stays valid.
  • Section pages — authored index.md listings where the bundle has them, synthesized listings where it doesn't, labeled "Overview" in the sidebar.
  • Changelog — from root log.md when present.
  • For free from Starlight: full-text search (Pagefind), light/dark theme, mobile layout, table of contents, sitemap-ready config.

Verify checklist

The build itself is the main gate (npm run build fails on broken pages), backed by the generator's own report. Before calling it done, confirm: build exits 0; the homepage links resolve (spot-check one card); one concept page shows badge + panel + rewritten link; WARN: lines have been either fixed or reported to the user. The generator's unit suite (assets/test_okf_site.py) is the regression net when modifying the generator itself.

Extending this skill

The generator is one file by design — parsing, routing, transforms, and emission are separate sections, each unit-tested. To support a future OKF version or a new bundle dialect, add a fixture to the test suite first, then extend the parser/transform, then document the variation in references/bundle-variations.md. To restyle the output, edit the embedded CSS/scaffold constants — the emitted project itself is plain Astro + Starlight and can also be customized after generation.