Custom Output Templates

Every knowledge package is rendered from a package template in your Context knowledge workspace, by default src/package-templates/kb/. The template supplies the package entry page, the query Skill and any instructions for Agents; context build renders it and adds the selected approved articles. The generated default is a usable generic starting point. Customize it when your package needs project terminology, curated navigation, routing rules or task-specific Skills.

flowchart LR
  tpl["src/package-templates/kb/"] --> render["Render with Handlebars"]
  vars["Built-in and template.vars"] --> render
  render --> out["dist/name/"]
  approved["Selected approved articles"] --> out
  out --> check["Path, link and<br/>boundary checks"]

What the template contains

src/package-templates/
├── kb/
│   ├── AGENTS.md
│   ├── wikis/
│   │   └── index.md
│   └── skills/
│       └── knowledge-query/
│           ├── SKILL.md
│           └── scripts/
│               └── search.mjs
└── llms/
    └── llms.txt

A knowledge package template must contain at least one SKILL.md and wikis/index.md; a template with only AGENTS.md is rejected. Each rendered Skill lives at skills/<skill-name>/SKILL.md with a matching frontmatter name. To give the query Skill a project prefix, rename its template folder — for example skills/android-query/ — since Context never derives Skill names from the package name. Add another Skill only when you want behavior beyond knowledge lookup.

Accept or edit before the first build

A newly initialized generic template must be edited or explicitly accepted before the first build. context status shows this as a package template review step: the Agent either accepts the unchanged default through the command the workflow returns, or you edit files under src/package-templates/. Context compares file digests and records the decision; it does not judge the template's prose.

The entry page and navigation

wikis/index.md is the package's entry page. Tell readers what the package covers, who it is for and how to query it. Every selected root — wikis/, guides/, rules/, feats/ — always gets an index. By default, small directories fold into their nearest generated ancestor index and a directory gets its own index.md only when it would expose more than 50 entries to its parent; set navigation.foldDirectoryIndexes: false to generate one per directory, or change maxInlineEntries.

For curated navigation, loop over the built-in variables in wikis/index.md:

{{#each knowledgeGroups}}
## {{title}} ({{count}})
{{#each items}}
- [{{title}}]({{href}})
{{/each}}
{{/each}}

Variable	Gives you
{{displayName}}, {{packageName}}	Package display name and name
{{knowledgeCount}}, {{knowledgeTimestamp}}	Number of selected pages and the latest timestamp
{{knowledgeItems}}	Selected page metadata for loops
{{knowledgeGroups}}	Pages grouped by root and first directory
{{knowledgeTreeNodes}}, {{knowledgeTree}}	Nested tree, or its Markdown preview
{{wikisRoot}} … {{featsRoot}}	Package-relative root paths, for links inside Skills

The complete list, with loops, conditionals and helpers, is in Template Variables. Custom values come from template.vars.

The query Skill

The default knowledge-query Skill already carries the structure-first query discipline and a BM25 search fallback. Edit its template when you need project terminology, entry points or task workflows. Put authoring notes in template comments or separate guidance — not in a final section addressed to authors inside the delivered Skill.

Rules the build enforces

• No second knowledge source. Template prose that describes coverage, scope, known gaps or limits must cite approved knowledge, context-build-inventory.json or rendered structure data; otherwise the build reports a template-boundary diagnostic. Facts belong in approved articles.
• No collisions. Template paths are rendered first; a rendered path may not collide with a selected knowledge path or a generated index path. Rename the template file or exclude the knowledge path with select.exclude.
• Valid links. Links in every root index and generated child index must resolve inside the package; broken ones are reported as package/index-link-invalid.
• Fix at the source. Repair the template, the approved knowledge path or the declaration and rebuild; never patch dist/.

context build and context verify check structure, not whether the selected knowledge is meaningful for your readers — inspect the output yourself. The template API is in Package Templates.

定制输出模板

每个知识包都由你的 Context 知识工作区中的一个知识包模板渲染而成，默认位于 src/package-templates/kb/。模板提供知识包的入口页、查询 Skill 以及给 Agent 的各种说明；context build 会渲染模板并加入选中的已批准文章。生成的默认模板是一个可用的通用起点。当你的知识包需要项目术语、精选导航、路由规则或面向特定任务的 Skill 时，再对它进行定制。

flowchart LR
  tpl["src/package-templates/kb/"] --> render["用 Handlebars 渲染"]
  vars["内置变量和 template.vars"] --> render
  render --> out["dist/name/"]
  approved["选中的已批准文章"] --> out
  out --> check["路径、链接和<br/>边界检查"]

模板包含什么

src/package-templates/
├── kb/
│   ├── AGENTS.md
│   ├── wikis/
│   │   └── index.md
│   └── skills/
│       └── knowledge-query/
│           ├── SKILL.md
│           └── scripts/
│               └── search.mjs
└── llms/
    └── llms.txt

知识包模板至少必须包含一个 SKILL.md 和 wikis/index.md；只有 AGENTS.md 的模板会被拒绝。每个渲染出的 Skill 都位于 skills/<skill-name>/SKILL.md，且 frontmatter 中的 name 与之匹配。如果想给查询 Skill 加上项目前缀，请重命名它的模板文件夹——例如 skills/android-query/——因为 Context 绝不会根据知识包名称推导 Skill 名称。只有当你需要知识查找之外的行为时，才添加其他 Skill。

首次构建前接受或修改

新初始化的通用模板必须先修改或明确接受，才能进行首次构建。context status 会把它显示为知识包模板审核步骤：Agent 要么通过工作流返回的命令接受未修改的默认模板，要么由你修改 src/package-templates/ 下的文件。Context 会比较文件摘要并记录这一决定；它不会评判模板的文字内容。

入口页与导航

wikis/index.md 是知识包的入口页。请告诉读者这个知识包覆盖什么、面向谁，以及如何查询它。每个选中的根目录——wikis/、guides/、rules/、feats/——始终都会有一个索引。默认情况下，小目录会折叠到最近的已生成上级索引中，只有当某个目录会向其父级暴露超过 50 个条目时，才会获得自己的 index.md；设置 navigation.foldDirectoryIndexes: false 可为每个目录生成一个索引，也可以修改 maxInlineEntries。

如需精选导航，可在 wikis/index.md 中遍历内置变量：

{{#each knowledgeGroups}}
## {{title}} ({{count}})
{{#each items}}
- [{{title}}]({{href}})
{{/each}}
{{/each}}

变量	提供的内容
{{displayName}}、{{packageName}}	知识包显示名称和名称
{{knowledgeCount}}、{{knowledgeTimestamp}}	选中页面的数量和最新时间戳
{{knowledgeItems}}	供循环使用的选中页面元数据
{{knowledgeGroups}}	按根目录和一级目录分组的页面
{{knowledgeTreeNodes}}、{{knowledgeTree}}	嵌套树，或其 Markdown 预览
{{wikisRoot}} … {{featsRoot}}	相对于知识包的根路径，用于 Skill 内的链接

包括循环、条件和辅助函数在内的完整列表见模板变量。自定义值来自 template.vars。

查询 Skill

默认的 knowledge-query Skill 已经内置了结构优先的查询规范和 BM25 搜索兜底。当你需要项目术语、入口或任务工作流时，修改它的模板。编写说明请放在模板注释或单独的指南中——不要放在交付的 Skill 里一个写给作者的末尾章节中。

构建强制执行的规则

• 不能有第二个知识来源。 描述覆盖范围、范围边界、已知缺口或限制的模板文字，必须引用已批准的知识、context-build-inventory.json 或渲染后的结构数据；否则构建会报告模板边界诊断。事实应放在已批准的文章中。
• 不能冲突。 模板路径会先渲染；渲染后的路径不能与选中的知识路径或生成的索引路径冲突。请重命名模板文件，或用 select.exclude 排除该知识路径。
• 链接必须有效。 每个根索引和生成的子索引中的链接都必须能在知识包内解析；失效的链接会被报告为 package/index-link-invalid。
• 在源头修复。 修复模板、已批准的知识路径或声明，然后重新构建；永远不要修补 dist/。

context build 和 context verify 检查的是结构，而不是选中的知识对你的读者是否有意义——请自己检查产出。模板 API 见包模板。