unifi-mcp: Skill for Claude Code

Skill Reference & Generated Manifest Drift Maintenance

Each app has a generated tool manifest (e.g. apps/protect/src/unifi_protect_mcp/tools_manifest.json) and a generated skill reference doc under the corresponding plugin (e.g. plugins/unifi-network/skills/unifi-network/references/network-tools.md, plugins/unifi-access/skills/unifi-access/references/access-tools.md) that uses <!-- AUTO:tools:<category> --> marker blocks. Both are generated artifacts — a pure function of the Python source (docstrings, parameter signatures, tool registrations). packages/unifi-mcp-shared/src/unifi_mcp_shared/manifest_generator.py implements the shared manifest-generation logic that each app's own generator wrapper script calls (e.g. apps/network/scripts/generate_tool_manifest.py, invoked via that app's make manifest target). Nothing about these generated files should ever be hand-authored. The recurring failure mode in this codebase is not that regeneration is hard — it's that CI's drift-check only diffs already-rendered content against disk. It cannot detect a missing section, a missing marker, or a description that's technically present but shallower/staler than the source. Those gaps are only caught by a human applying the checklists below.

Prerequisites

• Locate the generator scripts for this repo before starting — search scripts/ (e.g. Grep -r "tools_manifest" scripts/ and Grep -r "generate_tool_manifest\|generate_skill_references" scripts/) rather than assuming a fixed filename, since generator script names can move between refactors. Verified examples in this repo: scripts/generate_skill_references.py, the shared packages/unifi-mcp-shared/src/unifi_mcp_shared/manifest_generator.py module, and the per-app wrapper it documents (e.g. apps/network/scripts/generate_tool_manifest.py, run via that app's make manifest target).
• Locate the skill reference doc(s) for the category you're touching by searching repo-wide for AUTO:tools: markers (Grep -rl "AUTO:tools:" .) rather than assuming a fixed path. These live under each plugin's own skill references directory (plugins/<plugin>/skills/<plugin>/references/*.md) — not under apps/ — and the exact category set can vary per plugin.
• Regenerate inside a worktree venv synced to the locked dependencies. Using system Python or a stale venv can produce output that's subtly different from what CI would generate, defeating the point of regenerating at all.
• make pre-commit does regenerate manifests when it's actually run — both the root Makefile (pre-commit: format generate lint test check-generated worker-typecheck, where generate includes manifest) and each app's own Makefile (e.g. apps/network/Makefile: pre-commit: format manifest server-manifest lint test). But there is no .pre-commit-config.yaml wiring it into a git hook — it's a manual make target. Don't assume a branch's manifest is current just because its author "probably ran pre-commit"; check explicitly (Procedure A) whenever behavior-relevant source changed.