feat(tracing): emit ls_skill_name for skill invocations

[Paarth Ahuja (paarth-a)]

What

Emit an ls_skill_name run-metadata key for skill invocations, so skill usage is queryable in LangSmith via the run-stats endpoint. skillNameFromToolCall() (in metadata.ts) derives the skill name; trace.ts wires it onto the tool run.

Why

Today skill usage isn't aggregatable — the skill name isn't in any queryable metadata field or tag. With ls_skill_name you can run:

POST /api/v1/runs/stats
{ "session": ["<project>"], "group_by": { "attribute": "metadata", "path": "ls_skill_name" } }

for per-skill activation counts. It tags the exec_command that loads a skill — the activation — so it measures how often each skill is invoked, not the latency / tokens / cost of the skill's full downstream workflow. ls_skill_name is the shared coding-agent-v1 contract key, so once each coding-agent integration emits it, one query can span them.

How skills surface in Codex (confirmed)

Captured two fresh Codex 0.128.0 rollouts — one naming a skill explicitly (openai-docs), one where the model chose a skill implicitly (skill-creator). In both:

• No dedicated skill-invocation span, no skill/invoke_skill tool, and no list_skills_response catalog event recorded in the rollout.
• A skill invocation surfaces only as an exec_command reading the skill's definition file, e.g. cat …/skills/<name>/SKILL.md.

So the extractor keys on that read:

• Gated to exec_command read commands (cat/sed/rg/…); writes, in-place edits, redirects, and deletes never match, so authoring or removing a skill isn't counted as using it.
• Skill name = the directory holding SKILL.md, required under a skills/ path segment.
• De-duplicated per skill per turn — one activation yields exactly one tag (Codex often reads a skill's SKILL.md several ways in one turn).
• Inert for every other tool call, so it changes no existing trace. The remaining false positive — reading a SKILL.md for some non-use reason — is rare.

Changes

• plugins/tracing/src/metadata.ts — skillNameFromToolCall(): exec_command read → ls_skill_name
• plugins/tracing/src/trace.ts — wire onto the tool run + per-turn dedup
• plugins/tracing/test/fixtures/validator.json — ls_skill_name contract key (contextual, tool-scoped)
• plugins/tracing/test/metadata.test.ts — unit coverage (reads vs writes/deletes, non-exec tools, verb-in-name)
• plugins/tracing/test/skills.test.ts — end-to-end over the real rollouts
• plugins/tracing/test/sessions/2026/07/23/rollout-skill-{explicit,implicit}.jsonl — sanitized fixtures
• plugins/tracing/dist/index.mjs — regenerated bundle

Test plan

• tsc --noEmit
• vitest (metadata + skills + contract + trace suites)
• npm run build (bundle regenerated; skill code present)
• Confirmed against real Codex 0.128.0 skill-invocation rollouts (explicit + implicit)

Companion to the Claude Code plugin's skill-usage tracing.