Skip to content
Skills Library
AI & agents · Building & coding

init

/init

Start OKF v0.2 bundles and local multi-bundle catalogs, configure per-bundle settings, and scaffold concepts or exact Attested Computations. Use for new bundles or catalog setup; use migrate or ingest for existing material and repair for an existing KB.

Repository
okf ↗
Licence
MIT
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Start OKF v0.2 bundles and local multi-bundle catalogs, configure per-bundle settings, and scaffold concepts or exact Attested Computations. Use for new bundles or catalog setup; use migrate or ingest for existing material and repair for an existing KB.

Original author description

Start OKF v0.2 bundles and local multi-bundle catalogs, configure per-bundle settings, and scaffold concepts or exact Attested Computations. Use for new bundles or catalog setup; use migrate or ingest for existing material and repair for an existing KB.

How it works

  1. CLI compatibility preflight
  2. CLI and bundle access
  3. Portable OKF versus local policy
  4. Workflow
  5. Supporting material
  6. Bundle identity and examination scope
  7. Frontmatter order
Original SKILL.md headings · 141 lines, 1,294 words
SKILL.md preview
---
name: init
description: Start OKF v0.2 bundles and local multi-bundle catalogs, configure per-bundle settings, and scaffold concepts or exact Attested Computations. Use for new bundles or catalog setup; use migrate or ingest for existing material and repair for an existing KB.
---

# Initialize an OKF bundle

Use the CLI for writes and checks. Use the domain, scope, and modeling choices already supplied;
choose ordinary defaults for reversible scaffolding. Ask only about unresolved choices that
materially change the requested bundle.


## CLI compatibility preflight

Before CLI-dependent work, run `sh <this-skill-directory>/../../scripts/check-cli.sh`,
resolving the path from this installed SKILL.md, not the working directory. This read-only
check uses the plugin's `cli-compatibility.txt` range and reports the executable on PATH.
If missing, incompatible, or unable to run, stop CLI-dependent work and show its installation
instructions. Never invoke the installer, download a CLI, or update it from this skill.
An explicit user request to install should be handled separately from this workflow.
Only after this check passes may command help resolve syntax differences; help cannot waive
compatibility. Recheck if the executable or PATH changes during the task.

## CLI and bundle access

In multi-step work, set `OKF_BUNDLE` once. One fully qualified example is `okf add notes/hello
<bundle> --type Note`. Before using an unfamiliar command or flag, read its entry in
`references/cli.md`. If the installed version differs or rejects documented syntax, use that
command's `--help` output as the runtime authority.

Inspect bundle content through `okf browse`, `okf search`, `okf list`, and targeted `okf show`. For
text search, use `okf search <bundle> --text "query terms" --limit 10`; the positional is always the
bundle path, never the query. Use `okf list <bundle>` for an unfiltered inventory. For a large
concept, use `okf show <concept-id> <bundle> --outline`, then `okf show <concept-id> <bundle>
--lines <START:END>`.

## Portable OKF versus local policy

- Required for bundle conformance: parseable frontmatter, non-empty `type`, and valid reserved
  `index.md`/`log.md` structures. Unknown custom type strings are valid.
- Recommended: `title`, `description`, applicable `resource`, `tags`, useful Markdown structure, and
  absolute bundle-relative concept links.
- Optional with defined semantics: `sources`, `generated`, `verified`, lifecycle fields, and the
  Attested Computation family.
- `ontology.yaml`, source `kind`/`fingerprint`, and sync metadata are tool extensions. Ontology lint
  is advisory and never changes OKF conformance.

## Workflow

1. Choose bundle boundaries from ownership, update/release cycles, and distribution needs; use
   directories within one bundle when these are shared. For multiple bundles, follow the
   [catalog setup example](references/multi-bundle.md) to create nonoverlapping roots, stable IDs,
   typed defaults, per-bundle settings, and optional machine-local overrides. Keep ordinary paths
   valid; identity alone does not make cross-bundle links relocatable. Qualified catalog IDs are
   CLI targets, not authored Markdown link syntax. For existing separate repositories, use the
   example's sibling-checkout layout and reuse registered IDs; setup does not clone or fetch.
   Run `okf init <bundle>`; it creates an empty ontology sidecar by default. Use `okf init <bundle>
   --no-ontology` when no local ontology is wanted. Confirm that its root index is structurally
   valid with `okf validate <bundle>`; an empty bundle still needs a non-empty `#` heading when
   indexed.
2. If local type rules add value, define them with `okf ontology add <name> <bundle>` and inspect
   them with `okf ontology show <name> <bundle>`. Do not present this sidecar as an OKF registry or
   requirement. Keep exact type strings; unknown types remain portable. For reusable nested types
   or semantic relationships, use the ontology skill's
   [structured authoring example](../ontology/references/structured-authoring.md); structured CLI examples
   describe the YAML inputs and bulk apply workflow. Inspect configured ontology paths before editing.
3. Create ordinary concepts with `okf add <path> <bundle> --type <Type> --body
   @/tmp/concept-body.md`. Add grounded title and description with `--title "Title"
   --description "Summary"`. The file contains Markdown body only;
   unreadable input fails before creating a skeleton. Add a source with `okf edit <concept-id>
   <bundle> --add-source
   "resource=<path>,id=source-1"`. If generation provenance is desired, pass `--generated-by
   <actor>` to add; the CLI supplies the timestamp. Never label agent-authored material
   `human:<id>`.
4. Only for a requested computation, use exact `Attested Computation` with `okf add <path> <bundle>
   --attested --runtime <runtime>`. Read the add/computation sections of `references/cli.md` for
   parameters, inline/file forms, and contract resources. Inspect with `okf computation check
   <concept-id> <bundle>`; this does not execute or attest a run.
5. Add portable Markdown links for relationships. Ontology references may supplement them.
   For cross-bundle sources, preserve the document-relative `resource` and make optional
   `bundle_ref.id`/root-relative `bundle_ref.path` identify the same material. Inspect `okf catalog`
   and check the edge with explicitly scoped `okf links` before relying on it; the setup example
   includes a complete source mapping and checks. Snapshot expectations are optional and must not
   silently replace the ordinary target.
6. Run `okf validate <bundle>`, then advisory `okf lint <bundle> --fail-on never`. Generate indexes
   with `okf docs <bundle> --format index` only when their bodies are generated content or
   replacement is already authorized; the command replaces index prose across the bundle. Preserve
   curated indexes otherwise. Confirm generated indexes with `okf browse <bundle>`.

When local fingerprint tracking is enabled with a source `kind`, review its evidence and run
`okf refresh <concept-id> <bundle> --fail-on skipped` to record the baseline. `okf stale <bundle>
--fail-on any` distinguishes `unrecorded` (no baseline), `missing` (cannot fingerprint), and
`drifted` (changed baseline). Standard kind-less provenance is not fingerprint-checked. Inspect
findings even when a command succeeds: stale defaults to a successful exit on findings, and
`lint --fail-on never` is reporting only. Use `okf lint <bundle> --fail-on warn` when source warnings
must fail a health gate; conformance validation alone does not establish source health.

## Supporting material

`references/` is optional: Markdown files there are concepts; other files are artifacts. Copy only
material within the authorized scope and preserve its provenance. Use `okf artifact list <bundle>`
to inventory its default `references/` directory, or add `--directory <directory>` for another
directory. Resolve paths with `okf artifact resolve <resource> <bundle> --from <concept-id>`;
consult the artifact sections of `references/cli.md` for bounded reads and external-source handling.
Inspection never authorizes execution.

For an authorized artifact copy or authored schema, use `okf artifact put
contracts/x/references/schema.json @/tmp/schema.json <bundle>`. The destination is bundle-relative;
the input file is relative to cwd. Creation is the default; use `--replace` only for an intended
replacement. Writes preserve recorded fingerprints, so review citing concepts before refreshing
them. This command does not execute artifacts or grant permission to copy external material.

Report what was created, validation, and relevant lint findings. Include computation or artifact
details only when those features were used.

## Bundle identity and examination scope

Keep bundle paths and catalog IDs distinct. `OKF_BUNDLE` always selects a path; use the
`--bundle-id <id>` for a registered identity. When a catalog is configured, use `okf catalog` to inspect effective local
registrations, overrides, availability, and per-bundle settings. Catalog paths are relative to
`okf.toml`, locations are relative to the catalog, and machine-local overrides change effective
locations rather than accepting different snapshots. Inspect effective settings before relying on
a per-bundle ontology or view. Equal or nested registered roots are configuration errors.

Registration alone does not authorize catalog-wide traversal. Start with the selected bundle;
request additional bundles explicitly with repeatable `--scope-bundle <id>` or deliberate
`--catalog-scope` when the task requires them. Report requested and examined
scope and unavailable members. Out-of-scope references remain unknown. Ordinary relative paths
retain their meaning across registered boundaries; distributing one bundle alone can break them.
Never infer another bundle from a matching filename or title.

## Frontmatter order

When authoring concept frontmatter, put `type` first. For the matching ontology concept type,
follow `fields` declaration order recursively, including nested objects and objects in lists;
reusable field types use their resolved field order. Put reference-only keys next in reference
declaration order. Put undeclared/custom fields last at each level, preserving their relative
order. Without a matching ontology type, keep the other fields in their authored order.
This is an authoring convention, not an additional OKF conformance requirement.
CLI writes normalize this order. `okf lint <bundle>` reports `frontmatter-order` at warning by
default; `okf lint <bundle> --fix` normalizes the bundle and reports remaining findings. The
bundle lint setting `frontmatter_order` accepts `info`, `warn`, `error`, or `off`; an off rule
is not fixed. Normalization preserves values, list order, body text, and verification metadata;
YAML comments and scalar presentation may normalize.
Files in this package (3)
  • SKILL.md 10 KB
  • references/cli.md 47 KB
  • references/multi-bundle.md 8 KB

Versions

RepositoryScoreLicence
This page · abatyuk/okf100MIT
CodaColaLight/nightmill100Apache-2.0
userKael/rastro100MIT
elalfner/relevo100MIT
duronext/jig100MIT
sh5623/e2e-rail100MIT
Calvin-LLC/skills100MIT
arxdsilva/ai-loops100MIT
stxrmik/antigravity-plus100MIT

Database snapshot: 13.11.2026 · package version 936ff659960d (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100okf
    Use when creating, editing, validating, or structuring Open Knowledge Format (OKF v0.2) bundle files (.agents/bundles/), YAML frontmatter, Attested Computations, provenance footnotes, or Google Cloud Knowledge Catalog okf-bundle trees.
  • 100okf-init
    Creates the standard knowledge/ structure (OKF v0.2 bundle, knowledge/3.0 profile with the layers fragments/, base/ and projections/) in the current repository. Use when the user says "initialize OKF", "create the knowledge folder", "okf init", "scaffold knowledge", "prepare…
  • 100ingest
    Research a repository or directory and author grounded OKF v0.2 concepts with standard provenance. Use for source-code or mixed-artifact research; use migrate for pre-written docs and init for an empty bundle.
  • 100okf-maintain-knowledge
    OKF — Author, maintain, and consume Open Knowledge Format (OKF) knowledge bundles. Use when capturing project knowledge (services, APIs, schemas, decisions) into an OKF bundle, when updating one after code or docs change, or when a repository's OKF bundle should inform the task.…
  • 100okf
    Create, inspect, retrieve, author, revise, enrich, audit, repair, research, analyze change impact, migrate, validate, and maintain knowledge for AI agents as conformant Open Knowledge Format (OKF) bundles. Use for /okf commands; work on an existing OKF bundle; documentation of…
  • 100migrate
    Migrate documents or prior OKF material into one or more OKF v0.2 bundles with structured transformations, preserved provenance, and resumable mappings. Use for authored docs; use ingest for repository research and repair when upgrading an existing bundle in place.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.