Web Observability Plugin

Teaches Claude how to instrument web apps correctly — what to measure, what context to attach, and what mistakes to avoid.

The Problem

Most web teams instrument poorly:

• Too little — Can't debug production issues
• Too much — Noise, cost, performance impact
• Wrong context — Errors without enough data to act on

This plugin teaches Claude to capture both user intent (what they tried to do) and system state (browser conditions, errors, performance) so you can answer "Why did this fail, and for whom?"

Installation

claude plugin marketplace add caleb-davis-plugins/web-observability
claude plugin install web-observability

Usage

Commands

/instrument
/audit src/features/checkout

Natural Prompts

"How should I instrument this checkout flow?"
"What's wrong with my Core Web Vitals?"
"Set up session replay with Sentry"
"Review this code for observability anti-patterns"
"Track this user journey from signup to first purchase"

Commands

Command	Description
/instrument	Generate prioritized instrumentation plan for React, Vue, Angular, Svelte, etc.
/audit [path]	Scan existing code for instrumentation gaps and anti-patterns

Agents

codebase-analyzer

Explores web codebases to understand architecture and identify instrumentation opportunities.

Focus Areas:

• Framework and meta-framework detection (React, Next.js, Vue, Nuxt, etc.)
• Existing telemetry SDK inventory
• Routing, state management, data fetching patterns
• Key user flows and entry points

Output:

• Framework summary with version
• Architecture pattern identification
• Existing SDK coverage assessment
• Gap analysis with priority ranking

instrumentation-reviewer

Reviews code changes for observability issues before they ship.

Focus Areas:

• Anti-patterns (PII leaks, high cardinality, blocking main thread)
• Missing context (no user ID, no route, no session)
• Naming consistency
• Vendor best practices

Output:

• Issues by severity with file:line references
• Specific fixes with code examples
• Vendor guideline references

Skills

11 skills that activate automatically based on context:

Skill	Trigger
instrumentation-planning	"What should I measure?"
core-web-vitals	"LCP is slow", "Fix CLS"
error-tracking	"Set up error boundaries"
source-map-setup	"Configure source maps"
route-transition-tracking	"Track page navigation"
api-tracing	"Trace API requests"
session-replay	"Set up session replay"
user-journey-tracking	"Track user funnels"
hydration-performance	"SSR hydration is slow"
bundle-performance	"JavaScript is blocking"
synthetic-monitoring	"Set up Lighthouse CI"

Frameworks Supported

Framework	Guide
React	references/frameworks/react.md
Next.js	references/frameworks/nextjs.md
Vue 3	references/frameworks/vue.md
Nuxt 3	references/frameworks/nuxt.md
Angular	references/frameworks/angular.md
Svelte	references/frameworks/svelte.md
SvelteKit	references/frameworks/sveltekit.md
Remix	references/frameworks/remix.md
Astro	references/frameworks/astro.md

Platforms Supported

Platform	Guide
Sentry	references/platforms/sentry.md
Datadog RUM	references/platforms/datadog.md
New Relic	references/platforms/newrelic.md
LogRocket	references/platforms/logrocket.md
FullStory	references/platforms/fullstory.md
PostHog	references/platforms/posthog.md
Vercel Analytics	references/platforms/vercel-analytics.md
OpenTelemetry	references/platforms/opentelemetry.md

When to Use

Use this plugin for:

• Adding observability to a new or existing web app
• Setting up error tracking, performance monitoring, or session replay
• Improving Core Web Vitals (LCP, INP, CLS)
• Choosing between vendors (Sentry, Datadog, LogRocket, etc.)
• Reviewing instrumentation code for anti-patterns

Don't use for:

• Mobile app observability (use mobile-observability plugin)
• Backend/server observability
• General logging questions unrelated to web frontend

Architecture: Context Engineering

This plugin follows Anthropic's best practices for token-efficient context loading:

JIT Reference Loading

References are loaded only when needed, not upfront:

Tier	When to Load	Files
Never	Skills are self-contained	-
On detection	Framework/SDK unclear	references/framework-detection.md, references/telemetry-detection.md
On flagging	Reporting anti-patterns	references/anti-patterns.md
On implementation	Generating code	references/frameworks/*.md, references/platforms/*.md
On code generation	Specific templates	templates/*.ts

Single Source of Truth

Concern	Canonical File
Anti-patterns	references/anti-patterns.md
Framework detection	references/framework-detection.md
Telemetry detection	references/telemetry-detection.md

Slim Definitions

Component	Target Lines	Focus
Agent	60-100	Behavior, not data
Skill	50-70	Principles, reference templates
Command	60-70	Orchestration only
Hook	1 prompt	Short, reference docs

Directory Structure

web-observability/
├── commands/       # /instrument, /audit (thin orchestrators)
├── agents/         # codebase-analyzer, instrumentation-reviewer
├── skills/         # 11 instrumentation skills (principles only)
├── hooks/          # Single consolidated anti-pattern hook
├── templates/      # Production-ready code templates
└── references/     # JIT-loaded guides (frameworks, platforms, patterns)

Philosophy

1. Start with Core Web Vitals — LCP, INP, CLS are Google's ranking factors
2. Context over volume — One error with full context beats 100 without
3. User intent + system state — Link what users tried to do with browser conditions
4. Avoid anti-patterns early — PII leaks and high cardinality are expensive to fix later
5. Don't block the main thread — Telemetry that hurts INP defeats the purpose

Author

Caleb Davis

License

MIT — see LICENSE