fix(client): validate skills in skill_refs, not in the config parser

[XieX]

Summary

A malformed skills field no longer fails core config calls. Today parse_ai_config rejects the whole AI Config when skills is malformed. config().invoke(), stream(), graph nodes and extract_variation then raise, and inspect_config returns config: None, even for apps that never use Agent Skills. Agent Skills is experimental, and TESTING.md §0.3 says experimental behaviour must not break a core call.

• parse_ai_config passes skills through unchecked.
• skill_refs validates the field and raises ValueError when it is present but malformed, including skills: null and a single bad entry. Before, it dropped bad entries with a warning, which was only safe because the parser had already rejected them.
• An absent field, or a config that is not a dict, still returns [].

Raising rather than dropping keeps the reason the parser checked in the first place. write_skills with the default prune=True deletes every managed skill missing from the list it is given, so skill_refs never returns an empty or partial list for a field that is present.

Stacked on #144. JS counterpart: launchdarkly/js-ai-sdk#117.

Tests

• Parser: a malformed skills field of every kind (null, non-list, bad entry, one bad entry among good ones) parses successfully and passes through unchanged.
• skill_refs: the cases the parser used to reject, including null, now raise ValueError naming the field. One bad entry rejects the whole field. The error does not echo the rejected key.
• Core calls: inspect_config and extract_variation succeed on a variation with malformed skills.

Open question

skill_refs(None) still returns [], as documented. That is the case where a failed inspect_config feeds an empty list to a pruning write_skills. The README quickstart guards against it, but raising would remove the trap for every caller. That is a contract change, so it is not in this PR.

Test plan

• make lint, make format-check, make typecheck
• uv run pytest: 2209 passed, 11 skipped

🤖 Generated with Claude Code

---

Note

Overview
Agent Skills validation moves off the core config parser so experimental skills data cannot break config().invoke(), inspect_config, or extract_variation when apps never use skills (TESTING.md §0.3).

parse_ai_config now passes skills through unchanged; _parse_skills was removed from the parse path and exposed as skills_field_rejection_reason for reference discovery only. skill_refs validates the field and raises ValueError when skills is present but malformed (including null or one bad entry in a list), instead of dropping bad entries with warnings—avoiding a shortened list that would authorize write_skills(..., prune=True) to delete on-disk skills the config still references.

Docs (README.md, agents.md, AiConfigRep docstring) and tests were updated: parser tests expect malformed skills to parse successfully; skill_refs and lifecycle tests cover the new raise behavior and that core calls succeed with invalid skills.

^{Reviewed by Cursor Bugbot for commit 0f303f4. Bugbot is set up for automated code reviews on this repo. Configure here.}