--- name: version-watch description: Use Version Watch to retrieve current developer-platform changelog intelligence, filter it to a project stack, cite official sources, and produce actionable release-risk summaries. --- # Version Watch Skill Version Watch is a public change intelligence API for official developer-platform changelogs, release notes, docs updates, RSS feeds, and GitHub releases. The API reads from Convex-backed snapshots. It is not live scrape-on-request. Always check freshness status when a user is making a release, incident, compliance, or upgrade decision. Version Watch uses adaptive freshness: a 15-minute Convex scheduler fetches due sources based on freshness tier, source health, and backoff. A vendor-filtered API request can enqueue a background refresh when that vendor is due without blocking the response. Use this skill when a user asks about recent platform changes, release risk, dependency upgrades, API or SDK changes, vendor monitoring, or agent-readable changelog context. ## Public Resources - API docs: https://versionwatch.dev/agent-access - OpenAPI contract: https://versionwatch.dev/api/v1/openapi.json - Taxonomy: https://versionwatch.dev/api/v1/taxonomy - Status: https://versionwatch.dev/api/v1/status - Vendor freshness: https://versionwatch.dev/api/v1/status/vendors - Vendors: https://versionwatch.dev/api/v1/vendors - Updates: https://versionwatch.dev/api/v1/updates - Markdown feed: https://versionwatch.dev/feed.md - Agent guide: https://versionwatch.dev/agents.md - LLM map: https://versionwatch.dev/llms.txt ## Operating Procedure 1. Identify the user's project stack, vendors, or platform areas. 2. If freshness matters, call /api/v1/status and tell the user if the feed is degraded or stale. 3. If vendor slugs or valid tags are uncertain, call /api/v1/vendors and /api/v1/taxonomy. 4. Query /api/v1/updates with the narrowest useful filters. 5. Use severity, audience, tag, since, and vendor filters before broad queries. 6. Follow next_cursor only when more matching results are needed. 7. De-duplicate by update id before reporting or notifying. 8. Use summary, why_it_matters, and recommended_action to explain the impact. 9. Cite source_url for the official vendor source. Cite version_watch_url for the Version Watch record. 10. Do not claim to have read the official source unless you opened source_url. ## Freshness Handling - healthy: use results normally, while still citing official sources. - degraded: explain that the snapshot is recent but one or more active sources may be incomplete. - stale: warn that the snapshot missed the freshness window and avoid presenting results as complete. - paused or unsupported sources do not make the global API stale, but they mean that vendor is not actively monitored until a reliable machine-readable surface exists. - /api/v1/status/vendors/{slug} gives per-vendor tier, next due time, backoff, source counts, and queued refresh state. ## Pagination and Errors - Follow next_cursor by passing it as cursor on the next request. - Treat cursor values as opaque; do not decode them or assume offset pagination. - Store delivered update ids so repeated polling does not notify twice. - Handle error.code values invalid_filter, invalid_cursor, and not_found. Show error.message to the user or log it. ## Query Patterns - Latest high-signal changes: https://versionwatch.dev/api/v1/updates?severity=high&limit=10 - Critical changes: https://versionwatch.dev/api/v1/updates?severity=critical&limit=10 - Vendor-specific changes: https://versionwatch.dev/api/v1/updates?vendor=openai&limit=10 - Stack-tag changes: https://versionwatch.dev/api/v1/updates?tag=auth&limit=10 - Recent backend changes: https://versionwatch.dev/api/v1/updates?audience=backend&since=2026-04-24T00:00:00Z&limit=10 ## Common Agent Tasks ### Release Risk Check Use this before a planned deploy or release. GET https://versionwatch.dev/api/v1/updates?severity=high&tag=api&limit=10 Report only updates that match the project stack. Include recommended_action and cite source_url. If /api/v1/status is degraded or stale, include that caveat in the risk report. ### Dependency Upgrade Review Use this before upgrading SDKs, CLIs, frameworks, or hosted platform dependencies. GET https://versionwatch.dev/api/v1/updates?tag=sdk&limit=20 GET https://versionwatch.dev/api/v1/updates?tag=breaking&limit=20 Compare vendor_slug, tags, and audience to the dependency being upgraded. Flag breaking, deprecation, API, and SDK updates first. ### Vendor Watch Digest Use this to summarize changes for a known stack. GET https://versionwatch.dev/api/v1/updates?vendor=openai&limit=5 GET https://versionwatch.dev/api/v1/updates?vendor=vercel&limit=5 GET https://versionwatch.dev/api/v1/updates?vendor=github&limit=5 Group by vendor, de-duplicate by id, and sort by published_at descending. Use next_cursor when the digest needs more than one page. ### CI Preflight Use this in release checks when the project has known vendors. GET https://versionwatch.dev/api/v1/updates?severity=critical&limit=25 GET https://versionwatch.dev/api/v1/updates?severity=high&tag=infra&limit=25 GET https://versionwatch.dev/api/v1/updates?severity=high&tag=auth&limit=25 Return a warning when a matching update affects auth, API, SDK, infra, billing, security, or deployment behavior. Fail softly when status is degraded or stale: report the matching updates but tell the user coverage may be incomplete. ### Team Notification Formatting Use this structure for Discord, Slack, Teams, email, or issue trackers. Vendor: {vendor} Title: {title} Severity: {severity} Summary: {summary} Recommended action: {recommended_action} Source: {source_url} Version Watch: {version_watch_url} Send one message per update or one grouped digest. Store delivered ids to avoid repeats. ## Output Format When summarizing updates for a user, include: - Vendor and title - Published date - Severity and signal score - Summary - Why it matters - Recommended action - Official source URL - Version Watch URL ## Guardrails - Prefer precise filters over broad feeds. - Do not notify repeatedly for the same update id. - Do not invent migration details that are not present in the update or official source. - When confidence matters, tell the user to review source_url before changing production systems.