用途:该技能用于在本仓库中编写或修改指南类内容(SKILL.md、reference/.md、golden path),确保其与概念图一致并建立链接。仓库中概念(concepts/.yaml)以规则形式保存精确事实并引用公开来源,是指南“何为真”的来源;指南负责解释、教学与演示,是“如何做”的来源。指南陈述的事实须有概念规则支持,并链接其覆盖的概念;每个概念至少被一个指南覆盖,由 pnpm check:guides 强制校验。
主要能力与用法:编写前先在 ontology/tools/ 中查找相关概念,可运行 pnpm build:sqlite、pnpm query tree "<concept>"、pnpm query search "<question>"、pnpm query concept "<name>"。写作须基于规则,每条事实性声明(限制、默认值、状态、动作效果、存在性)都要与规则一致,并补充命令、顺序、陷阱与验证方式。若指南需要某条规则没有的事实,先用 add-concept 技能新增规则并引用规范、公开文档或实测;若规则有误或过时,应在同一次变更中修正规则及其证据。
链接声明:SKILL.md 在 frontmatter 的 metadata.concepts 中声明;reference 文档在顶部 frontmatter 用 concepts: 行声明;golden path 在 frontmatter 的 lanes、mcp、concepts 中声明。只列出指南实际解释或使用的概念。pnpm build:bundle --suggest 可列出各 golden path 提及的概念作为候选。当某文档是概念的主要解释时,结尾加简短“Exact rules”小节并链接各概念文件(reference 文档中目标为 ../concepts/<id>.yaml)。新 reference 文档需在其 SKILL.md 表格中加一行;新 golden path 需在路由表与 golden-paths/README.md 中加行。
概念变更后:pnpm check:guides 会在新概念无指南时报错,需扩展现有文档或新写;用 pnpm query tree 与 grep 查找已覆盖该概念的指南并核对是否仍与规则一致;若规则引用了某技能文件作为证据而该文件被修改,需重读规则。
风格与检查:遵循 concepts/README.md 的“Writing style”与 AGENTS.md 约定,使用一般现在时、"Runpod"、代码标识符用反引号,避免“currently”“not yet”,优先正面陈述。检查命令:cd ontology/tools 后运行 pnpm format && pnpm validate --strict && pnpm check:guides && pnpm test,再 cd ../.. 运行 python3 hooks/check_links.py && python3 hooks/check_runpod_branding.py。check:guides 须无错误,构建中“concepts with a guide”须覆盖每个概念。