claude-code-skills-observability
astronaut27/claude-code-skills-observability
Instalação
npx convez-ai astronaut27/claude-code-skills-observability1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
Claude Code Skills Observability
Local OpenTelemetry stack for observing a Claude Code skills catalog: skill activations, stale skills, adoption, token usage, and cost.
This repository accompanies the article:
Claude Code Skills Catalog: Observability, Stale Detection, and OpenTelemetry in Practice
What This Demo Shows
This demo includes:
- A local OpenTelemetry Collector receiving Claude Code telemetry over OTLP.
- Prometheus for
claude_code.cost.usageandclaude_code.token.usagemetrics. - Loki for
claude_code.skill_activatedandclaude_code.tool_resultevents. - Grafana with a pre-provisioned
Skill Catalog Managementdashboard. - Seven demo Claude Code skills, including two intentionally stale skills.
- A catalog generator that emits
skills-catalog.jsonandgrafana/catalog.csv.
Architecture
Claude Code
└─ OTLP gRPC :4317
└─ OpenTelemetry Collector
├─ metrics → Prometheus :9090
└─ logs → Loki :3100
Grafana :3001
├─ Prometheus datasource
├─ Loki datasource
└─ Skill Catalog Management dashboard
Repository Layout
.
├── .claude/skills/ # Demo skills
├── .env.example # Claude Code telemetry environment
├── docker-compose.yml # Local observability stack
├── grafana/
│ ├── catalog.csv # Static skill catalog for dashboard joins
│ ├── dashboards/
│ │ └── skill-catalog-management.json
│ └── provisioning/
├── loki/loki-config.yaml
├── otel-collector-config.yaml
├── prometheus.yml
├── scripts/build-catalog.sh
└── skills-catalog.json
Requirements
- Docker or Docker Desktop
- Claude Code with OpenTelemetry support
- A shell that can source
.env.example
Quick Start
Start the local observability stack:
docker-compose up -d
Load the Claude Code telemetry environment:
source .env.example
Start Claude Code from the same shell:
claude
Call some of the demo skills in normal work. Leave legacy-formatter and db-migration-helper untouched if you want the stale-skill panel to show red rows.
Open Grafana:
http://localhost:3001
Default login:
admin / admin
Open the dashboard:
Skill Catalog Management
Other local endpoints:
Prometheus: http://localhost:9090
Loki: http://localhost:3100
OTLP gRPC: localhost:4317
OTLP HTTP: localhost:4318
Rebuild the Skill Catalog
If you add, remove, or rename demo skills, rebuild both catalog files:
./scripts/build-catalog.sh
The script writes:
skills-catalog.jsonfor humans and automation.grafana/catalog.csvfor the Grafana dashboard's static catalog join.
Important Telemetry Notes
Set OTEL_LOG_TOOL_DETAILS=1. Without it, skill names and detailed tool parameters are redacted or collapsed, which makes skill-level dashboards much less useful.
Native telemetry answers whether a skill was activated. It does not prove that the skill completed its intended business logic. For example, a shell command can return exit 1 while the tool harness still reports a successful tool result. Treat skill correctness as a separate signal that requires hooks or custom instrumentation.
Depending on your Claude Code version, direct slash-command skill invocations and programmatic Skill tool invocations may produce different telemetry. Validate the invocation paths your team actually uses before treating this as a complete usage accounting system.
What Not to Commit
This public package intentionally excludes:
- Local Claude Code settings
- Internal planning documents
- Article drafts
- Experiment notes
- Captured local data volumes