用途
unifi-docs-sync 用于解决 unifi-mcp-server 仓库中同一能力面在四个位置重复暴露且可能发生漂移的问题。四个表面分别是：MCP 工具（运行时生效，来源为 src/tool_registry.py 的注册）、A2A agent card（产物为 agent-card.json，来源为 src/a2a/capabilities.py 的实时注册表）、原生 MCP 提示（运行时生效，来源为 src/prompts/catalog.py）、文档（API.md、README.md、skills/ 下的文件）。该技能提供一套检查清单和操作流程，确保在变更时这四个表面保持对齐。
主要能力
- 从实时注册表读取真实工具清单，避免凭记忆写入工具名。示例命令会清除 PYTHONPATH 并设置环境变量后运行 Python 脚本，打印工具数量及名称；本地模式注册 343 个工具，云模式注册 71 个，需按所记录的模式检查。
- 通过 src/tool_registry.py:TOOL_TIERS 检查每个工具的风险等级，确保文档中标注的读写属性与注册表一致。
- 新增工具时的完整步骤：在正确的 src/tools/ 模块中实现并使用 @read_tool 或 @write_tool 装饰器；写工具需提供 confirm 参数，可预览的操作还需提供 dry_run 参数；检查 tests/unit/test_tool_declarations.py 确保读工具不会调用 post、put、patch 或 delete；在 API.md 的对应分类下添加工具及参数；在 skills/ 下对应技能中添加；若为新模块，还需更新 src/tool_registry.py 的 profile 列表和开发者技能中的模块映射；工具面变化后重新生成 agent card：python scripts/generate_agent_card.py。
- 移除或重命名工具时，使用 grep 搜索整个仓库，定位工具名出现的所有位置：API.md、skills/*/SKILL.md、src/prompts/catalog.py、src/a2a/capabilities.py、src/a2a/agent_card.py。
- 原生提示目录的维护：src/prompts/catalog.py 在证据列表和需求组两处命名工作流所需工具；工作流仅在其需求命名的工具已注册时才对外提供，重命名工具会破坏工作流可用性；tests/unit/prompts/test_prompt_catalog.py 会检查每个命名工具是否存在于实时注册表。提示文本仅是指导，不得声称已执行检查，也不得承诺服务器没有的工具。
- A2A agent card 的维护：卡片从实时注册表构建，但需要手动维护 src/a2a/capabilities.py 中声明的能力名称和 _MODULE_DOMAINS 模块到域的映射；卡片是公开元数据，不得包含凭证、控制器地址或文件系统路径，tests/unit/a2a/test_agent_card_capabilities.py 会断言这一点。
- 测试实时注册表时的注意事项：由于导入顺序依赖，需重新导入服务器模块而非复用缓存；使用显式值构建 Settings，因为测试会话会清除 UNIFI_* 变量。
- 两个守卫测试：tests/unit/test_skill_tool_references.py 确保技能表不命名服务器未注册的工具；tests/unit/test_skill_parameter_references.py 确保技能不声明工具 schema 中不存在的参数。后者读取显式参数列表（工具名后括号或方括号中反引号名称组）。
- 漂移检测命令：make test、make test-cov、make lint、make typecheck、make security、make docs-coverage、make pre-commit；其中 tests/unit/test_agent_docs.py 检查技能 frontmatter 名称与文件夹匹配、开发者技能副本一致性、文档引用路径/链接/工具名是否存在；tests/unit/a2a/test_agent_card.py 检查卡片产物与构建器是否一致。
- 复制开发者技能到 .claude/skills 和 .agents/skills 目录的循环命令；操作员技能仅保留在 skills/ 下。
使用方式
按照技能中给出的推荐顺序操作：实现并注册工具；运行聚焦测试 pytest tests/unit/tools/test_<module>.py -q；更新 API.md；更新技能并将开发者技能复制到两个 agent 目录；若工作流读取该工具则更新提示目录；重新生成 agent card；运行 make test，然后 make lint typecheck。技能还说明，先运行漂移测试再做后续更新会浪费周期。
适用场景
适用于 unifi-mcp-server 仓库的开发和维护人员，在添加、修改、移除或重命名 MCP 工具，变更 A2A agent card 或原生 MCP 提示目录，或调整部署暴露内容时使用。
限制
该技能是仓库内的文档同步检查清单，不提供自动化修复功能；所有命令和测试路径均基于 unifi-mcp-server 仓库布局。资料中未提供其他平台支持、收费模式或独立安装方式。