feat(claude-agent-sdk): capture gen_ai.skill.* on Skill load execute_tool span

[sipercai]

What

Capture gen_ai.skill.{name,id,description,version} on the execute_tool span of the Claude Agent SDK built-in Skill tool.

Telemetry is bound to the ToolUseBlock(name="Skill") tool span (not the subsequent UserMessage TextBlock that injects SKILL.md content).

Attribute mapping (per spec)

Source	Span attribute
ToolUseBlock.input.skill (frontmatter name fallback)	gen_ai.skill.name
claude:project:<skill-name>	gen_ai.skill.id
SKILL.md frontmatter description	gen_ai.skill.description
SKILL.md frontmatter version	gen_ai.skill.version

• cwd is captured from SystemMessage.data.cwd to locate the project-level .claude/skills/<name>/SKILL.md.
• If start info is incomplete, skill.name/skill.id fall back to UserMessage.tool_use_result.commandName before the span closes.
• All metadata reads are best-effort: failures are swallowed and never propagate to the SDK call.

Local validation

• ruff check instrumentation-loongsuite/loongsuite-instrumentation-claude-agent-sdk → all checks passed
• pytest test_span_validation.py::test_skill_tool_span_attributes → 1 passed (exactly one gen_ai.tool.name=Skill execute_tool span with all four gen_ai.skill.* attributes, skill.id = claude:project:probe-skill)
• pytest test_span_validation.py::test_skill_metadata_read_failure_does_not_break_sdk → 1 passed (best-effort: missing SKILL.md does not break the call)
• Regression (test_span_validation.py + test_with_cassettes.py + test_task_subagent_real_data.py) → 24 passed, no regressions

Draft PR; not requesting review yet.

[CLAassistant]

All committers have signed the CLA.

[ralf0131]

Summary

Captures gen_ai.skill.{name,id,description,version} on the Skill tool execute_tool span. The cwd propagation chain and best-effort fallback design are solid. Test coverage is good (happy path + failure case). However, one critical issue must be fixed before merge: the top-level import yaml will break the entire instrumentation module if PyYAML is not installed.

Findings

• [Critical] patch.py:22 — import yaml at module level without pyyaml in pyproject.toml dependencies; will crash the entire module on import if PyYAML is missing
• [Info] patch.py:98 — suggestion for lazy-import placement if that approach is chosen

Suggestions

Move import yaml inside _parse_skill_frontmatter (the only consumer) to preserve the best-effort guarantee, or add pyyaml to pyproject.toml dependencies.

Note: the PR body mentions "Draft PR; not requesting review yet" — consider converting to a GitHub Draft PR to prevent accidental merge before this is addressed.

---

Automated review by github-manager-bot

[ralf0131]

[Critical] import yaml at module level without pyyaml in pyproject.toml dependencies. If PyYAML is not installed in the user's environment, the entire patch.py will fail to import with ModuleNotFoundError, breaking the instrumentation completely — not just the skill metadata feature. This contradicts the best-effort design intent. Fix: either add pyyaml to dependencies in pyproject.toml, or move the import inside _parse_skill_frontmatter (lazy import) so only the skill parsing is affected when PyYAML is missing.

[ralf0131]

[Info] If you choose the lazy-import approach, the yaml.safe_load(frontmatter_text) call here is the only place yaml is used — adding import yaml at the top of this function's try block would keep the scope minimal and preserve the best-effort guarantee.