系列《把经验封装成能力Agent Skills 设计与落地》本文是系列第十四篇。上一篇我们拆了文档处理类 Skill它们围绕复杂文件格式展开解包、转换、提取、重算和校验。这一篇换一个方向开发工具类 Skill。它们不只是处理文件而是帮助 Agent 使用本地环境、命令行工具、浏览器、测试框架和协议文档形成可反复执行的工程反馈循环。1. 开发工具类 Skill 解决什么问题开发工具类 Skill 面向的是工程现场。用户的需求通常不是“生成一段文本”而是验证一个页面是否能正常工作。启动前端和后端服务。查看浏览器控制台日志。复现一个 UI 问题。创建一个 MCP Server。根据协议规范实现一组工具。运行构建、测试和检查命令。根据错误反馈继续修复。这些任务有一个共同点结果不是一次性回答而是一轮又一轮的反馈。文档处理类 Skill 更像“处理输入文件生成输出文件”。开发工具类 Skill 更像“理解环境执行工具观察反馈再决定下一步”。所以它们特别强调先理解项目环境。再执行最小命令。再根据反馈继续行动。避免不必要的副作用。避免把上下文塞满源码和日志。2. 和文档处理类 Skill 有什么不同可以先用一张表对比。类型核心对象主要风险典型验证文档处理类 Skill.docx、.pdf、.xlsx等文件文件损坏、格式丢失、内容提取错误文件可打开、公式无错、字段齐全开发工具类 Skill服务、浏览器、测试框架、协议、代码仓库命令副作用、环境不一致、测试不稳定构建通过、测试通过、浏览器行为符合预期文档处理类 Skill 的关键是“文件结构”。开发工具类 Skill 的关键是“运行反馈”。这意味着开发工具类 Skill 通常要处理命令是否会启动长进程。服务是否已经监听端口。浏览器是否等到页面真正渲染。测试失败是代码问题、环境问题还是选择器问题。日志很多时应该读哪一部分。什么时候应该停止继续尝试转而向用户说明阻塞。3. 开发工具类 Skill 的通用分工开发工具类 Skill 的分工可以这样理解角色负责什么Agent理解任务、选择最小验证路径、解释错误、决定下一步命令行工具启动服务、构建项目、运行测试、生成输出脚本封装复杂命令、管理生命周期、收集稳定结果参考资料保存协议、框架用法、最佳实践和限制测试/日志提供真实反馈证明行为是否符合预期这里最重要的是Agent 不应该只“猜测”代码是否正确而应该尽量用工具获得证据。但反过来它也不应该盲目执行所有命令。好的开发工具类 Skill 会让 Agent 在证据和成本之间找到平衡。4. 开发工具类 Skill 的三个关键词开发工具类 Skill 可以用三个关键词概括。4.1 环境它要知道当前项目如何运行。例如前端启动命令是什么。后端端口是什么。是否需要多个服务。是否已有服务在运行。是否需要安装依赖。是否有测试框架。没有环境理解工具调用很容易失败。4.2 反馈它要能读取真实反馈。例如构建输出。单测结果。浏览器截图。DOM 状态。控制台日志。网络请求。MCP Inspector 的连接结果。开发任务不是“写完代码就结束”而是“用反馈证明代码能工作”。4.3 收敛它要帮助 Agent 收敛。也就是说不要漫无目的地读完整仓库。运行所有测试。打开所有日志。尝试所有工具。修改大量无关文件。开发工具类 Skill 应该鼓励最小验证。先用小证据判断方向再逐步扩大范围。5.webapp-testingSkill用浏览器验证真实行为先看webapp-testing。它的定位很清楚使用 Playwright 与本地 Web 应用交互和测试。它支持验证前端功能。调试 UI 行为。捕获浏览器截图。查看浏览器日志。和本地服务配合运行自动化脚本。这类 Skill 的价值非常直接。很多前端问题单看源码不够。你需要真的打开页面看它是否渲染、按钮是否可点击、表单是否提交、控制台是否报错、网络请求是否成功。6.webapp-testing的触发范围webapp-testing的 description 并不长description:Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality,debugging UI behavior,capturing browser screenshots,and viewing browser logs.它覆盖了四类核心场景testing local web applications。verifying frontend functionality。debugging UI behavior。capturing screenshots and browser logs。这个 description 的边界也比较自然它不是通用前端开发 Skill。它更偏“验证和调试”。如果用户只是说“写一个按钮组件”不一定需要它。如果用户说“这个页面点击没反应帮我验证一下”就非常匹配。7.webapp-testing的核心思想先侦察再行动这个 Skill 里最重要的模式是Reconnaissance-Then-Action可以翻译成先侦察再行动。在动态 Web 应用里不能一上来就猜选择器。正确流程是打开页面。等待网络和 JavaScript 执行完成。截图或读取渲染后的 DOM。根据真实渲染结果识别选择器。再执行点击、输入、断言等动作。这和很多人第一次写浏览器自动化脚本的习惯相反。常见错误是看到源码里有一个按钮就直接用这个选择器点击。但真实页面可能还没加载完。按钮被条件渲染隐藏。文案经过国际化替换。元素在 iframe 或弹层里。组件库生成了不同 DOM。所以webapp-testing强调先观察真实页面。8. 为什么要等待networkidle动态前端应用通常要等 JavaScript 执行。如果页面还没加载完就读取 DOM很可能得到空状态或中间状态。webapp-testing明确提醒page.goto(http://localhost:5173)page.wait_for_load_state(networkidle)这一步看起来简单但非常关键。很多 UI 自动化失败不是功能错了而是测试太急。测试脚本比用户操作快得多。用户等待一秒看到页面正常脚本可能在 100 毫秒内就开始查找元素然后失败。所以等待策略是开发工具类 Skill 中非常重要的经验。9.with_server.py把服务生命周期封装起来webapp-testing提供了一个关键脚本scripts/with_server.py它的职责是启动一个或多个服务。等待端口就绪。运行自动化脚本。执行完成后清理服务进程。典型用法python scripts/with_server.py--servernpm run dev--port5173-- python automation.py多个服务也可以python scripts/with_server.py\--servercd backend python server.py--port3000\--servercd frontend npm run dev--port5173\-- python automation.py这个脚本体现了开发工具类 Skill 的一个重要原则把容易出错的环境管理交给脚本。Agent 不需要每次都手动启动服务、等端口、记 PID、最后清理。脚本把这个流程变成稳定入口。10. 为什么强调先运行--helpwebapp-testing特别强调Always run scripts with--helpfirst.这不是形式主义。这是为了减少上下文污染和误用。脚本可能很长如果 Agent 一上来就读完整源码会浪费大量上下文。更好的方式是先把脚本当黑盒。运行--help看参数。根据帮助信息调用。只有当默认能力不够时再读源码或自定义方案。这和第五篇讲的渐进式加载完全一致。开发工具类 Skill 特别容易因为“读太多源码、读太多日志”导致上下文成本失控。所以工具入口要尽量黑盒化。11.webapp-testing的目录组织这个 Skill 的目录很简洁webapp-testing/ ├── SKILL.md ├── scripts/ │ └── with_server.py └── examples/ ├── console_logging.py ├── element_discovery.py └── static_html_automation.py它没有大量参考资料。因为它的核心不是长知识而是可执行模式服务生命周期管理。Playwright 脚本。元素发现。控制台日志。静态 HTML 自动化。这些更适合放在脚本和示例中。12.webapp-testing的典型工作流可以把它总结成这条流程确认页面类型 - 管理服务 - 打开页面 - 等待渲染 - 侦察 DOM/截图 - 执行动作 - 收集日志 - 输出结论展开一点判断是静态 HTML 还是动态 Web App。如果是动态应用确认服务是否已运行。如果服务未运行使用with_server.py管理服务生命周期。编写轻量 Playwright 脚本。打开页面并等待networkidle。截图或读取 DOM。根据真实页面状态选择 selector。执行用户关心的操作。捕获控制台日志、错误或截图。汇总验证结果和未覆盖风险。这就是开发工具类 Skill 的“反馈循环”。13.webapp-testing的常见风险13.1 测试不稳定UI 测试容易不稳定。常见原因页面还没加载完。动画未结束。网络请求延迟。元素被遮挡。文案变化。测试依赖真实后端数据。Skill 应该引导 Agent 使用明确等待和可观察证据而不是靠固定 sleep 堆时间。13.2 选择器脆弱如果选择器依赖复杂 CSS 层级很容易因为样式调整失效。更稳的方式是优先使用role。text。label。test id。稳定的语义选择器。13.3 服务副作用启动服务可能占用端口、写入缓存、连接数据库。Skill 应该提醒 Agent明确端口。尽量使用本地或测试环境。运行结束后清理进程。不在不清楚后果时执行破坏性操作。13.4 过度自动化有些问题只需要截图和日志就能定位。不一定要写复杂 E2E。好的工具类 Skill 会鼓励最小验证而不是一上来写一套大测试。14.mcp-builderSkill把协议、框架和评估组织成工程流程再看mcp-builder。它和webapp-testing完全不同。webapp-testing是使用工具验证已有应用。mcp-builder是指导 Agent 创建一个高质量 MCP Server。它的目标是创建能让 LLM 通过工具与外部服务交互的 MCP Server。这类 Skill 的复杂点不是“打开页面”而是理解 MCP 协议。选择传输方式。设计工具。设计输入和输出 schema。处理鉴权。处理分页。给出可行动错误信息。测试 MCP Server。创建评估问题。这已经接近一个完整工程项目。15.mcp-builder的触发范围它的 description 是description:Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services,whether in Python (FastMCP) or Node/TypeScript (MCP SDK).这个 description 很清楚地包含能力创建高质量 MCP Server。目标让 LLM 通过工具与外部服务交互。任务场景集成外部 API 或服务。技术栈Python FastMCP 或 Node/TypeScript MCP SDK。它不是一般后端开发 Skill。它专门服务于 MCP Server 设计与实现。16.mcp-builder的四阶段流程mcp-builder把任务拆成四个阶段。阶段目标Phase 1深入研究和规划Phase 2实现Phase 3审查和测试Phase 4创建评估这正是复杂工程类 Skill 的典型做法。它不是只给代码模板而是把项目从需求理解推进到验证评估。17. Phase 1研究和规划第一阶段强调研究。它要求 Agent 理解MCP 协议文档。SDK 文档。目标服务 API。鉴权方式。数据模型。常见操作。工具覆盖范围。这说明开发工具类 Skill 不一定一开始就写代码。有些任务必须先查资料。尤其是协议和 API 类任务凭记忆写代码风险很高。mcp-builder明确要求从 MCP sitemap 和相关文档入手再根据语言选择 TypeScript 或 Python 指南。这和下一篇要讲的知识库型 Skill 也有联系。18. 工具设计API 覆盖和工作流工具的平衡mcp-builder提出一个关键问题API Coverage vs. Workflow Tools。也就是要不要把 API endpoint 尽量完整地暴露出来还是只做少量高层工作流工具二者都有价值。完整 API 覆盖给 Agent 灵活组合的能力。高层工作流工具对常见任务更方便。当不确定时mcp-builder倾向于优先保证较完整的 API 覆盖。这背后的原因是MCP Server 的使用者是 Agent。Agent 可能会根据任务组合多个原子工具。如果工具太少、太高层反而限制组合能力。19. 工具命名和可发现性MCP 工具命名非常重要。mcp-builder的参考资料建议{service}_{action}_{resource}例如slack_send_message github_create_issue github_list_repos这看起来像命名细节但对 Agent 很关键。Agent 选择工具时依赖工具名和描述。如果工具叫do_action它很难判断该不该用。如果工具叫github_create_issue它的服务、动作和资源都很明确。这和 Skill 的 description 类似命名本身就是召回信号。20. 输入 schema 和输出 schema开发工具类 Skill 经常要指导 Agent 写代码。mcp-builder特别强调输入 schema。TypeScript 通常用 Zod。Python 通常用 Pydantic。好的输入 schema 应该类型明确。参数有描述。有合理约束。可选参数清楚。错误时能给出可行动提示。输出也要尽量结构化。因为 MCP Server 的使用者是 Agent结构化输出可以减少解析成本。例如列表工具应该返回items。count。total。has_more。next_cursor 或 next_offset。这比返回一大段无结构文本更适合 Agent 继续推理。21. 分页和上下文管理mcp-builder的最佳实践特别强调分页尊重limit参数。默认返回 20 到 50 条。返回分页元数据。不要一次加载所有结果。这和 Skill 的上下文管理是同一个思想。如果一个 MCP 工具每次返回几千条记录Agent 很容易被上下文淹没。好的工具应该帮 Agent 控制信息量。例如{total:150,count:20,offset:0,items:[],has_more:true,next_offset:20}这让 Agent 可以逐步探索而不是一次吞下所有数据。22. 可行动错误信息开发工具类 Skill 不能只说“失败了”。错误信息应该帮助 Agent 继续修复。不好的错误Error: request failed更好的错误Authentication failed: missing GITHUB_TOKEN. Set GITHUB_TOKEN in the environment and retry.或者Invalid repository name. Expected format is owner/repo, for example octocat/hello-world.对 Agent 来说错误信息是下一步行动的输入。所以 MCP 工具和测试脚本都应该输出可行动错误。23. 安全和副作用标注mcp-builder要求为工具添加 annotations。常见标注包括readOnlyHint。destructiveHint。idempotentHint。openWorldHint。这些标注能帮助 Agent 判断工具风险。比如读取 issue 列表是 read-only。删除仓库是 destructive。重复执行创建操作可能不是 idempotent。调用外部 API 可能是 open-world。这对开发工具类 Skill 非常重要。因为它们经常连接真实服务。一个没有风险标注的工具很容易被误用。24. Phase 3构建、测试和 Inspectormcp-builder的第三阶段是审查和测试。不同语言有不同验证方式。TypeScript 可能运行npmrun buildPython 可能运行python-mpy_compile your_server.py还可以用 MCP Inspector 测试连接和工具调用。这体现了开发工具类 Skill 的基本原则代码生成不是结束构建和连接验证才是工程闭环。如果一个 MCP Server 代码看起来对但 Inspector 连接不上那它还不能算完成。25. Phase 4创建评估mcp-builder的最后阶段是创建评估。这点很值得注意。它不是只要求“工具能调用”而是要求LLM 能否使用这些工具完成真实复杂问题。评估问题需要真实。独立。非破坏性。需要多步工具调用。有单一可验证答案。答案稳定不随时间频繁变化。这比普通单元测试更接近 Agent 工具质量。因为 MCP Server 的质量不是“有多少 endpoint”而是“Agent 能不能用这些工具解决真实任务”。26.mcp-builder的目录组织这个 Skill 的目录也很有代表性mcp-builder/ ├── SKILL.md ├── reference/ │ ├── evaluation.md │ ├── mcp_best_practices.md │ ├── node_mcp_server.md │ └── python_mcp_server.md └── scripts/ ├── connections.py ├── evaluation.py ├── example_evaluation.xml └── requirements.txt它的资源组织比webapp-testing更重。原因是 MCP Server 开发涉及协议知识。语言差异。SDK 用法。最佳实践。评估规范。这些内容不适合全塞进SKILL.md。所以它拆到了reference/。这就是渐进式加载的实际应用。27. 两个案例的差异webapp-testing和mcp-builder都是开发工具类 Skill但差异很大。对比项webapp-testingmcp-builder主要任务验证本地 Web 应用创建 MCP Server核心工具Playwright、服务管理脚本MCP SDK、协议文档、Inspector主要资源脚本和示例参考资料和实现指南反馈方式浏览器状态、截图、日志构建、连接、工具调用、评估最大风险测试不稳定、选择器脆弱、服务副作用工具设计不清、协议误用、鉴权和安全风险这个对比说明开发工具类 Skill 不是一种固定模板。它们共同点是都围绕工具和反馈。但资源组织要根据任务特征调整。28. 开发工具类 Skill 的通用结构如果要设计一个开发工具类 Skill可以从这个结构开始my-dev-tool-skill/ ├── SKILL.md ├── scripts/ │ ├── run_check.py │ └── collect_evidence.py ├── references/ │ ├── workflow.md │ └── troubleshooting.md └── examples/ └── basic_usage.py但不要机械照搬。如果任务以工具执行为主scripts/更重要。如果任务以协议或框架知识为主references/更重要。如果任务以使用模式为主examples/更重要。29.SKILL.md应该写什么开发工具类 Skill 的SKILL.md建议包含Scope。Trigger Boundaries。Environment Discovery。Workflow。Tool Routing。Safety Rules。Validation。Failure Handling。示例## Workflow 1. Identify the project type and available commands. 2. Prefer the smallest command that validates the users request. 3. Run helper scripts with --help before using them. 4. Collect actionable evidence such as logs, screenshots, response codes, or test output. 5. Summarize what was verified, what failed, and what remains unverified.这里的核心不是“写代码”而是“找到最小验证路径”。30. 常见风险一读太多源码开发任务很容易陷入读源码。Agent 可能会想我先把整个项目结构都看一遍。但很多时候不需要。比如用户只是要验证登录按钮是否可点击。更好的路径可能是找到启动命令。启动应用。打开页面。点击按钮。捕获结果。只有验证失败时再读相关组件或日志。这就是“先反馈再深入”的思路。31. 常见风险二命令副作用开发工具类 Skill 会运行命令。命令可能有副作用修改文件。启动服务。写数据库。发网络请求。删除资源。提交代码。所以 Skill 应该要求 Agent优先选择只读命令。对长进程使用生命周期管理。对破坏性命令保持克制。对外部服务写操作明确说明风险。记录实际执行过的验证命令。这类规则比普通写作 Skill 更重要。32. 常见风险三测试不稳定开发工具类 Skill 很容易遇到不稳定测试。原因包括时间等待不充分。环境依赖缺失。网络波动。本地端口冲突。数据状态变化。外部 API 限流。Skill 不应该把一次失败直接解释成代码错误。更好的做法是读取错误信息。判断是否环境问题。尝试最小复现。必要时重新运行一次。如果仍失败再归类为稳定问题。33. 常见风险四日志过载构建和测试日志可能非常长。Agent 如果全部读入很容易浪费上下文。Skill 应该鼓励先看失败摘要。再看第一处错误。再看堆栈关键行。必要时按关键词过滤。不要把所有日志当成同等重要。这和mcp-builder里的分页思想一致。工具返回和日志读取都要控制信息量。34. 常见风险五验证范围过大用户可能只改了一个按钮样式。如果每次都跑完整 E2E、完整构建、完整回归成本会很高。开发工具类 Skill 应该支持分层验证级别适用场景静态检查语法、格式、类型单元测试局部逻辑组件测试UI 组件行为冒烟测试核心路径是否可用E2E用户完整流程手工确认视觉或产品判断默认从最小足够验证开始。35. 设计“本地 API 冒烟测试”Skill现在进入实践任务设计一个“本地 API 冒烟测试”Skill包含脚本入口、测试流程和错误处理规范。这个 Skill 的目标是启动或连接本地 API 服务。执行少量核心端点检查。验证状态码、响应结构和关键字段。输出清晰的通过、失败和未验证项。避免对真实环境产生副作用。它是一个典型开发工具类 Skill。36. 目录草图可以这样设计local-api-smoke-test/ ├── SKILL.md ├── scripts/ │ ├── with_api_server.py │ └── smoke_check.py ├── references/ │ ├── endpoint-config.md │ └── failure-handling.md └── examples/ └── smoke-config.example.json各文件职责文件职责SKILL.md触发、流程、工具路由、安全边界和输出格式scripts/with_api_server.py启动 API 服务、等待端口、执行检查、清理进程scripts/smoke_check.py读取配置并请求核心端点references/endpoint-config.md描述端点配置格式references/failure-handling.md常见失败和处理策略examples/smoke-config.example.json示例配置37. description 草案可以这样写name:local-api-smoke-testdescription:Run lightweight smoke tests against a local API service. Use this skill when the user wants to verify that a local backend or HTTP API starts correctly,responds on expected endpoints,returns expected status codes,or has no obvious integration breakage after code changes. The expected output is a concise Chinese verification report with passed,failed,and unverified checks. Do not use this skill for full load testing,destructive production API calls,security scanning,or broad end-to-end testing unless the user explicitly asks for those tasks.它包含能力本地 API 冒烟测试。输入对象本地后端或 HTTP API。触发表达启动验证、端点检查、状态码、集成破坏。产物中文验证报告。排除条件压测、生产破坏性调用、安全扫描、完整 E2E。38. Workflow 草案可以写成## Workflow 1. Identify the API start command, base URL, port, and smoke endpoints. 2. Prefer read-only endpoints such as health checks, version endpoints, and list queries. 3. Run helper scripts with --help before using them. 4. Start the local API server only when it is not already running. 5. Wait until the port or health endpoint is ready. 6. Execute the smoke checks with explicit timeouts. 7. Capture status code, response time, and key response fields. 8. Summarize passed, failed, skipped, and unverified checks. 9. Do not call destructive endpoints unless the user explicitly confirms.这个流程的核心是先发现环境。再选择只读端点。再执行最小检查。最后输出可行动结果。39. API 冒烟测试配置可以用一个 JSON 配置描述端点。{base_url:http://localhost:3000,checks:[{name:health,method:GET,path:/health,expected_status:200,required_fields:[status]},{name:version,method:GET,path:/version,expected_status:200,required_fields:[version]}]}第一版只支持只读 GET 请求就够了。不要一开始就支持任意方法、鉴权、数据准备和清理。冒烟测试的目标是快速发现明显问题。40.smoke_check.py的职责smoke_check.py可以负责读取配置。请求每个端点。检查状态码。检查必填字段。设置超时。输出 JSON 结果。示例输出{summary:{passed:2,failed:0,skipped:0},checks:[{name:health,status:passed,status_code:200,duration_ms:32}]}脚本输出 JSONAgent 再把它解释成中文报告。这就是工具和 Agent 的分工。41. 错误处理规范references/failure-handling.md可以记录常见错误。错误可能原因建议处理端口无法连接服务未启动、端口错误、启动失败检查启动命令和服务日志健康检查超时服务启动慢、依赖未就绪延长超时或检查依赖状态码不符路由错误、鉴权缺失、服务异常查看响应体和服务日志JSON 解析失败返回 HTML 错误页或非 JSON 响应输出响应摘要并检查路由字段缺失API schema 变化或版本不匹配标记失败并给出缺失字段连接到生产环境base_url 非 localhost 或测试域名停止执行并请求确认错误处理要可行动。不要只说检查失败。要说明哪个检查失败。实际结果是什么。可能原因是什么。下一步建议是什么。42. 输出报告格式最终输出可以采用中文报告## 本地 API 冒烟测试结果 测试目标http://localhost:3000 总体结果2 项通过1 项失败0 项跳过。 ### 通过项 1. GET /health 返回 200包含字段 status。 2. GET /version 返回 200包含字段 version。 ### 失败项 1. GET /api/users 期望 200实际 500。 - 响应摘要database connection failed - 建议检查本地数据库连接和环境变量。 ### 未验证项 1. 未验证写接口避免产生数据副作用。这样的报告比单纯贴脚本输出更有用。43. 验证策略这个 Skill 自己也需要测试。可以设计 5 条测试 prompt“帮我验证本地 API 的/health是否正常。”“服务启动在 3000 端口帮我做个冒烟测试。”“根据这个配置检查两个只读端点。”“帮我压测这个接口。” 这应该不走冒烟测试流程或明确说明不是当前 Skill 范围。“调用生产接口删除测试用户。” 这应该拒绝或要求明确确认。评估重点是否优先选择只读端点。是否避免生产写操作。是否记录实际执行的检查。是否输出通过、失败、未验证项。错误信息是否可行动。44. 开发工具类 Skill 自查清单设计开发工具类 Skill 时可以用这张表。检查项问题任务边界这个 Skill 是验证、调试、构建、集成还是生成代码环境发现是否说明如何发现启动命令、端口、依赖和配置最小验证是否优先执行能回答用户问题的最小命令生命周期长进程是否有启动、等待、清理策略工具入口脚本是否支持--help参数是否明确反馈收集是否收集日志、截图、状态码、构建输出或连接结果副作用是否避免破坏性命令和生产写操作上下文控制是否避免读完整源码、完整日志或过大返回值错误处理错误信息是否可行动验证结论是否区分已验证、失败和未验证如果这些问题能回答清楚开发工具类 Skill 就有比较好的工程基础。45. 常见设计错误45.1 错误一把工具 Skill 写成代码生成 Skill比如webapp-testing的目标不是“生成任意前端代码”。它的重点是测试和调试。如果边界不清就会和前端开发 Skill 混在一起。45.2 错误二没有服务生命周期管理如果 Skill 要测试本地服务却不说明如何启动、等待和清理服务就容易留下后台进程或端口占用。with_server.py的价值就在这里。45.3 错误三不看真实反馈开发工具类 Skill 最怕只凭源码猜。如果能运行测试、打开浏览器、连接 Inspector就应该尽量拿证据。45.4 错误四把日志全部塞进上下文日志要筛选。先看错误摘要和关键堆栈不要把所有输出都当作同等重要。45.5 错误五忽略副作用构建、测试、API 调用、脚本执行都可能有副作用。Skill 应该默认偏向只读和本地验证。45.6 错误六只验证工具存在不验证 Agent 能否使用这在 MCP Server 中尤其常见。工具能调用不代表 Agent 能用它完成真实任务。所以mcp-builder才强调评估问题。46. 小结这一篇拆解了两个开发工具类 Skillwebapp-testing和mcp-builder。可以记住三句话开发工具类 Skill 的核心是反馈循环理解环境、执行最小验证、收集证据、解释结果、决定下一步。webapp-testing通过 Playwright、截图、DOM、日志和服务管理脚本验证真实 UI 行为。mcp-builder通过协议研究、工具设计、schema、构建测试和评估问题指导 Agent 完成复杂工程实现。如果第十三篇关注的是“复杂文件如何稳定处理”第十四篇关注的就是“复杂工程环境如何稳定验证”。下一篇我们会继续拆知识库型 Skill以claude-api为例看它如何让 Agent 在 API 漂移和 SDK 变化中避免凭记忆写错。47. 实践任务请设计一个“本地 API 冒烟测试”Skill要求包含脚本入口、测试流程和错误处理规范。可以从这个目录开始local-api-smoke-test/ ├── SKILL.md ├── scripts/ │ ├── with_api_server.py │ └── smoke_check.py ├── references/ │ ├── endpoint-config.md │ └── failure-handling.md └── examples/ └── smoke-config.example.json47.1 descriptionname:local-api-smoke-testdescription:Run lightweight smoke tests against a local API service. Use this skill when the user wants to verify that a local backend or HTTP API starts correctly,responds on expected endpoints,returns expected status codes,or has no obvious integration breakage after code changes. The expected output is a concise Chinese verification report with passed,failed,and unverified checks. Do not use this skill for full load testing,destructive production API calls,security scanning,or broad end-to-end testing unless the user explicitly asks for those tasks.47.2 Workflow1. Identify the API start command, base URL, port, and smoke endpoints. 2. Prefer read-only endpoints such as /health, /version, and safe list queries. 3. Run helper scripts with --help before using them. 4. Start the local API server only when it is not already running. 5. Wait until the port or health endpoint is ready. 6. Execute smoke checks with explicit timeouts. 7. Capture status code, response time, response summary, and required fields. 8. Summarize passed, failed, skipped, and unverified checks. 9. Do not call destructive endpoints unless the user explicitly confirms.47.3 输出格式## 本地 API 冒烟测试结果 测试目标 总体结果 ### 通过项 1. ### 失败项 1. ### 未验证项 1. ### 后续建议 1.完成这个练习后你会更清楚地看到开发工具类 Skill 的关键不是把命令列表堆起来而是把环境发现、工具调用、反馈收集、副作用控制和验证结论组织成一条可复用工作流。