Create Bkn
Developmentcreate-bknCreate Bkn is an Agent Skill for development published in the UnicomAI/wanwu repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Guides creation of BKN (Business Knowledge Network) definition files following v2.0.1 spec. Covers network, object_type, relation_type, action_type, concept_group. Use when creating knowledge networks, BKN files, object types, relation types, action types, concept groups, or when user asks to model business knowledge in BKN format. When ontology-core is also loaded, use it to run ontology CLI (bkn push) after files exist.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/UnicomAI/wanwu/blob/HEAD/configs/microservice/bff-service/configs/agent-skills/ontology/create-bkn/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/create-bkn, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Create BKN
Generate well-formed BKN directories (Markdown + YAML frontmatter) per v2.0.1.
Works with ontology-core
create-bkn authors the .bkn tree; ontology-core runs ontology 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.
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
- Gather requirements — objects, relations, actions, optional concept groups
- Read spec — references/SPECIFICATION.llm.md (format rules, sections, frontmatter types)
- Pick templates — copy/adapt from assets/templates/ (
network_type.bkn.template,object_type.bkn.template, …) - Create
network.bkn— root file; align with Network Overview- MUST: generate a fresh UUID v4 locally (e.g. Python
uuid.uuid4()) and write it as theidfield in frontmatter at file creation time. Never leaveidempty,null,~, or absent —ontology bkn validate/pushboth require a non-empty string id, and the bkn-creator flow does not callontology bkn createto acquire a server-assigned id. - The locally generated UUID is the final
kn_id; any other.bknfile that references the network id (e.g.network_idinobject_types/*.bkn) must reuse the same UUID.
- MUST: generate a fresh UUID v4 locally (e.g. Python
- Create
object_types/*.bkn— one file per object,{id}.bkn - Create
relation_types/*.bkn— one file per relation - Create
action_types/*.bkn— one file per action - Create
concept_groups/*.bkn— optional - Update
network.bkn— list all IDs in Network Overview - Add root
SKILL.mdin the BKN directory — same folder asnetwork.bkn(this is not the create-bkn skill file); agent-facing guide for that network (see Delivered BKN: root SKILL.md) - Review (MUST) — cross-check Validation checklist and Business rules placement; fix IDs, cross-refs, headings
- 特别核对
action_types/*.bkn每个文件 frontmatter 是否含action_type: add|modify|delete这一行(位置在 frontmatter,不在 markdown body 的 Bound Object 表),遇到查询/监控/追溯/校验等只读语义,删掉对应 ActionType 文件并在network.bkn的 Network Overview 同步移除该 id
- 特别核对
- Validate (MUST) —
ontology bkn validate <dir>(see Validation) - Import (optional) —
ontology bkn push <dir>
Import (ontology CLI)
无需安装。ontology 已内置在执行环境,直接调用即可。
- BKN validation — If workflow step 12 (
ontology bkn validate <dir>) already succeeded for this directory, do not repeat validate beforepushunless you changed.bknfiles. If you have not validated yet, runvalidatebeforepush.
ontology bkn push <dir> [--branch main] [-bd <business-domain>]
-bd / --biz-domain is optional. If you omit it, the CLI resolves the business domain automatically.
Export: ontology bkn pull <kn-id> [<dir>]. More subcommands: ontology bkn --help (see ontology-core skill if loaded).
Validation
ontology bkn validate <dir> — 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/network_type.bkn.template | references/examples/k8s-network/network.bkn |
| Object | object_type | assets/templates/object_type.bkn.template | references/examples/k8s-network/object_types/pod.bkn |
| Relation | relation_type | assets/templates/relation_type.bkn.template | references/examples/k8s-network/relation_types/pod_belongs_node.bkn |
| Action | action_type | assets/templates/action_type.bkn.template | references/examples/k8s-network/action_types/restart_pod.bkn |
| Concept group | concept_group | assets/templates/concept_group.bkn.template | references/examples/k8s-network/concept_groups/k8s.bkn |
Full rules and optional sections: references/SPECIFICATION.llm.md.
Naming conventions
- ID: lowercase, digits, underscores; file:
{id}.bknunder 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.
- Network-level — prose in
network.bknright 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.bknat root; frontmatter matches spec - Every
.bknhas 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 - 每个
action_types/*.bkn的 frontmatter 都包含action_type:字段,值 ∈ {add,modify,delete}(注意:该字段在 frontmatter,不在### Bound Object表格里;缺失或值非法时 backend 返回BknBackend.ActionType.InvalidParameter,错误细节里说的[create, update, delete]是 backend bug,实际白名单就是add/modify/delete) -
network.bkn的 Network Overview ActionType 列表与action_types/*.bkn文件名一一对应(多/少都会导致后端 schema 不一致;CLI 不校验,会静默放过) - 没有把只读语义(查询/监控/追溯/校验)建为 ActionType——这类应走 object-type query / subgraph / metric / semantic search
- Heading hierarchy has no skipped levels
- Business rules only in allowed places (see Business rules placement)
Output rules
- Emit raw
.bkncontent — do not wrap the whole file in a fencedmarkdownblock - Reuse IDs consistently across relations/actions
- IDs: lowercase + underscores; display text Chinese unless asked otherwise
- Keep heading order per spec
Examples
- references/examples/k8s-network/ — modular sample (objects, relations, actions, concept group)
Delivered BKN: root GUIDE.md
When you build a knowledge network directory {network_dir}/, add {network_dir}/GUIDE.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/GUIDE.md.