convez.ai
Skill
astronaut27

claude-code-skills-observability

astronaut27/claude-code-skills-observability

Ver no GitHub
InicialPluginScore · de 0 a 100

Instalação

$npx convez-ai astronaut27/claude-code-skills-observability

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
14%
Último commit
há 4 meses
Versão
—
Issues abertas
0
Contribuidores
1

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.usage and claude_code.token.usage metrics.
  • Loki for claude_code.skill_activated and claude_code.tool_result events.
  • Grafana with a pre-provisioned Skill Catalog Management dashboard.
  • Seven demo Claude Code skills, including two intentionally stale skills.
  • A catalog generator that emits skills-catalog.json and grafana/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.json for humans and automation.
  • grafana/catalog.csv for 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
Ver o original no GitHub

Bom para

Relacionados