adk-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ADK Documentation Management

ADK文档管理

Use this skill when helping users create, review, update, or maintain documentation for their ADK projects. Users write guides and docs for their own bots and features — code examples should come from their project and the official ADK repo.

当帮助用户为其ADK项目创建、审核、更新或维护文档时，使用此技能。用户会为自己的机器人和功能编写指南与文档——代码示例应来自他们的项目及官方ADK仓库。

When to Use This Skill

何时使用此技能

Activate this skill when users:

Want to create documentation for their bot ("Document my order workflow", "Write a guide for my custom actions")
Need to review existing project docs for accuracy ("Check if my docs are still correct")
Want to update docs after changing their bot ("I refactored the checkout flow, update the docs")
Need to check if docs are in sync with their code ("Are my docs current?")
Want to search their project documentation ("Find docs about my payment handler")
Ask about documentation standards or templates
Mention
```
/adk-document
```

当用户有以下需求时，启用此技能：

想要为自己的机器人创建文档（如“为我的订单流程编写文档”“为我的自定义操作撰写指南”）
需要审核现有项目文档的准确性（如“检查我的文档是否仍然正确”）
在修改机器人后想要更新文档（如“我重构了结账流程，更新文档”）
需要检查文档是否与代码同步（如“我的文档是最新的吗？”）
想要搜索项目文档（如“查找关于我的支付处理器的文档”）
询问文档标准或模板相关问题
提及
```
/adk-document
```
命令

Available Documentation

可用文档

File	Description
references/doc-standards.md	Document types, templates, quality checklists, and health metrics

文件	描述
references/doc-standards.md	文档类型、模板、质量检查清单及健康指标

Available Commands

可用命令

Command (and suggested subcommand)	Description
`/adk-document create [topic]`	Create documentation for a feature in the user's bot
`/adk-document review [doc-path]`	Review project docs for accuracy and completeness
`/adk-document update [doc-path] [what-changed]`	Update project docs after code changes
`/adk-document sync [optional-doc-path]`	Check if project docs are in sync with the bot's code
`/adk-document search [search-term]`	Search project documentation for specific topics

命令（及建议子命令）	描述
`/adk-document create [topic]`	为用户机器人中的功能创建文档
`/adk-document review [doc-path]`	审核项目文档的准确性与完整性
`/adk-document update [doc-path] [what-changed]`	代码变更后更新项目文档
`/adk-document sync [optional-doc-path]`	检查项目文档是否与机器人代码同步
`/adk-document search [search-term]`	搜索项目文档中的特定主题

Shared Principles

通用原则

1. AI-Optimized Structure

1. AI优化结构

Clear section headers (
```
##
```
,
```
###
```
,
```
####
```
) so ripgrep can find sections
Table of contents at top with anchor links
Right-sized for document type (see doc-standards reference)
Keyword-rich section names — no vague "Advanced Topics" or "Other"

清晰的章节标题（
```
##
```
、
```
###
```
、
```
####
```
），便于ripgrep查找章节
顶部带锚点链接的目录
文档长度与类型匹配（参考文档标准）
富含关键词的章节名称——避免模糊的“高级主题”或“其他”

2. Code-First Approach

2. 代码优先方法

Every concept needs a working code example from actual project code
Include file paths with line numbers for verification
Primary sources for examples (in priority order):
1. The user's own ADK project (look for
```
agent.config.ts
```
  in the workspace) — BEST
2. The official ADK repo examples (clone or find locally)
3. ADK runtime usage (
```
@botpress/runtime
```
  packages)
Never invent or speculate examples — all code must be verifiable

每个概念都需要来自实际项目代码的可运行示例
包含带行号的文件路径以便验证
示例的主要来源（优先级排序）：
1. 用户自己的ADK项目（在工作区中查找
```
agent.config.ts
```
  ）——最佳选择
2. 官方ADK仓库示例（克隆或本地查找）
3. ADK运行时用法（
```
@botpress/runtime
```
  包）
切勿编造或推测示例——所有代码必须可验证

3. Critical Distinctions

3. 关键区分

ADK primitives (from
```
@botpress/runtime
```
) vs Botpress SDK primitives
```
this.send()
```
in conversations vs
```
client.createMessage()
```
in workflows
Messages (persistent, stored) vs Events (ephemeral, not stored)
Agnostic APIs vs channel-specific features

ADK原语（来自
```
@botpress/runtime
```
）与Botpress SDK原语
对话中的
```
this.send()
```
与工作流中的
```
client.createMessage()
```
消息（持久化、存储）与事件（临时、不存储）
通用API与渠道特定功能

4. No Speculation

4. 不做推测

Do NOT add Common Mistakes or Best Practices sections unless the user explicitly provides them
Use
```
❌ WRONG
```
/
```
✅ CORRECT
```
only when documenting actual reported errors
Workflows and examples must be verified from actual code, not imagined

除非用户明确提供，否则不要添加“常见错误”或“最佳实践”章节
仅在记录实际报告的错误时使用
```
❌ WRONG
```
/
```
✅ CORRECT
```
工作流与示例必须从实际代码中验证，而非凭空想象

5. Writing Style

5. 写作风格

Direct and actionable — "Use
```
this.send()
```
" not "You might want to consider..."
Technically accurate — test examples against actual ADK code
Assumes intelligence — provide context and guidance, not hand-holding
No marketing fluff — straight to the technical substance

直接且可操作——使用“使用
```
this.send()
```
”而非“你可能需要考虑……”
技术准确——对照实际ADK代码测试示例
假设用户具备专业能力——提供上下文与指导，而非手把手教学
无营销话术——直接呈现技术实质内容

How to Answer

如何回复

When a user asks about documentation without invoking a specific command:

Load the
adk
skill (& more, if needed) for ADK context and knowledge
Identify what they need — creating, reviewing, updating, syncing, or searching
Point them to the right command or help directly using the principles above
Reference doc-standards for template and quality guidance

当用户询问文档相关问题但未调用特定命令时：

**加载
```
adk
```
技能（如有需要可加载更多）**以获取ADK相关背景知识
明确用户需求——创建、审核、更新、同步或搜索文档
指引用户使用正确的命令，或依据上述原则直接提供帮助
参考文档标准获取模板与质量相关指导

Documentation Location

文档存储位置

Documentation is written in the user's own project. Ask the user where they want docs saved if not obvious (common locations:

./docs/

./guides/

, or project root).

文档需写入用户自己的项目中。若存储位置不明确，询问用户希望将文档保存至何处（常见位置：

./docs/

、

./guides/

或项目根目录）。

Discovering Code Sources

代码来源查找

Discover the user's project and the official ADK repo for examples:

javascript

// Find ADK projects in the workspace
Glob({ pattern: "**/agent.config.ts" })

// Find ADK runtime usage in the user's project
Grep({ pattern: "from ['\"]@botpress/runtime", output_mode: "files_with_matches" })

// Look for existing project documentation
Glob({ pattern: "./{docs,guides}/**/*.md" })

// Find official ADK examples if available locally
Glob({ pattern: "**/adk/examples/**/*.ts" })

查找用户项目及官方ADK仓库以获取示例：

javascript

// 在工作区中查找ADK项目
Glob({ pattern: "**/agent.config.ts" })

// 在用户项目中查找ADK运行时用法
Grep({ pattern: "from ['\"]@botpress/runtime", output_mode: "files_with_matches" })

// 查找现有项目文档
Glob({ pattern: "./{docs,guides}/**/*.md" })

// 若本地有官方ADK示例，查找相关内容
Glob({ pattern: "**/adk/examples/**/*.ts" })

Cross-References

交叉引用

adk
skill — Core ADK knowledge (actions, workflows, conversations, etc.)
adk-evals
skill — Testing and eval documentation
adk-frontend
skill — Frontend integration documentation
adk-integrations
skill — Integration lifecycle documentation

adk
技能——核心ADK知识（操作、工作流、对话等）
adk-evals
技能——测试与评估文档
adk-frontend
技能——前端集成文档
adk-integrations
技能——集成生命周期文档