⚡

文档编写技能Skill write-docs

该技能用于通过执行命令和捕获真实输出来编写准确、以用户为中心的技术文档，专注于验证示例和可重现流程。关键词：文档编写、真实示例、技术文档、执行命令、SEO优化、用户友好文档。

其他 0 次安装 0 次浏览 更新于 3/18/2026

name: 文档编写 description: 编写带有真实、验证过的示例的文档。通过用户执行命令来捕获实际输出。适用于任何新文档或主要文档更新。

编写文档

通过执行操作用户来编写准确、以用户为中心的文档，并使用真实示例。

原则

  1. 先执行后文档：从不编写没有真实输出的示例
  2. 分块进行：一次编写一个部分，在继续之前获取确认
  3. 以用户为中心：为用户编写，而不是为开发者
  4. 验证先决条件：从现有文档运行设置步骤以验证它们有效
  5. Claude运行基础设施，用户运行MCP：Claude执行所有Bash/基础设施命令。仅要求用户进行MCP客户端交互（实际的用户面示例）。
  6. 修复损坏的文档：如果在设置过程中现有文档无效，停止并讨论更新这些文档后再继续。

工作流程

步骤1：确定文档目标

询问用户要编写什么文档。选项：

  • 新功能指南（例如，“知识库指南”）
  • 更新现有指南
  • API参考
  • 设置/配置指南

步骤2：新鲜环境设置

始终从清洁测试集群开始，以确保文档可重现。

遵循实际文档（docs/setup/mcp-setup.md）- 这验证它们有效。

Claude直接使用Bash工具执行所有基础设施步骤：

  1. 如果存在，拆除现有测试集群

    kind delete cluster --name dot-test 2>/dev/null || true
rm -f ./kubeconfig.yaml

  2. 创建具有本地kubeconfig的新鲜Kind集群

    kind create cluster --name dot-test --kubeconfig ./kubeconfig.yaml
export KUBECONFIG=./kubeconfig.yaml

  3. 安装先决条件（入口控制器）

    kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/deploy/static/provider/kind/deploy.yaml
# 等待入口就绪
kubectl wait --namespace ingress-nginx --for=condition=ready pod --selector=app.kubernetes.io/component=controller --timeout=300s

  4. 遵循docs/setup/mcp-setup.md（如果功能不需要，跳过控制器）

    • 步骤1：设置环境变量（使用现有API密钥）
    • 步骤2：通过Helm安装控制器（如果功能不需要，跳过）
    • 步骤3：通过Helm安装MCP服务器
    • 步骤4：告诉用户配置MCP客户端
    • 步骤5：告诉用户使用“Show dot-ai status”验证

  5. 对于未发布功能：构建和使用本地镜像

    如果记录尚未发布图表的功能：

    # 构建MCP服务器镜像
npm run build
docker build -t dot-ai:test .
kind load docker-image dot-ai:test --name dot-test

# 构建agentic-tools插件镜像
docker build -t dot-ai-agentic-tools:test ./packages/agentic-tools
kind load docker-image dot-ai-agentic-tools:test --name dot-test

    添加到helm安装的标志：

    --set image.repository=dot-ai \
--set image.tag=test \
--set image.pullPolicy=Never \
--set plugins.agentic-tools.image.repository=dot-ai-agentic-tools \
--set plugins.agentic-tools.image.tag=test \
--set plugins.agentic-tools.image.pullPolicy=Never

重要：始终对所有kubectl/helm命令使用KUBECONFIG=./kubeconfig.yaml。

如果任何步骤失败或不匹配现有文档：停止并讨论是否在继续之前更新这些文档。

为什么新鲜集群？ 确保文档示例从已知清洁状态工作，并验证设置文档。

步骤3：文档大纲

呈现要编写的部分大纲。示例：

1. 概述（做什么，何时使用）
2. 先决条件
3. 基本用法（带有真实示例）
4. 高级功能
5. API参考
6. 故障排除
7. 下一步

在继续之前获取用户对大纲的确认。

步骤4：分块编写

对于每个部分：

  1. 提议部分内容 - 简要描述本节涵盖的内容
  2. 执行或请求执行：
    • Bash命令：Claude使用Bash工具直接运行这些
    • MCP交互：要求用户发送意图并分享输出（这些是我们正在记录的用户面示例）
  3. 等待输出 - 对于MCP交互，用户分享实际输出
  4. 编写块 - 使用真实输出创建文档部分
  5. 应用编辑 - 使用编辑工具添加到文档文件
  6. 继续下一个 - 移动到下一个部分

关键区别：基础设施/设置 = Claude运行它。用户面MCP示例 = 用户运行它并分享输出。

步骤5：交叉引用检查

所有部分编写后：

  • 验证内部链接有效
  • 检查链接到其他文档的存在
  • 如果添加新工具指南，更新mcp-tools-overview.md
  • 更新任何索引页面

步骤6：最终审查

告诉用户：“文档完成。请查看完整文件，如有需要调整，请告诉我。”

示例执行请求格式

对于MCP工具操作：

请将此意图发送到您的MCP客户端：
“将本文档摄取到知识库：[内容] 带有URI：[url]”

分享您收到的响应。

对于状态检查：

请询问：“显示dot-ai状态”

分享您看到的Vector DB集合。

对于bash命令：

请运行：
kubectl get pods -n dot-ai

分享输出。

重要规则

  • 从不发明输出 - 始终使用来自用户的真实响应
  • 从不跳过验证 - 每个示例必须首先执行
  • 保持部分小 - 每块一个概念以便于审查
  • 使用用户语言 - 避免内部/开发者术语
  • 包括错误案例 - 记录事情出错时会发生什么

文件位置

  • 功能指南：docs/guides/mcp-*-guide.md
  • 设置指南：docs/setup/*.md
  • 工具概述：docs/guides/mcp-tools-overview.md
  • 图像：docs/img/