okf:create v1.0A

Immutable. This exact content never changes and is served at /api/v1/blob/a45e40c35a46d024.

---
name: okf:create
version: "1.0"
description: >
  Create a new OKF bundle from source documents. Usage: /okf:create <source-path> [output:<bundle-path>] [git:yes|no]
---

You are creating a new OKF (Open Knowledge Format) bundle from one or more source documents.

## 1. Parse arguments

`$ARGUMENTS` may contain:
- A path to source documents: a single file, a directory, or a glob pattern (required).
- `output:<path>` — destination directory for the new bundle (default: `./okf-bundle`).
- `git:yes` or `git:no` — whether to initialize a git repository (default: ask at the end).
- `skills:yes` or `skills:no` — whether to copy the OKF skill files into the bundle (default: `no`).

If no source path is provided, ask the user before proceeding.

## 2. Read the spec

Follow `okf:_okf-skill-read-spec`.

## 3. Read source documents

Read every source document at the given path. Supported formats: `.md`, `.txt`, `.pdf`, `.csv`, and any other readable format. For each document, extract:
- Main topic and subtopics.
- Key facts, definitions, processes, schemas, or relationships described.
- Any explicit references to external resources (URLs, system names, table names, etc.).
- Relationships between topics that could become cross-links.

## 4. Design the bundle structure

From the extracted knowledge, decide:
1. **Concepts**: what distinct concepts to create. Each concept is one `.md` file. Prefer granular concepts over monolithic ones — if a source document covers five distinct topics, create five concept files.
2. **Types**: assign a `type` to each concept. Be descriptive and consistent within the bundle (e.g., `Metric`, `BigQuery Table`, `API Endpoint`, `Playbook`, `Reference`). Use the same type string for the same kind of thing across all concepts.
3. **Hierarchy**: group concepts into subdirectories by domain or category, not by source file. A concept from document A and a concept from document B may belong in the same subdirectory.
4. **Cross-links**: identify relationships between concepts that should be expressed as markdown links in the body.
5. **Tags**: identify cross-cutting tags.

**Before writing any files**, present the proposed structure to the user:

```
Proposed OKF bundle: <output path>
─────────────────────────────────────────
<bundle-root>/
├── index.md
├── log.md
├── <group>/
│   ├── index.md
│   ├── <concept>.md
│   └── <concept>.md
└── <group>/
    ├── index.md
    └── <concept>.md

Concepts : <N>
Types    : <list of distinct type values>
Tags     : <list of distinct tags>
Source   : <N> document(s) read
```

Ask: **"Proceed with this structure? (yes / no / describe changes)"**

Wait for the user's answer. If they request changes, revise the structure and show it again before writing.

## 5. Write the bundle

After user approval:

### Concept files
For each concept, write a `.md` file at the planned path with:
- Frontmatter:
  - `type`: as decided
  - `title`: human-readable display name
  - `description`: one sentence summarizing the concept
  - `resource`: canonical URI if the concept describes a concrete external asset; omit otherwise
  - `tags`: YAML list of relevant tags
  - `timestamp`: current datetime in ISO 8601 (UTC)
- Body: structured markdown derived from the source content. Use headings, lists, and tables. Add cross-links to related concepts using bundle-relative paths (starting with `/`). Include a `# Citations` section if claims are sourced from external material.

### Index files
For each directory (including the root), write `index.md` with no frontmatter. Exception: the root `index.md` MAY include frontmatter with `okf_version`. Format per §6:
```markdown
# <Directory / Group Name>

* [Title](./concept.md) - description from frontmatter
* [Subdirectory](./subdir/) - what this group contains
```

### Log file
Write `log.md` at the bundle root. Format per §7, with today's date and one entry per concept created:
```markdown
# Bundle Update Log

## <YYYY-MM-DD>
* **Creation**: Initialized OKF bundle from <N> source document(s).
* **Creation**: Added [<title>](<path>) — <description>.
…
```

### Skill files (optional)
Only if `skills:yes` was specified: copy all skill files found in `skills/` (relative to the current working directory) into `<bundle-root>/skills/`.

### SPEC.md
Fetch `SPEC.md` from the upstream repository and write it to `<bundle-root>/SPEC.md`:
`https://raw.githubusercontent.com/GoogleCloudPlatform/knowledge-catalog/main/okf/SPEC.md`

## 6. Git (optional)

If `git:yes` was specified, or if not specified and the user confirms:
1. If the bundle root is not already inside a git repository, run `git init`.
2. Follow `okf:_okf-skill-git-commit` with commit message: `Initialize OKF bundle (<N> concepts, <M> types)`

## 7. Validate

Follow `okf:_okf-skill-validate`.

## 8. Final report

```
OKF bundle created
─────────────────────────────────────────
Path      : <absolute path>
Concepts  : <N> files across <M> directories
Types     : <list>
Git       : initialized with initial commit  /  not initialized
Skills    : copied  /  not included
Validation: ✓ Conformant (OKF <version>)
Skill version: 1.0
```

## 9. Write invocation log

Follow `okf:_okf-skill-write-log` with:
- `skill`: `okf:create`, `version`: `1.0`
- `bundle`: absolute path to the bundle root written in step 5
- `outcome`: `success` if the final report was printed; `cancelled` if the user declined the proposed structure; `error` if an unrecoverable error occurred
- `concepts_added`: number of concept files written
- `concepts_updated`: `null`
- `concepts_split`: `null`
- `conflicts`: `null`
- `note`: `null`