docs(skills): document SKILL.md runtime field + AST coverage gate (#119 PR-4)

[HongmingWang-Rabbit]

Summary

Closes the documentation + audit gap for declarative skill-compat. The plumbing has been live since PR #117 (RuntimeCapabilities) and skill_loader._normalize_runtime_field has been emitting filter decisions for weeks, but:

• No public doc explained the runtime frontmatter field, so skill authors didn't know how to opt in / opt out.
• No structural gate ensured every load_skills() call site threads current_runtime — a future caller forgetting the kwarg silently force-loads runtime-incompatible skills (no AttributeError, just a delayed crash on first tool invocation).

This is the fourth (and final structural) slice of #119 — see #2548 (event_log module), #2551 (heartbeat + uvicorn wiring), #2552 (EventLog into adapter base).

Two changes

1. docs/agent-runtime/skills.md

• Adds runtime, tags, examples to the Frontmatter Fields table.
• Adds a Runtime Compatibility section with example, accepted shapes (universal default, list, string sugar), and the "logged + omitted, not crashed" failure mode.
• Notes that match values come from each adapter's name() method (the same string in config.yaml's runtime: field).

2. workspace/tests/test_load_skills_call_sites.py

• Static AST gate: walks every workspace/*.py (excluding tests/), finds load_skills(...) Call nodes, fails if any lacks current_runtime= as a keyword.
• Defense-in-depth test_known_call_sites_present — pins that the scan actually sees the two known callers (adapter_base.py, skill_loader/watcher.py) so a refactor that moves them is loud.
• Sanity-checked the matcher against a synthetic violating module.

Same-shape pattern as PR #2358 (tenant_resources audit-coverage AST gate, task #150) — pin the contract structurally, not just behaviorally.

Why this matters now

Hermes-style skill packages start landing in shared catalogs as soon as they're worth sharing. Without a public doc, every skill author hits the loader's silent filter decision the same way — by reading source. Without the AST gate, every refactor that moves a load_skills call site risks dropping the kwarg and reintroducing the silent force-load bug.

Test plan

• test_load_skills_call_sites.py (2 new tests) passes
• Existing 7 runtime-compat unit tests in test_skills_loader.py still pass
• AST matcher sanity-check confirmed it correctly flags load_skills('/x', ['y']) and approves load_skills('/x', ['y'], current_runtime='claude-code')
• Wheel build + boot smoke pass on this PR's CI

🤖 Generated with Claude Code