Hongming Wang
f8b40d8d73
Closes the documentation + audit gap for declarative skill-compat. The plumbing has been live since PR #117 (RuntimeCapabilities) and skill_loader's `_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). 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() (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, skill_loader.watcher) 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, #150) — pin the contract structurally, not just behaviorally. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
docs/
This directory serves two purposes:
- Markdown content — everything under
architecture/,agent-runtime/,api-protocol/,development/,frontend/,plugins/,product/, etc. This is what agents and humans read. - VitePress site —
.vitepress/config.ts,package.json,package-lock.json. These drive the rendered documentation site.
Local preview
cd docs
npm install
npm run dev # preview on http://localhost:5173
npm run build # static build to docs/.vitepress/dist/
Conventions
- New top-level docs must be linked from
PLAN.md,README.md, andCLAUDE.md— otherwise agents can't find them (see.claude/memoryfeedback_cross_reference_docs.md). edit-history/YYYY-MM-DD.mdis append-only log of significant changes; don't rewrite history.archive/holds one-shot analyses and retired docs — kept for context but not maintained.
Why site tooling lives here (not in docs-site/)
VitePress expects its config at <root>/.vitepress/config.ts where <root> is also the content directory. Splitting tooling into a sibling docs-site/ would require a non-trivial srcDir shim and break relative links in .vitepress/config.ts. Keeping both together is the pragmatic choice; this README is the tradeoff ledger.