fix(sdk): skip subagents whose skill is missing

[px12811]

HUMAN:

---

AGENT:

Why

A parsed file-based or plugin-provided agent that named a missing skill raised during lazy registration. That exception escaped the first message path as a 500 and left the conversation unusable on later messages.

Summary

• Register file-based and plugin definitions through one per-definition guard.
• Skip only invalid definitions, log the source, agent, and failure, and continue registering valid siblings.
• Document the non-fatal registration invariant and add file/plugin regression tests.
• Update the user-facing file-based agents guide in docs: document skipped agent definitions docs#923.

Issue Number

#5630

How to Test

pytest tests/sdk/subagent/test_subagent_registry.py tests/sdk/conversation/test_local_conversation_agent_plugins.py -q

Live messages and the server warning are recorded in .pr/evidence.md. Both message requests returned 200, and a create with initial_message returned 201. The later error status in that evidence is from the intentionally invalid test LLM, not the missing skill.

Documentation counterpart: OpenHands/docs#923

Type

• Bug fix

[github-actions]

📁 PR Artifacts Notice

This PR contains a .pr/ directory with temporary PR-specific documents. Because this is a fork PR, the workflow will open or update a cleanup PR against main after merge.