Add vMCP anti-pattern review skill

[jerm-dro]

Summary

• vMCP code reviews lack a shared vocabulary for structural issues that make the codebase harder to understand and more brittle. This adds a Claude Code skill (/vmcp-anti-pattern-review) that codifies 9 anti-patterns identified through codebase analysis, each with detection guidance and concrete alternatives.
• The catalog covers: context variable coupling, repeated body read/restore, god object, middleware overuse, string-based error classification, silent error swallowing, SDK coupling leakage, config sprawl, and mutable shared state through context.

Type of change

• Other (describe): Developer tooling — Claude Code skill for code review

Test plan

• Manual testing (describe below)

Invoked /vmcp-anti-pattern-review in Claude Code and verified it loads the skill and anti-pattern catalog correctly.

Changes

File	Change
.claude/skills/vmcp-anti-pattern-review/SKILL.md	Skill definition with instructions for scoping, checking, classifying, and presenting findings
.claude/skills/vmcp-anti-pattern-review/ANTI-PATTERNS.md	Catalog of 9 anti-patterns with definitions, detection heuristics, known instances, and recommended alternatives

Does this introduce a user-facing change?

No. This is internal developer tooling for AI-assisted code review.

Special notes for reviewers

The anti-patterns were identified through analysis of the current vMCP codebase (pkg/vmcp/, cmd/vmcp/). The "known instances" sections reference real code locations. The catalog is intended to evolve — new anti-patterns can be added as they're identified, and existing entries updated as the codebase improves.

Key design decisions in the alternatives:

• Anti-pattern #1 (context coupling) recommends pushing data onto MultiSession as the primary alternative, since it's a well-typed domain object that's 1:1 with requests and decoupled from protocol concerns.
• Anti-pattern #4 (middleware overuse) similarly recommends domain objects over middleware for non-cross-cutting concerns.
• Anti-pattern #7 (SDK coupling) accepts the two-phase session pattern as necessary but emphasizes containing it at the adapter boundary.

Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 68.82%. Comparing base (29a2c67) to head (b1a44de).
⚠️ Report is 8 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4172      +/-   ##
==========================================
- Coverage   68.85%   68.82%   -0.03%     
==========================================
  Files         467      468       +1     
  Lines       46983    47087     +104     
==========================================
+ Hits        32349    32407      +58     
- Misses      11974    11998      +24     
- Partials     2660     2682      +22     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[JAORMX]

@jerm-dro is generating an anti-pattern skill the way to go? What about having a code-review skill for vmcp in general and writing in the skill that it must watch for antipatterns. Those antipatterns could then go in a reference in the skill. wdyt?

[aponcedeleonch]

I would recommend:

• To have a CC rule listing anti-patterns: https://code.claude.com/docs/en/memory#organize-rules-with-claude/rules/
• Besides listing anti-patterns (negative), also list what would be what it should do instead (positive)

Ideally, since vMCP is part of the same CC project that toolhive, I would try to consolidate in the existing Agent code-reviewer

I am proposing: #4189
It's just a coincidence that I started to work on this on Friday. But now I have a pretty decent idea on how each of our CC resources are distributed

[jerm-dro]

• Besides listing anti-patterns (negative), also list what would be what it should do instead (positive)

The current PR has What to Do Instead sections for each anti-pattern. Did you have something else in mind? It's hard to be too prescriptive, since the ideal change depends largely on the goal of the change and the state of the code at the time of writing.

• To have a CC rule listing anti-patterns: https://code.claude.com/docs/en/memory#organize-rules-with-claude/rules/

Nice, I'll change this to also use a rule.

Ideally, since vMCP is part of the same CC project that toolhive, I would try to consolidate in the existing Agent code-reviewer

I'll also update the code-reviewer 🫡

[jerm-dro]

@JAORMX @aponcedeleonch Thanks for the review. I've addressed your comments. PTAL!

[aponcedeleonch]

nice! a couple of nits and suggestions but looks good

[jerm-dro]

Thanks @aponcedeleonch. Comments addressed! PTAL.

[aponcedeleonch]

nice!