Create Bkn

Create BKN

Generate well-formed BKN directories (Markdown + YAML frontmatter) per v2.0.1.

Works with kweaver-core

create-bkn authors the .bkn tree; kweaver-core runs kweaver auth login and kweaver bkn push / pull after files exist.

What is BKN

BKN is Markdown + YAML frontmatter for schema; one file per definition under typed subfolders. Details (sections, required tables, types) live in [references/SPECIFICATION.llm.md](references/SPECIFICATION.llm.md).

Directory layout

{network_dir}/
├── SKILL.md
├── network.bkn
├── CHECKSUM                 # optional; SDK may generate
├── object_types/
├── relation_types/
├── action_types/
├── concept_groups/
└── data/                    # optional CSV instance data

Workflow

1. Gather requirements — objects, relations, actions, optional concept groups
2. Read spec — [references/SPECIFICATION.llm.md](references/SPECIFICATION.llm.md) (format rules, sections, frontmatter types)
3. Pick templates — copy/adapt from [assets/templates/](assets/templates/) (network_type.bkn.template, object_type.bkn.template, …)
4. Create network.bkn — root file; align with Network Overview
5. Create object_types/*.bkn — one file per object, {id}.bkn
6. Create relation_types/*.bkn — one file per relation
7. Create action_types/*.bkn — one file per action
8. Create concept_groups/*.bkn — optional
9. Update network.bkn — list all IDs in Network Overview
10. Add root SKILL.md in the BKN directory — same folder as network.bkn (this is not the create-bkn skill file); agent-facing guide for that network (see [Delivered BKN: root SKILL.md](#delivered-bkn-root-skillmd))
11. Review (MUST) — cross-check [Validation checklist](#validation-checklist) and [Business rules placement](#business-rules-placement); fix IDs, cross-refs, headings
12. Validate (MUST) — kweaver bkn validate (see [Validation](#validation))
13. Import (optional) — kweaver bkn push

Import (kweaver CLI)

Requires the kweaver CLI from @kweaver-ai/kweaver-sdk (npm install -g @kweaver-ai/kweaver-sdk; Node.js 22+). push uses tar; on macOS COPYFILE_DISABLE=1 is set by the tool.

• Platform auth — If you already have a valid token for the target platform (kweaver auth status), do not run kweaver auth login again. If not authenticated, run kweaver auth login first.
• BKN validation — If workflow step 12 (kweaver bkn validate ) already succeeded for this directory, do not repeat validate before push unless you changed .bkn files. If you have not validated yet, run validate before push.

kweaver bkn push  [--branch main] [-bd ]

-bd / --biz-domain is optional. If you omit it, the CLI resolves the business domain automatically (KWEAVER_BUSINESS_DOMAIN env, then saved platform config in ~/.kweaver, otherwise bd_public).

Export: kweaver bkn pull []. More subcommands: kweaver bkn --help (see kweaver-core skill if loaded).

Validation

kweaver bkn validate — must pass before delivery or upload. It loads network.bkn and sibling .bkn files. Success prints counts; on failure fix .bkn files and re-run.

Per-type reference

| Kind | Spec (section) | Template | Example (k8s) | |------|------------------|----------|---------------| | Network | knowledge_network in spec | [assets/templates/networktype.bkn.template](assets/templates/networktype.bkn.template) | [references/examples/k8s-network/network.bkn](references/examples/k8s-network/network.bkn) | | Object | object_type | [assets/templates/objecttype.bkn.template](assets/templates/objecttype.bkn.template) | [references/examples/k8s-network/objecttypes/pod.bkn](references/examples/k8s-network/objecttypes/pod.bkn) | | Relation | relation_type | [assets/templates/relationtype.bkn.template](assets/templates/relationtype.bkn.template) | [references/examples/k8s-network/relationtypes/podbelongsnode.bkn](references/examples/k8s-network/relationtypes/podbelongsnode.bkn) | | Action | action_type | [assets/templates/actiontype.bkn.template](assets/templates/actiontype.bkn.template) | [references/examples/k8s-network/actiontypes/restartpod.bkn](references/examples/k8s-network/actiontypes/restartpod.bkn) | | Concept group | concept_group | [assets/templates/conceptgroup.bkn.template](assets/templates/conceptgroup.bkn.template) | [references/examples/k8s-network/conceptgroups/k8s.bkn](references/examples/k8s-network/conceptgroups/k8s.bkn) |

Full rules and optional sections: [references/SPECIFICATION.llm.md](references/SPECIFICATION.llm.md).

Naming conventions

• ID: lowercase, digits, underscores; file: {id}.bkn under the matching folder
• Headings: # network title, ## type block, ### section, #### logic property
• Frontmatter: at least type, id, name (see spec for each type)

Business rules placement

Rules must sit in spec-defined places so import persists them. Full wording: [references/SPECIFICATION.llm.md](references/SPECIFICATION.llm.md#输出规则).

• Network-level — prose in network.bkn right after # {title} (before structured sections like ## Network Overview)
• Type-level — prose in each type file after ## ObjectType: / ## RelationType: / … and before the first ###; never in frontmatter
• Property-level — in Data Properties table Description column
• No extra sections — do not add Markdown outside the standard sections; parsers may drop unparsed content on import

Validation checklist

• [ ] network.bkn at root; frontmatter matches spec
• [ ] Every .bkn has valid YAML frontmatter (type, id, name)
• [ ] Files live under folders matching type (object_types/, relation_types/, …); filename = {id}.bkn
• [ ] Network Overview lists all definition IDs — no missing/extra
• [ ] Relations/actions reference existing object-type IDs; concept groups list only existing objects
• [ ] Parameter binding Source ∈ property | input | const; YAML blocks (e.g. trigger) parse
• [ ] Heading hierarchy has no skipped levels
• [ ] Business rules only in allowed places (see [Business rules placement](#business-rules-placement))

Output rules

1. Emit raw .bkn content — do not wrap the whole file in a fenced markdown block
2. Reuse IDs consistently across relations/actions
3. IDs: lowercase + underscores; display text Chinese unless asked otherwise
4. Keep heading order per spec

Examples

• [references/examples/k8s-network/](references/examples/k8s-network/) — modular sample (objects, relations, actions, concept group)

Delivered BKN: root SKILL.md

When you build a knowledge network directory {network_dir}/, add {network_dir}/SKILL.md at the root (alongside network.bkn). Short overview + index tables with file paths (object | path | relation | path | action | path) so agents route to the right .bkn without scanning. Optional: topology sketch, usage scenarios. Example: [references/examples/k8s-network/SKILL.md](references/examples/k8s-network/SKILL.md).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: kweaver-ai
• Source: kweaver-ai/kweaver-dip
• License: Apache-2.0
• Homepage: https://kweaver.ai

Install and usage instructions live in the source repository linked above.