Proposal: Bundle an official Maka help skill for version-aware product knowledge

## Problem

When users ask Maka about its own features, configuration, permissions, troubleshooting, or architecture, the model should have a discoverable, official source of product knowledge that matches the installed version. A packaged-app user should not need a source checkout or manually install a documentation skill to get a grounded answer.

Could we ship an official help skill, tentatively `maka-help`, enabled by default, that guides the model to the relevant documentation and implementation references on demand?

## Existing foundations

- The [skill catalog policy](https://github.com/apache/maka/blob/main/docs/skill-catalog-policy.md) already keeps summaries in a bounded catalog and loads instructions through `Skill`, with `SkillSearch` for omitted entries.
- [Bundled skills](https://github.com/apache/maka/tree/main/packages/runtime/resources/bundled-skills) provide an existing distribution mechanism.
- [maka-architecture-docs](https://github.com/apache/maka/blob/main/skills/maka-architecture-docs/SKILL.md) supports writing and reviewing architecture documentation. The proposed skill would serve product questions from end users; its scope and delivery would be different.

## Suggested scope

1. Start with usage, configuration, and common troubleshooting. Provide deeper links to design documents and selected implementation references for architecture questions.
2. Keep `SKILL.md` short: clear trigger descriptions, a lookup workflow, and a topic index. Load supporting material only when needed; maintain authoritative documents rather than a separately rewritten knowledge base.
3. Bundle essential references so they work without a source checkout or network connection. Tie the documentation snapshot and source links to the installed release, and label current behavior, proposals, deprecated features, and historical notes separately.
4. Make discovery reliable within existing catalog limits, while preserving the user's ability to disable the skill. Default installation alone does not establish that the model will discover and invoke it.
5. Ask the model to cite the documentation it used and state when an answer depends on a different version or unavailable evidence. Documentation can explain a setting; the user's actual configuration still requires runtime inspection when relevant.

## Questions for discussion

- Does an official bundled skill fit this use case, and which existing documents should be its authoritative sources?
- How should release packaging and updates keep the skill and references aligned without creating a second documentation maintenance burden?
- What is the smallest useful first version, and how should we ensure discovery under catalog budget pressure?

A useful acceptance scenario would be a fresh packaged installation, without a repository checkout: a user asks a product question in Chinese or English, the model discovers the skill, reads the appropriate versioned reference, and answers with a source. Unrelated tasks should not load the documentation body. Checks should also cover catalog omission, disabled state, and missing or mismatched references.

@Astro-Han, given your recent work on runtime tool/skill context and active upstream maintenance, would you share your view on whether this belongs in the default distribution and what the initial scope should be? This is a proposal for discussion; the design is open.

中文翻译

## 问题

用户询问 Maka 自身的功能、配置、权限、故障排查或架构时，模型应该能发现并查阅与已安装版本匹配的官方产品资料。使用打包应用的用户不应为了获得有依据的回答，还需要准备源码仓库或手动安装文档技能。

是否可以默认内置并启用一个官方帮助技能，暂名 `maka-help`，让模型按需查阅相关文档与实现参考？

## 已有基础

- [技能目录策略](https://github.com/apache/maka/blob/main/docs/skill-catalog-policy.md)已支持在有预算限制的目录中展示摘要，通过 `Skill` 加载正文，并用 `SkillSearch` 搜索未展示的条目。
- [内置技能](https://github.com/apache/maka/tree/main/packages/runtime/resources/bundled-skills)提供了现有分发机制。
- [maka-architecture-docs](https://github.com/apache/maka/blob/main/skills/maka-architecture-docs/SKILL.md)用于架构文档的撰写与审查。本提案面向终端用户的产品问答，范围与交付方式有所不同。

## 建议范围

1. 首版覆盖使用、配置与常见排障；架构问题通过深入阅读入口连接设计文档与精选实现参考。
2. 保持 `SKILL.md` 简短，包含清晰的触发描述、查阅流程和主题索引；参考资料按需读取，维护权威文档，避免另外改写一套知识库。
3. 随应用打包关键资料，使其无需源码仓库或网络即可使用。文档快照与源码链接匹配已安装版本，分别标明当前行为、提案、已弃用功能和历史记录。
4. 在现有目录预算内保证可发现性，并保留用户禁用技能的能力。默认安装本身不能证明模型能够发现并调用它。
5. 要求模型引用实际使用的文档，并说明答案何时依赖其他版本或缺失证据。文档可以解释配置项，用户实际的配置在相关场景下仍需通过运行时检查确认。

## 待讨论问题

- 官方内置技能是否适合这个场景？哪些现有文档应作为权威来源？
- 发布打包与更新怎样保持技能及参考资料的版本一致，同时避免增加第二套文档维护负担？
- 最小可用的首版应包含哪些内容？目录预算紧张时如何保证可发现性？

一个有用的验收场景是：全新安装的打包应用，没有源码仓库；用户用中文或英文询问产品问题，模型能够发现技能、读取相应版本的参考资料，并给出带来源的回答。无关任务不应加载文档正文。验证还应覆盖目录省略、技能禁用，以及参考资料缺失或版本不匹配的情况。

邀请 Astro-Han 结合近期在运行时工具与技能上下文上的工作，以及持续参与上游维护的经验，评价这个能力是否适合默认分发、首版范围应该如何确定。这是供讨论的提案，设计仍开放。