@mcptoolshop/claude-synergy 0.0.0 → 1.0.0

package/products.yaml

@@ -0,0 +1,456 @@
+# Claude Synergy — products configuration
+#
+# Single source of truth for product metadata + fetcher dispatch. Loaded by
+# src/products-config.ts; consumed by src/fetch.ts (TARGETS) + src/ingest.ts
+# (PRODUCT_META). If this file is missing, both modules fall back to their
+# hardcoded defaults (with a one-time warn to stderr).
+#
+# Adding a new product: append an entry here. No code change required as long
+# as the fetcher 'type' matches an existing strategy (gh-releases | rss |
+# raw-changelog | html-scrape | catalog | playwright).
+#
+# ─── Schema reference ──────────────────────────────────────────────────────
+#
+# Each entry under `products:` has these fields:
+#
+#   REQUIRED:
+#     name            string   Product slug. Used as directory name + DB key.
+#                              Must match ^[a-z0-9][a-z0-9-]*$ (lowercase
+#                              alphanumeric + hyphens, no leading hyphen).
+#     display_name    string   Human-readable name shown in CLI output.
+#     tier            integer  Source reliability tier (1-5):
+#                                1 = Structured API (GitHub Releases) — highest fidelity
+#                                2 = Raw markdown changelog (CHANGELOG.md / HISTORY.md)
+#                                3 = HTML / RSS scrape (blogs, feed URLs)
+#                                4 = Catalog snapshot (not versioned releases)
+#                                5 = Advisory / manual (X accounts, mirrors)
+#     source_url      string   Canonical URL for the data source.
+#     fetch_strategy  string   Fetcher type label. Should match fetch.type when
+#                              a fetch: block is present.
+#
+#   OPTIONAL:
+#     notes           string   Free-text notes (e.g., platform requirements).
+#     fetch           object   Fetcher configuration. Omit if the product's
+#                              corpus is seeded manually (no automated fetch).
+#
+#   fetch: sub-schema (varies by fetch.type):
+#
+#     type: gh-releases
+#       repo           string   REQUIRED. "owner/repo" (e.g., "anthropics/anthropic-sdk-python").
+#       multi_package  boolean  Optional. Set true for monorepos with scoped
+#                               tags like "@scope/pkg@1.0.0" or "sdk-v1.0.0".
+#
+#     type: rss
+#       url            string   REQUIRED. RSS 2.0 feed URL.
+#       title_filter   string   Optional. Regex (case-insensitive) to filter
+#                               entries by title (e.g., "cody|sourcegraph").
+#
+#     type: raw-changelog
+#       url            string   REQUIRED. Raw file URL (e.g., GitHub raw URL).
+#       parser         string   REQUIRED. Parser name. Currently: "aider-history".
+#
+#     type: html-scrape
+#       parser         string   REQUIRED. Parser name. One of:
+#                               "github-copilot-blog", "vscode-updates".
+#
+#     type: playwright
+#       (no additional fields — currently hardcoded to Windsurf's CSR changelog)
+#
+#     type: catalog
+#       catalog_type   string   REQUIRED. One of: "official-mcp-registry", "smithery".
+#       max_entries    integer  Optional. Cap on entries to fetch (default: all).
+
+products:
+
+  # ── Tier 2 / Anthropic CHANGELOG.md ───────────────────────────────────────
+  - name: claude-code
+    display_name: Claude Code
+    tier: 2
+    source_url: https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md
+    fetch_strategy: git-changelog
+    # No fetch: block — corpus seeded by initial study-swarm; CHANGELOG.md
+    # incremental sync deferred to a future phase.
+
+  # ── Tier 3 / HTML feeds ──────────────────────────────────────────────────
+  - name: claude-api
+    display_name: Claude API / Platform
+    tier: 3
+    source_url: https://platform.claude.com/docs/en/release-notes/overview
+    fetch_strategy: webfetch
+    # WebFetch-based; corpus seeded by initial swarm.
+
+  - name: anthropic-apps
+    display_name: Anthropic Apps (Design / Cowork / Chat / Mobile)
+    tier: 3
+    source_url: https://support.claude.com/en/articles/12138966-release-notes
+    fetch_strategy: webfetch
+
+  # ── Tier 1 / GitHub Releases — Anthropic SDKs ────────────────────────────
+  - name: claude-agent-sdk-python
+    display_name: Claude Agent SDK (Python)
+    tier: 1
+    source_url: https://github.com/anthropics/claude-agent-sdk-python
+    fetch_strategy: gh-releases
+    fetch:
+      type: gh-releases
+      repo: anthropics/claude-agent-sdk-python
+
+  - name: claude-agent-sdk-typescript
+    display_name: Claude Agent SDK (TypeScript)
+    tier: 1
+    source_url: https://github.com/anthropics/claude-agent-sdk-typescript
+    fetch_strategy: gh-releases
+    fetch:
+      type: gh-releases
+      repo: anthropics/claude-agent-sdk-typescript
+
+  - name: anthropic-cli
+    display_name: Anthropic CLI (ant)
+    tier: 1
+    source_url: https://github.com/anthropics/anthropic-cli
+    fetch_strategy: gh-releases
+    fetch:
+      type: gh-releases
+      repo: anthropics/anthropic-cli
+
+  - name: anthropic-sdk-python
+    display_name: Anthropic SDK (Python)
+    tier: 1
+    source_url: https://github.com/anthropics/anthropic-sdk-python
+    fetch_strategy: gh-releases
+    fetch:
+      type: gh-releases
+      repo: anthropics/anthropic-sdk-python
+
+  - name: anthropic-sdk-typescript
+    display_name: Anthropic SDK (TypeScript)
+    tier: 1
+    source_url: https://github.com/anthropics/anthropic-sdk-typescript
+    fetch_strategy: gh-releases
+    fetch:
+      type: gh-releases
+      repo: anthropics/anthropic-sdk-typescript
+      multi_package: true
+
+  - name: anthropic-sdk-go
+    display_name: Anthropic SDK (Go)
+    tier: 1
+    source_url: https://github.com/anthropics/anthropic-sdk-go
+    fetch_strategy: gh-releases
+    fetch:
+      type: gh-releases
+      repo: anthropics/anthropic-sdk-go
+
+  - name: anthropic-sdk-java
+    display_name: Anthropic SDK (Java)
+    tier: 1
+    source_url: https://github.com/anthropics/anthropic-sdk-java
+    fetch_strategy: gh-releases
+    fetch:
+      type: gh-releases
+      repo: anthropics/anthropic-sdk-java
+
+  - name: anthropic-sdk-ruby
+    display_name: Anthropic SDK (Ruby)
+    tier: 1
+    source_url: https://github.com/anthropics/anthropic-sdk-ruby
+    fetch_strategy: gh-releases
+    fetch:
+      type: gh-releases
+      repo: anthropics/anthropic-sdk-ruby
+
+  - name: anthropic-sdk-csharp
+    display_name: Anthropic SDK (C#)
+    tier: 1
+    source_url: https://github.com/anthropics/anthropic-sdk-csharp
+    fetch_strategy: gh-releases
+    fetch:
+      type: gh-releases
+      repo: anthropics/anthropic-sdk-csharp
+      multi_package: true
+
+  - name: anthropic-sdk-php
+    display_name: Anthropic SDK (PHP)
+    tier: 1
+    source_url: https://github.com/anthropics/anthropic-sdk-php
+    fetch_strategy: gh-releases
+    fetch:
+      type: gh-releases
+      repo: anthropics/anthropic-sdk-php
+
+  - name: claude-code-action
+    display_name: Claude Code Action (GitHub Action)
+    tier: 1
+    source_url: https://github.com/anthropics/claude-code-action
+    fetch_strategy: gh-releases
+    fetch:
+      type: gh-releases
+      repo: anthropics/claude-code-action
+
+  - name: claude-code-security-review
+    display_name: Claude Code Security Review (GitHub Action)
+    tier: 1
+    source_url: https://github.com/anthropics/claude-code-security-review
+    fetch_strategy: gh-releases
+    fetch:
+      type: gh-releases
+      repo: anthropics/claude-code-security-review
+
+  # ── Tier 4 / Catalog repos (Anthropic) ───────────────────────────────────
+  - name: skills
+    display_name: Anthropic Skills Catalog
+    tier: 4
+    source_url: https://github.com/anthropics/skills
+    fetch_strategy: git-snapshot
+
+  - name: plugins-official
+    display_name: Claude Plugins (Official)
+    tier: 4
+    source_url: https://github.com/anthropics/claude-plugins-official
+    fetch_strategy: git-snapshot
+
+  - name: plugins-community
+    display_name: Claude Plugins (Community)
+    tier: 4
+    source_url: https://github.com/anthropics/claude-plugins-community
+    fetch_strategy: git-snapshot
+
+  - name: plugins-knowledge-work
+    display_name: Knowledge Work Plugins (Cowork)
+    tier: 4
+    source_url: https://github.com/anthropics/knowledge-work-plugins
+    fetch_strategy: git-snapshot
+
+  # ── Tier 1 / MCP ecosystem SDKs ──────────────────────────────────────────
+  - name: mcp-python-sdk
+    display_name: MCP Python SDK
+    tier: 1
+    source_url: https://github.com/modelcontextprotocol/python-sdk
+    fetch_strategy: gh-releases
+    fetch:
+      type: gh-releases
+      repo: modelcontextprotocol/python-sdk
+
+  - name: mcp-typescript-sdk
+    display_name: MCP TypeScript SDK
+    tier: 1
+    source_url: https://github.com/modelcontextprotocol/typescript-sdk
+    fetch_strategy: gh-releases
+    fetch:
+      type: gh-releases
+      repo: modelcontextprotocol/typescript-sdk
+      multi_package: true
+
+  - name: mcp-go-sdk
+    display_name: MCP Go SDK
+    tier: 1
+    source_url: https://github.com/modelcontextprotocol/go-sdk
+    fetch_strategy: gh-releases
+    fetch:
+      type: gh-releases
+      repo: modelcontextprotocol/go-sdk
+
+  - name: mcp-java-sdk
+    display_name: MCP Java SDK
+    tier: 1
+    source_url: https://github.com/modelcontextprotocol/java-sdk
+    fetch_strategy: gh-releases
+    fetch:
+      type: gh-releases
+      repo: modelcontextprotocol/java-sdk
+
+  - name: mcp-csharp-sdk
+    display_name: MCP C# SDK
+    tier: 1
+    source_url: https://github.com/modelcontextprotocol/csharp-sdk
+    fetch_strategy: gh-releases
+    fetch:
+      type: gh-releases
+      repo: modelcontextprotocol/csharp-sdk
+
+  - name: mcp-kotlin-sdk
+    display_name: MCP Kotlin SDK
+    tier: 1
+    source_url: https://github.com/modelcontextprotocol/kotlin-sdk
+    fetch_strategy: gh-releases
+    fetch:
+      type: gh-releases
+      repo: modelcontextprotocol/kotlin-sdk
+
+  - name: mcp-ruby-sdk
+    display_name: MCP Ruby SDK
+    tier: 1
+    source_url: https://github.com/modelcontextprotocol/ruby-sdk
+    fetch_strategy: gh-releases
+    fetch:
+      type: gh-releases
+      repo: modelcontextprotocol/ruby-sdk
+
+  - name: mcp-swift-sdk
+    display_name: MCP Swift SDK
+    tier: 1
+    source_url: https://github.com/modelcontextprotocol/swift-sdk
+    fetch_strategy: gh-releases
+    fetch:
+      type: gh-releases
+      repo: modelcontextprotocol/swift-sdk
+
+  - name: mcp-rust-sdk
+    display_name: MCP Rust SDK
+    tier: 1
+    source_url: https://github.com/modelcontextprotocol/rust-sdk
+    fetch_strategy: gh-releases
+    fetch:
+      type: gh-releases
+      repo: modelcontextprotocol/rust-sdk
+
+  - name: mcp-php-sdk
+    display_name: MCP PHP SDK
+    tier: 1
+    source_url: https://github.com/modelcontextprotocol/php-sdk
+    fetch_strategy: gh-releases
+    fetch:
+      type: gh-releases
+      repo: modelcontextprotocol/php-sdk
+
+  - name: mcp-spec
+    display_name: MCP Specification
+    tier: 1
+    source_url: https://github.com/modelcontextprotocol/modelcontextprotocol
+    fetch_strategy: gh-releases
+    fetch:
+      type: gh-releases
+      repo: modelcontextprotocol/modelcontextprotocol
+
+  - name: mcp-inspector
+    display_name: MCP Inspector
+    tier: 1
+    source_url: https://github.com/modelcontextprotocol/inspector
+    fetch_strategy: gh-releases
+    fetch:
+      type: gh-releases
+      repo: modelcontextprotocol/inspector
+
+  - name: mcp-registry
+    display_name: MCP Registry
+    tier: 1
+    source_url: https://github.com/modelcontextprotocol/registry
+    fetch_strategy: gh-releases
+    fetch:
+      type: gh-releases
+      repo: modelcontextprotocol/registry
+
+  - name: mcp-mcpb
+    display_name: MCP Bundle (mcpb)
+    tier: 1
+    source_url: https://github.com/modelcontextprotocol/mcpb
+    fetch_strategy: gh-releases
+    fetch:
+      type: gh-releases
+      repo: modelcontextprotocol/mcpb
+
+  - name: mcp-conformance
+    display_name: MCP Conformance
+    tier: 1
+    source_url: https://github.com/modelcontextprotocol/conformance
+    fetch_strategy: gh-releases
+    fetch:
+      type: gh-releases
+      repo: modelcontextprotocol/conformance
+
+  # ── Tier 4a / Non-Anthropic AI dev tools ─────────────────────────────────
+  - name: continue-dev
+    display_name: Continue.dev
+    tier: 1
+    source_url: https://github.com/continuedev/continue
+    fetch_strategy: gh-releases
+    fetch:
+      type: gh-releases
+      repo: continuedev/continue
+      multi_package: true
+
+  - name: continue-cli
+    display_name: Continue.dev CLI
+    tier: 1
+    source_url: https://github.com/continuedev/continue-cli
+    fetch_strategy: gh-releases
+    fetch:
+      type: gh-releases
+      repo: continuedev/continue-cli
+
+  - name: cursor
+    display_name: Cursor
+    tier: 3
+    source_url: https://cursor.com/changelog/rss.xml
+    fetch_strategy: rss
+    fetch:
+      type: rss
+      url: https://cursor.com/changelog/rss.xml
+
+  - name: cody-enterprise
+    display_name: Sourcegraph Cody Enterprise
+    tier: 3
+    source_url: https://sourcegraph.com/changelog/featured.rss
+    fetch_strategy: rss
+    fetch:
+      type: rss
+      url: https://sourcegraph.com/changelog/featured.rss
+      title_filter: 'cody|sourcegraph'
+
+  - name: aider
+    display_name: Aider
+    tier: 2
+    source_url: https://raw.githubusercontent.com/Aider-AI/aider/main/HISTORY.md
+    fetch_strategy: raw-changelog
+    fetch:
+      type: raw-changelog
+      url: https://raw.githubusercontent.com/Aider-AI/aider/main/HISTORY.md
+      parser: aider-history
+
+  # ── Tier 4b / HTML-scraped (Tier 4b) ─────────────────────────────────────
+  - name: github-copilot
+    display_name: GitHub Copilot
+    tier: 3
+    source_url: https://github.blog/changelog/label/copilot/
+    fetch_strategy: html-scrape
+    fetch:
+      type: html-scrape
+      parser: github-copilot-blog
+
+  - name: vscode-copilot-chat
+    display_name: VS Code Copilot Chat (editor)
+    tier: 3
+    source_url: https://code.visualstudio.com/updates/
+    fetch_strategy: html-scrape
+    fetch:
+      type: html-scrape
+      parser: vscode-updates
+
+  - name: windsurf
+    display_name: Windsurf (Cognition)
+    tier: 3
+    source_url: https://windsurf.com/changelog
+    fetch_strategy: playwright
+    fetch:
+      type: playwright
+    notes: "Client-rendered Next.js — requires Playwright (pnpm add -D playwright && npx playwright install chromium)"
+
+  # ── Tier 4 / MCP registry catalogs ───────────────────────────────────────
+  - name: mcp-registry-official
+    display_name: Official MCP Registry
+    tier: 4
+    source_url: https://registry.modelcontextprotocol.io
+    fetch_strategy: catalog
+    fetch:
+      type: catalog
+      catalog_type: official-mcp-registry
+
+  - name: mcp-registry-smithery
+    display_name: Smithery MCP Registry
+    tier: 4
+    source_url: https://registry.smithery.ai
+    fetch_strategy: catalog
+    fetch:
+      type: catalog
+      catalog_type: smithery
+      max_entries: 200

package/schema-vec.sql

@@ -0,0 +1,43 @@
+-- Tier 2b — semantic layer (sqlite-vec + FTS5 over contextualized chunks)
+-- Run after schema.sql. Tables here are independent of Tier 2a's changes_fts,
+-- so naive FTS still works on the raw bullets while hybrid uses the contextualized layer.
+--
+-- Dimension: 768 (nomic-embed-text native; Voyage 3 truncatable via Matryoshka)
+-- One row per change. Reranking deferred.
+
+CREATE TABLE IF NOT EXISTS chunks (
+  id                INTEGER PRIMARY KEY,
+  change_id         INTEGER NOT NULL UNIQUE REFERENCES changes(id) ON DELETE CASCADE,
+  product           TEXT NOT NULL,
+  release_version   TEXT NOT NULL,
+  released_at       DATE,
+  context_prefix    TEXT NOT NULL,
+  original_text     TEXT NOT NULL,
+  contextualized    TEXT NOT NULL,
+  context_provider  TEXT NOT NULL,
+  embedding_model   TEXT NOT NULL,
+  embedded_at       DATETIME NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_chunks_product ON chunks(product, released_at);
+CREATE INDEX IF NOT EXISTS idx_chunks_change ON chunks(change_id);
+
+-- Vector storage (sqlite-vec extension required)
+CREATE VIRTUAL TABLE IF NOT EXISTS chunks_vec USING vec0(
+  embedding FLOAT[768]
+);
+
+-- FTS5 over the contextualized text (separate from changes_fts which indexes raw bullets)
+CREATE VIRTUAL TABLE IF NOT EXISTS chunks_fts USING fts5(
+  contextualized,
+  content='chunks',
+  content_rowid='id'
+);
+
+CREATE TRIGGER IF NOT EXISTS chunks_fts_insert AFTER INSERT ON chunks BEGIN
+  INSERT INTO chunks_fts(rowid, contextualized) VALUES (new.id, new.contextualized);
+END;
+
+CREATE TRIGGER IF NOT EXISTS chunks_fts_delete AFTER DELETE ON chunks BEGIN
+  INSERT INTO chunks_fts(chunks_fts, rowid, contextualized) VALUES('delete', old.id, old.contextualized);
+END;

package/schema.sql

@@ -0,0 +1,155 @@
+-- claude-synergy schema — local mirror of every Anthropic product's release notes
+-- Forward-looking design; not yet implemented. See README.md for tier roadmap.
+-- Run with: sqlite3 claude-synergy.db < schema.sql
+
+-- ============================================================================
+-- PRODUCTS
+-- ============================================================================
+-- One row per surface (Claude Code, Claude API, Claude Agent SDK Python, etc.)
+
+CREATE TABLE products (
+  name             TEXT PRIMARY KEY,            -- "claude-code" | "claude-api" | "claude-agent-sdk-python" | "anthropic-apps" | "skills" | ...
+  display_name     TEXT NOT NULL,               -- "Claude Code", "Claude API", "Claude Agent SDK (Python)"
+  source_tier      INTEGER NOT NULL,            -- 1=GH Releases, 2=GH CHANGELOG.md, 3=HTML, 4=Catalog repo, 5=Third-party
+  source_url       TEXT NOT NULL,
+  fetch_strategy   TEXT NOT NULL,               -- "gh-releases" | "git-changelog" | "webfetch" | "git-snapshot"
+  notes            TEXT
+);
+
+-- ============================================================================
+-- RELEASES (per product)
+-- ============================================================================
+
+CREATE TABLE releases (
+  product          TEXT NOT NULL REFERENCES products(name) ON DELETE CASCADE,
+  version          TEXT NOT NULL,               -- "2.1.147" | "v0.2.82" | "2026-05-19" (date when no version)
+  released_at      DATE,
+  notes_path       TEXT NOT NULL,               -- relative path under repo, e.g. "products/claude-code/releases/2.1.147.md"
+  fetched_at       DATETIME NOT NULL,
+  source_url       TEXT NOT NULL,
+  bundle_size_kb   REAL,                        -- delta vs prior, when available
+  notes_hash       TEXT,                        -- sha256 of normalized notes body for change detection
+  PRIMARY KEY (product, version)
+);
+
+CREATE INDEX idx_releases_date ON releases(released_at);
+
+-- ============================================================================
+-- CHANGES (per release)
+-- ============================================================================
+
+CREATE TABLE changes (
+  id               INTEGER PRIMARY KEY,
+  product          TEXT NOT NULL,
+  version          TEXT NOT NULL,
+  ordinal          INTEGER NOT NULL,            -- order within release (1-based)
+  kind             TEXT NOT NULL,               -- "added" | "fixed" | "renamed" | "deprecated" | "breaking" | "improved" | "removed" | "internal"
+  text             TEXT NOT NULL,               -- the original bullet, verbatim
+  FOREIGN KEY (product, version) REFERENCES releases(product, version) ON DELETE CASCADE,
+  UNIQUE (product, version, ordinal)
+);
+
+CREATE INDEX idx_changes_pv ON changes(product, version);
+CREATE INDEX idx_changes_kind ON changes(kind);
+
+-- ============================================================================
+-- ENTITIES (extracted from change text)
+-- ============================================================================
+-- One row per detected entity per change. Lets us query "when was CLAUDE_CODE_WORKFLOWS introduced?"
+
+CREATE TABLE entities (
+  id               INTEGER PRIMARY KEY,
+  change_id        INTEGER NOT NULL REFERENCES changes(id) ON DELETE CASCADE,
+  entity_type      TEXT NOT NULL,               -- "env_var" | "slash_command" | "cli_option" | "tool" | "hook_event" | "setting_key" | "config_key" | "model_id" | "beta_header" | "api_endpoint"
+  entity_value     TEXT NOT NULL                -- "CLAUDE_CODE_WORKFLOWS" | "/code-review" | "--config" | "Workflow" | "claude-opus-4-7" | "fast-mode-2026-02-01"
+);
+
+CREATE INDEX idx_entities_value ON entities(entity_type, entity_value);
+CREATE INDEX idx_entities_change ON entities(change_id);
+
+-- ============================================================================
+-- FTS5 over change text
+-- ============================================================================
+
+CREATE VIRTUAL TABLE changes_fts USING fts5(text, content='changes', content_rowid='id');
+CREATE TRIGGER changes_fts_insert AFTER INSERT ON changes BEGIN
+  INSERT INTO changes_fts(rowid, text) VALUES (new.id, new.text);
+END;
+CREATE TRIGGER changes_fts_delete AFTER DELETE ON changes BEGIN
+  INSERT INTO changes_fts(changes_fts, rowid, text) VALUES('delete', old.id, old.text);
+END;
+
+-- ============================================================================
+-- MARKERS — "what have I seen?" tracking, per product
+-- ============================================================================
+
+CREATE TABLE markers (
+  product          TEXT NOT NULL REFERENCES products(name) ON DELETE CASCADE,
+  name             TEXT NOT NULL,               -- "last_seen" | "last_synced"
+  version          TEXT,
+  updated_at       DATETIME NOT NULL,
+  PRIMARY KEY (product, name)
+);
+
+-- ============================================================================
+-- RELEVANCE — manually curated "this affects workflow X"
+-- ============================================================================
+
+CREATE TABLE relevance (
+  id               INTEGER PRIMARY KEY,
+  change_id        INTEGER NOT NULL REFERENCES changes(id) ON DELETE CASCADE,
+  tag              TEXT NOT NULL,               -- "swarm-control-plane" | "memory-gate-hook" | "windows" | "ratchet-invalidates" | "urgent"
+  note             TEXT,
+  added_at         DATETIME NOT NULL
+);
+
+CREATE INDEX idx_relevance_change ON relevance(change_id);
+CREATE INDEX idx_relevance_tag ON relevance(tag);
+
+-- ============================================================================
+-- SYNERGIES — curated cross-product workflows
+-- ============================================================================
+-- The Synergy layer is what makes this a product instead of a mirror.
+-- Source: synergies/*.md files (markdown is the source of truth; parser populates these tables)
+
+CREATE TABLE synergies (
+  id               INTEGER PRIMARY KEY,
+  name             TEXT NOT NULL UNIQUE,        -- "skill-portability" | "mcp-server-portability" | etc.
+  title            TEXT NOT NULL,
+  trigger          TEXT NOT NULL,               -- "when this workflow is the right answer"
+  status           TEXT NOT NULL,               -- "confirmed" | "speculative" | "deprecated"
+  last_validated   DATE NOT NULL,
+  notes_path       TEXT NOT NULL                -- "synergies/01-skill-portability.md"
+);
+
+CREATE TABLE synergy_products (
+  synergy_id       INTEGER NOT NULL REFERENCES synergies(id) ON DELETE CASCADE,
+  product          TEXT NOT NULL REFERENCES products(name),
+  PRIMARY KEY (synergy_id, product)
+);
+
+CREATE TABLE synergy_steps (
+  synergy_id       INTEGER NOT NULL REFERENCES synergies(id) ON DELETE CASCADE,
+  ordinal          INTEGER NOT NULL,
+  text             TEXT NOT NULL,
+  PRIMARY KEY (synergy_id, ordinal)
+);
+
+CREATE TABLE synergy_evidence (
+  id               INTEGER PRIMARY KEY,
+  synergy_id       INTEGER NOT NULL REFERENCES synergies(id) ON DELETE CASCADE,
+  source_url       TEXT NOT NULL,
+  quote            TEXT,
+  source_kind      TEXT                          -- "changelog" | "docs" | "release-notes" | "blog" | "github-readme"
+);
+
+-- Link synergies to specific changelog entries that enable them
+-- (e.g. synergy 07 cites Claude Code 2.1.147's /code-review --comment change)
+CREATE TABLE synergy_change_refs (
+  synergy_id       INTEGER NOT NULL REFERENCES synergies(id) ON DELETE CASCADE,
+  change_id        INTEGER NOT NULL REFERENCES changes(id) ON DELETE CASCADE,
+  PRIMARY KEY (synergy_id, change_id)
+);
+
+CREATE INDEX idx_synergy_products ON synergy_products(product);
+CREATE INDEX idx_synergy_change_refs_change ON synergy_change_refs(change_id);

package/synergies/01-skill-portability.md

@@ -0,0 +1,33 @@
+---
+name: skill-portability
+title: Develop skills in Claude Code, deploy via Claude API
+products: [claude-code, claude-api, claude-cowork]
+trigger: User has built a working skill in `~/.claude/skills/<name>/` and wants to use it in a production agentic workload
+status: confirmed
+last_validated: 2026-05-21
+---
+
+# Develop skills in Claude Code, deploy via Claude API
+
+**Why it works:** Skills are folders of instructions/scripts/resources with the same format across every Anthropic surface. Building locally in Code is the lowest-friction iteration path; the same folder graduates unchanged to Claude API and Cowork.
+
+**Workflow:**
+
+1. Create `~/.claude/skills/<name>/SKILL.md` with `name`, `description`, optional `tools` frontmatter
+2. Iterate in Code — edit the file, invoke via `Skill` tool or natural context match, repeat
+3. When stable, organize as a directory with SKILL.md + supporting scripts/resources
+4. **Graduate to API:** `POST /v1/skills` with the bundle (requires `skills-2025-10-02` beta header). Returns a skill ID
+5. Reference the skill ID in Messages API requests — Claude loads it on demand
+6. **(Optional) Publish in Cowork:** submit to [claude-plugins-official](https://github.com/anthropics/claude-plugins-official) or [knowledge-work-plugins](https://github.com/anthropics/knowledge-work-plugins) for team distribution
+
+**Evidence:**
+
+- [Claude API release notes 2025-10-16](https://platform.claude.com/docs/en/release-notes/overview#october-16-2025): "Skills are organized folders of instructions, scripts, and resources that Claude loads dynamically to perform specialized tasks. Anthropic-managed Skills + Custom Skills via /v1/skills"
+- [anthropics/skills](https://github.com/anthropics/skills) — official catalog (pptx, xlsx, docx, pdf)
+- The local-format-and-API-format identity is the load-bearing fact; if Anthropic ever forks them, this synergy breaks
+
+**Caveats:**
+
+- Skills require the `code execution` tool enabled in the API request
+- Cost: every API request loading a skill incurs token cost for its instructions — keep them lean
+- Cowork plugin manifests may have additional fields beyond raw Code skills; check the repo before publishing