[tobi12345]

What does this PR do?

Add local skill discovery and skill availability tracing to the Python SDK. Configure Langfuse(skills={"available": discover_skills(dir=".agents/skills")}), then use propagate_attributes(attach_skills=True) to attach the configured list or skills_available=[...] to supply it directly.

Discovery follows symlinks and reads names and versions from CLI lockfiles. Malformed or unreadable locks warn and fall back to directory names; unreadable skill entries warn and are skipped. Lockfiles with other integer versions are accepted when their structure is compatible.

Skills follow the JavaScript lifecycle: at span start, existing attributes take precedence over propagated skills, then configured defaults. Observation initialization and subsequent updates or propagation can overwrite that value, including with an empty list. Skills are not written to outgoing baggage; incoming baggage uses the normal handler.

The stable skills API is already on main via #2063; this PR has no generated API changes.

Verification

• uv run --frozen pytest -n 4 --dist worksteal tests/unit -q with CI test credentials: 1024 passed, 2 skipped.
• uv run --frozen ruff check .: All checks passed!
• uv run --frozen ruff format --check .: 578 files already formatted.
• uv run --frozen mypy langfuse --no-error-summary: exit 0.
• git diff --check: exit 0.

Server E2E and live-provider tests were skipped; in-memory unit tests cover the affected discovery, propagation and span lifecycle behavior.

Scope notes

Configured catalogs are attached to the live span. The existing project-scope guard remains for Langfuse-owned spans, but multiple processors sharing external spans do not receive isolated catalogs. Direct skill attributes are accepted on all Python observation types.

Confidence Score: 3/5

Fix explicit-skill overwrites, shared-provider catalog mix-ups, and the required import layout before merging.

Summary

Adds local skill discovery, configured skill catalogs, and skill attributes on observations.

• The SDK finds local skills and can attach their catalog to traces.
• Each observation can record the skills available to it.
• The skills API can return file text with the skill manifest.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Local skill folders and lockfile] --> B[discover_skills]
  B --> C[Configured project catalog]
  D[Direct observation skills] --> E[Span attributes]
  F[propagate_attributes] --> G[Current observation and child context]
  G --> H[Span processor]
  C --> H
  H --> E
  E --> I[Project export]

Loading

_{Reviews (1) · Last reviewed commit: "feat(skills): add discovery and availabi..." · Reviewed by Greptile}

[claude]

Nothing blocking. The comments below are optional suggestions. There is no need to push a fix for them before merging.

[tobi12345]

@claude review

[claude]

Nothing blocking. The comments below are optional suggestions. There is no need to push a fix for them before merging.

Beyond the inline finding, I also looked at whether propagate_attributes(attach_skills=True) should attach the configured catalog to the observation that is already open. It doesn't, but that matches the docstring ("spans created in this context"), and explicit skills_available still updates the current span, so I didn't count it as a bug.

Extended reasoning...

The ruled-out item is in langfuse/_client/propagation.py. There, attach_skills is stored only as a context value that the span processor reads in on_start, while skills_available is also written to the current span.

[hassiebp]

why do we need a new available_skills kwarg on all observation types?

[hassiebp]

this key should also not be propagatable via baggage