跳转到内容
OntoSkills

OntoCore 编译器

ontocore 是可选的编译器，将 SKILL.md 源文件转换为已验证的 OWL 2 本体模块。

大多数用户不需要它 — 只有在以下情况才需要 OntoCore：

  • 从源文件编写自定义技能
  • 导入和编译原始技能仓库
  • 本地开发和测试技能

安装

Terminal window
ontoskills install core

这将在以下位置创建托管的编译器运行时：

~/.ontoskills/core/

系统要求：

  • Python 3.10+
  • Anthropic API key（设置 ANTHROPIC_API_KEY 环境变量）

可选： 安装 ontocore[embeddings] 以启用每技能嵌入生成，用于语义搜索（大型技能目录推荐）：

Terminal window
pip install ontocore[embeddings]

编译流水线

SKILL.md → [提取] → [安全检查] → [序列化] → [SHACL] → [嵌入] → ontoskill.ttl + intents.json
阶段发生什么
提取Claude 读取 SKILL.md 并提取结构化知识 → 紧凑知识节点
安全检查正则表达式 + LLM 审查恶意内容
序列化Pydantic 模型 → RDF 三元组
验证SHACL 形状检查逻辑有效性
嵌入生成每技能意图嵌入（384 维，L2 归一化）
写入带备份的原子写入

如果任何阶段失败，技能不会被写入。SHACL 守门员强制执行宪法规则。嵌入阶段是可选的 — 通过 pip install ontocore[embeddings] 安装以生成每技能语义搜索向量。未安装时，嵌入生成会被跳过并显示警告。

内容提取

提取阶段是 OntoCore 的核心。它将你的 Markdown 转换为紧凑的知识节点 — 即代理消费的主要输出。内部通过结构化内容块和节树的中间管道实现。

SKILL.md → 平坦块 → 节树 → 知识节点
  1. 平坦块提取 — 解析器将 Markdown 分词为类型化块：段落、代码块、表格、项目列表、有序过程、引用、流程图、模板、HTML 块、前置元数据和标题
  2. 节树构建 — 块根据标题级别组织为层次树，通过父子关系保留文档结构
  3. LLM 增强（可选）— 如果设置了 ANTHROPIC_API_KEY，LLM 骨架步骤在回退到确定性树构建之前改善节嵌套

内容块类型

SKILL.md 中的每个元素在中间提取管道期间成为类型化的 RDF 节点。共有 11 种块类型：

块类型捕获内容关键属性
paragraph自由文本textContent
code_block带语言的围栏代码codeLanguage、codeContent
tableMarkdown 表格tableMarkdown、rowCount
flowchartMermaid 或 Graphviz 图表flowchartType、flowchartSource
template带 {variables} 的可重用模板templateContent、templateVariables
bullet_list带嵌套子项的无序列表hasItem → itemText、itemOrder
blockquote带可选归属的引用文本quoteContent、quoteAttribution
ordered_procedure编号的逐步过程hasStep → stepText、stepOrder
html_block原始 HTML 内容htmlContent
frontmatterYAML 元数据rawYaml、解析后的属性
heading节标题集成到节树中

项目列表中的条目和过程中的步骤可以通过 hasChild 属性包含嵌套子块（代码示例、引用等）。

文件处理规则

OntoCore 根据文件类型进行处理：

规则输入输出处理方式
ASKILL.mdontoskill.ttlLLM 编译
B*.md（辅助文件）*.ttl作为子技能进行 LLM 编译
C其他文件直接复制资产（图片等）

目录镜像

输出结构镜像输入：

skills/                          →    ontoskills/
├── office/                      →    ├── office/
│   ├── SKILL.md                 →    │   ├── ontoskill.ttl
│   ├── planning.md              →    │   ├── planning.ttl
│   └── review.md                →    │   └── review.ttl
└── pdf/                         →    └── pdf/
    ├── SKILL.md                 →        ├── ontoskill.ttl
    └── diagram.png              →        └── diagram.png

子技能

技能目录中的辅助 .md 文件成为子技能：

  • 它们自动 extend 父技能
  • 在提取过程中继承父级上下文
  • 获得限定 ID：package/parent/child

CLI 命令

初始化核心本体

Terminal window
ontoskills init-core

创建 core.ttl，包含基础 TBox 本体（类、属性、状态定义）。

编译技能

Terminal window
# 编译 skills/ 中的所有技能
ontoskills compile


# 编译特定技能
ontoskills compile office


# 带选项编译
ontoskills compile --force          # 跳过缓存
ontoskills compile --dry-run        # 预览但不保存
ontoskills compile --skip-security  # 跳过 LLM 安全审查
ontoskills compile -v               # 详细日志
选项描述
-i, --input输入目录（默认：skills/）
-o, --output输出目录（默认：ontoskills/）
--dry-run预览但不保存
--skip-security跳过 LLM 安全审查（正则检查仍运行）
-f, --force强制重新编译（跳过缓存）
-y, --yes跳过确认提示
-v, --verbose启用调试日志
-q, --quiet抑制进度输出

查询图谱

Terminal window
ontoskills query "SELECT ?s WHERE { ?s a oc:Skill }"

对编译后的本体运行 SPARQL 查询。

检查质量

Terminal window
# 列出所有已编译的技能
ontoskills list-skills


# 运行安全审计
ontoskills security-audit

输出结构

编译后：

ontoskills/
├── core.ttl      # 核心 TBox（共享类/属性）
├── index.ttl                # 带 owl:imports 的清单
├── system/
│   └── index.enabled.ttl    # 为 MCP 启用的技能
└── <skill-path>/
    ├── ontoskill.ttl        # 单个技能模块
    └── intents.json         # 预计算的意图嵌入（可选）

核心本体

核心本体（core.ttl）是所有技能模块通过 owl:imports 引用的共享 TBox。它：

  • 在线服务于 https://ontoskills.sh/ontology/core.ttl
  • 由 ontoskills install mcp 自动下载到 ~/.ontoskills/ontologies/core.ttl
  • 在开发时由 ontoskills init-core 或 ontoskills compile 本地重新生成

已编译的技能模块通过 owl:imports <https://ontoskills.sh/ontology/core.ttl> 引用核心本体。MCP 将此解析为本体根目录中的本地副本。

core.ttl 定义：

  • oc:Skill、oc:ExecutableSkill、oc:DeclarativeSkill
  • 属性：dependsOnSkill、extends、contradicts、resolvesIntent 等
  • 知识节点类：oc:Heuristic、oc:AntiPattern 等
  • 前置条件/后置条件的状态类

索引

index.ttl 是一个清单，它：

  • 列出所有已编译的技能
  • 通过 owl:imports <https://ontoskills.sh/ontology/core.ttl> 引用核心本体
  • 被 OntoMCP 用于发现可用技能

缓存

OntoCore 是缓存感知的：

  • 每个技能都有存储在 oc:contentHash 中的内容哈希
  • 未更改的技能在重新编译时会被跳过
  • 使用 --force 跳过缓存

安全流水线

编译器运行深度防御安全检查：

  1. Unicode 规范化 — NFC 规范化，零宽字符移除
  2. 正则模式 — 检测提示注入、命令注入、路径遍历、凭据暴露
  3. LLM 审查 — Claude 审查标记内容的细微威胁

检测到的威胁类型：

  • 提示注入（ignore instructions、system:、you are now）
  • 命令注入（; rm、| bash、命令替换）
  • 数据泄露（带凭据的 curl -d、wget --data）
  • 路径遍历（../../../、/etc/passwd）
  • 凭据暴露（硬编码的 api_key=、password=）

使用 --skip-security 跳过 LLM 审查（正则检查仍运行）。

SHACL 验证

每个技能在写入前必须通过 SHACL 验证。宪法形状定义在 core/specs/ontoskills.shacl.ttl 中，跨 6 个节点形状强制执行约束。

必需字段（阻止）：

约束规则
resolvesIntent必需（至少 1 个）— 也用于语义搜索嵌入
generatedBy可选（证明）
requiresState必须是有效的 IRI
yieldsState必须是有效的 IRI
handlesFailure必须是有效的 IRI

类型特定规则：

  • ExecutableSkill 必须恰好有 1 个 hasPayload（带 code 或 executionPath）
  • DeclarativeSkill 不能有 hasPayload

如果验证失败，技能不会被写入并显示错误。

参见技能创作获取通过验证的实用指南。

错误处理

错误原因解决方案
SkillNotFoundError技能目录不存在检查路径拼写
OrphanSubSkillsError.md 文件没有父级 SKILL.md在目录中创建 SKILL.md
SecurityError内容被安全流水线阻止审查内容，如果安全使用 --skip-security
OntologyValidationErrorSHACL 验证失败修复报告的约束违规
ExtractionErrorLLM 提取失败检查 ANTHROPIC_API_KEY，重试

环境变量

变量描述默认值
ANTHROPIC_API_KEYAnthropic API key必需
ANTHROPIC_BASE_URLAPI 基础 URLhttps://api.anthropic.com
SECURITY_MODEL安全审查模型claude-opus-4-6
DEFAULT_SKILLS_AUTHOR无包结构的技能的默认作者local

下一步