From 55814b714ac74c17813cd3cb489a8ec4f6407033 Mon Sep 17 00:00:00 2001 From: Andrew Wessels Date: Tue, 17 Nov 2026 15:16:10 -1000 Subject: [PATCH 1/6] Require diffbot 3.4.0 and describe DQL as POST. Plugin manifests move to 1.3.0. Install lines no longer accept 3.1.x, and the DQL skill states the JSON POST contract without telling the agent to call the endpoint. Co-authored-by: Cursor --- .claude-plugin/plugin.json | 2 +- .cortex-plugin/plugin.json | 2 +- .factory-plugin/plugin.json | 2 +- .github/plugin/plugin.json | 2 +- .grok-plugin/plugin.json | 2 +- README.md | 12 +++++++----- docs/listing/anthropic/README.md | 2 +- docs/listing/anthropic/validation-proof.md | 8 +++++--- docs/listing/xai/xai-pr.md | 4 ++-- skills/diffbot-crawl/SKILL.md | 6 +++--- skills/diffbot-deals/SKILL.md | 6 +++--- skills/diffbot-dql/SKILL.md | 8 ++++---- skills/diffbot-entities/SKILL.md | 6 +++--- skills/diffbot-extract/SKILL.md | 6 +++--- skills/diffbot-news/SKILL.md | 6 +++--- skills/diffbot-organizations/SKILL.md | 6 +++--- skills/diffbot-people/SKILL.md | 6 +++--- skills/diffbot-places/SKILL.md | 6 +++--- skills/diffbot-web-search/SKILL.md | 13 +++++++------ 19 files changed, 55 insertions(+), 50 deletions(-) diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 26831c6..a360ba0 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "diffbot", - "version": "1.2.3", + "version": "1.3.0", "description": "Structured web knowledge tools for development and research. Enables querying of Diffbot’s Knowledge Graph (for organizations, people, and news articles) as well as web extraction, crawling, entity resolution, and web search.", "author": { "name": "Diffbot", diff --git a/.cortex-plugin/plugin.json b/.cortex-plugin/plugin.json index 26831c6..a360ba0 100644 --- a/.cortex-plugin/plugin.json +++ b/.cortex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "diffbot", - "version": "1.2.3", + "version": "1.3.0", "description": "Structured web knowledge tools for development and research. Enables querying of Diffbot’s Knowledge Graph (for organizations, people, and news articles) as well as web extraction, crawling, entity resolution, and web search.", "author": { "name": "Diffbot", diff --git a/.factory-plugin/plugin.json b/.factory-plugin/plugin.json index 26831c6..a360ba0 100644 --- a/.factory-plugin/plugin.json +++ b/.factory-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "diffbot", - "version": "1.2.3", + "version": "1.3.0", "description": "Structured web knowledge tools for development and research. Enables querying of Diffbot’s Knowledge Graph (for organizations, people, and news articles) as well as web extraction, crawling, entity resolution, and web search.", "author": { "name": "Diffbot", diff --git a/.github/plugin/plugin.json b/.github/plugin/plugin.json index 26831c6..a360ba0 100644 --- a/.github/plugin/plugin.json +++ b/.github/plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "diffbot", - "version": "1.2.3", + "version": "1.3.0", "description": "Structured web knowledge tools for development and research. Enables querying of Diffbot’s Knowledge Graph (for organizations, people, and news articles) as well as web extraction, crawling, entity resolution, and web search.", "author": { "name": "Diffbot", diff --git a/.grok-plugin/plugin.json b/.grok-plugin/plugin.json index 7b40a7e..dc26ba7 100644 --- a/.grok-plugin/plugin.json +++ b/.grok-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "diffbot", - "version": "1.2.3", + "version": "1.3.0", "description": "Structured web knowledge tools for development and research. Enables querying of Diffbot’s Knowledge Graph (for organizations, people, and news articles) as well as web extraction, crawling, entity resolution, and web search.", "author": { "name": "Diffbot", diff --git a/README.md b/README.md index 70de603..40e1941 100644 --- a/README.md +++ b/README.md @@ -129,7 +129,7 @@ echo "DIFFBOT_API_TOKEN=YOUR_TOKEN_HERE" > ~/.diffbot/credentials && chmod 600 ~ 3. Install the `db` CLI once, into the virtualenv every skill reads: ```bash -python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.1.1' +python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0' ``` This is a one-time user install, the same as putting `gh` or `wrangler` on your machine. @@ -141,14 +141,16 @@ python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.1 ### Upgrading the `db` CLI -If a skill reports a version below 3.1.1, `db --version` fails with `No such option +These skills require `diffbot` >= 3.4.0. If a skill reports a lower version, `db --version` fails with `No such option '--version'` (an old `diffbot-python` install), or `db` warns about the `diffbot-python` rename, upgrade in place: ```bash -~/.diffbot/venv/bin/pip install -U 'diffbot>=3.1.1' +~/.diffbot/venv/bin/pip install -U 'diffbot>=3.4.0' ``` +3.1.0 added `--version` and the rename from `diffbot-python`. 3.2.0 switched DQL to `POST https://kg.diffbot.com/kg/v3/dql` with a JSON body (the token stays the `token` query parameter; GET remains a low-level escape hatch). 3.4.0 is the cumulative release to install. 3.1.x and 3.2.x are not new enough and must be upgraded. The CLI sends that request; do not call the endpoint yourself. + The package was renamed from `diffbot-python` to [`diffbot`](https://pypi.org/project/diffbot/) at 3.0.0. If a leftover `diffbot-python` is still in the venv, remove it and reinstall — in this order, because uninstalling the shim deletes the shared module files and a plain @@ -156,7 +158,7 @@ install afterwards no-ops on the surviving dist-info: ```bash ~/.diffbot/venv/bin/pip uninstall -y diffbot-python -~/.diffbot/venv/bin/pip install --force-reinstall --no-deps 'diffbot>=3.1.1' +~/.diffbot/venv/bin/pip install --force-reinstall --no-deps 'diffbot>=3.4.0' ``` ## Skills @@ -296,7 +298,7 @@ This is structured knowledge querying — not page fetching, not generic web sea ## Requirements - **Python 3.10+** (used to create `~/.diffbot/venv`) -- **`diffbot` >= 3.1.1** (formerly `diffbot-python`), installed once by you — see [Setup](#setup) +- **`diffbot` >= 3.4.0** (formerly `diffbot-python`), installed once by you — see [Setup](#setup). 3.1.x must be upgraded. - **Diffbot API token** (free tier available) - A supported agent (see Install) diff --git a/docs/listing/anthropic/README.md b/docs/listing/anthropic/README.md index 898e773..2f1d37d 100644 --- a/docs/listing/anthropic/README.md +++ b/docs/listing/anthropic/README.md @@ -64,7 +64,7 @@ home-directory `Read` allowlist tweak). Nothing had landed on main since Saturda | *BLOCKING: `allowed-tools` beyond Read, Grep, Glob, and LS* | every skill | `Bash` and `jq` removed from all ten. Nine skills keep only a `Read` entry scoped to a scratch folder under `~/.diffbot` (itself refused later; removed in 1.2.3). `diffbot-web-search` omits the `allowed-tools` key. No `${...}` paths, no `//` or `\\` paths, no URLs. `db` and `jq` prompt the user. | | *Pre-approves broad shell access (Bash)* | 10 | Resolved by the same Bash removal. | | *An image or font file the plugin's code could run* | 2 | Audited, files left as-is. The only image or font in the tree is `.claude-plugin/icon.png`, which the report already marked Info/passed. No hooks, scripts, commands, or skill instructions load or execute an image or font as code. No `icon` field added — it is not in the schema and `claude plugin validate --strict` fails on it. | -| *Download-and-run commands* (`curl \| sh`, `uvx`/`npx` of a remote URL, `pip install` from a URL) | 3 | Left as documentation. The plugin itself does not run them: there is no hook, script, command, or `` !`…` `` line, and no bundled installer was added. The README install / upgrade / `npx skills add` sections stay. Each skill's Step 1 block still shows `python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.1.0'` for the user to run or approve, and still says the skill never installs, upgrades, or uninstalls the CLI. 1.2.1's note that installing was "documented in the README only" was incomplete — the line also lives in those Step 1 blocks, as documentation. | +| *Download-and-run commands* (`curl \| sh`, `uvx`/`npx` of a remote URL, `pip install` from a URL) | 3 | Left as documentation. The plugin itself does not run them: there is no hook, script, command, or `` !`…` `` line, and no bundled installer was added. The README install / upgrade / `npx skills add` sections stay. Each skill's Step 1 block still shows `python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0'` for the user to run or approve, and still says the skill never installs, upgrades, or uninstalls the CLI. As of 1.3.0 that floor is 3.4.0; 3.1.x must be upgraded. 1.2.1's note that installing was "documented in the README only" was incomplete — the line also lives in those Step 1 blocks, as documentation. | ## Directory review refusal after v1.2.2 diff --git a/docs/listing/anthropic/validation-proof.md b/docs/listing/anthropic/validation-proof.md index b6cffd6..ce30248 100644 --- a/docs/listing/anthropic/validation-proof.md +++ b/docs/listing/anthropic/validation-proof.md @@ -99,13 +99,15 @@ observation, not assumption: ## Dependency floor -The install line in the README pins `diffbot>=3.1.1` (at the time of this -capture, `diffbot-python>=0.2.1`; the package has since been renamed) rather than +The install line in the README pins a minimum (at the time of this +capture, `diffbot-python>=0.2.1`, later `diffbot>=3.1.0`; the package has since been renamed) rather than the bare package name. This is deliberate: `pip install ` with no constraint is a no-op when *any* version is already present, so a venv created against 0.1.0 would never upgrade. 0.1.0 sent the wrong query parameter for web-search `-n`, silently returning 10 results regardless — the version floor is what guarantees the documented flag -behaves as described. +behaves as described. As of plugin 1.3.0 the install and upgrade lines require +`diffbot>=3.4.0`. 3.1.0 added `--version` and the rename; 3.2.0 switched DQL to POST +with a JSON body (token stays the `token` query parameter); users on 3.1.x must upgrade. ## Permissions summary diff --git a/docs/listing/xai/xai-pr.md b/docs/listing/xai/xai-pr.md index 9ad945c..6de526e 100644 --- a/docs/listing/xai/xai-pr.md +++ b/docs/listing/xai/xai-pr.md @@ -33,8 +33,8 @@ Adds the **diffbot** plugin: ten skills for Diffbot's structured web knowledge A - [x] No reading/exfiltration of secrets, tokens, `.env`, or env vars. - [x] Hooks and MCP scope are least-privilege — the plugin has no hooks and no MCP servers. - Network endpoints this plugin calls (and why): - - `pypi.org` / `files.pythonhosted.org` — the user runs one documented line to create `~/.diffbot/venv` and `pip install` [`diffbot`](https://pypi.org/project/diffbot/) (>= 3.1.1, formerly `diffbot-python`), the `db` CLI every skill shells out to. The skills never install it themselves. Source: https://github.com/diffbot/diffbot-python. - - `kg.diffbot.com` — Knowledge Graph: DQL queries (`/kg/v3/dql`) and the ontology (`/kg/ontology`). + - `pypi.org` / `files.pythonhosted.org` — the user runs one documented line to create `~/.diffbot/venv` and `pip install` [`diffbot`](https://pypi.org/project/diffbot/) (>= 3.4.0, formerly `diffbot-python`; 3.1.x must be upgraded), the `db` CLI every skill shells out to. The skills never install it themselves. Source: https://github.com/diffbot/diffbot-python. + - `kg.diffbot.com` — Knowledge Graph: DQL queries (`POST /kg/v3/dql` with a JSON body; the token stays the `token` query parameter; GET is only a low-level escape hatch) and the ontology (`/kg/ontology`). The skills do not call these URLs themselves. - `api.diffbot.com` — Extract (`/v3/*`) and Crawl (`/v3/crawl`). - `llm.diffbot.com` — web search (`/api/v1/web_search`). - `nl.diffbot.com` — entity recognition and linking (`/v1/`). diff --git a/skills/diffbot-crawl/SKILL.md b/skills/diffbot-crawl/SKILL.md index 02c1e56..9adfe07 100644 --- a/skills/diffbot-crawl/SKILL.md +++ b/skills/diffbot-crawl/SKILL.md @@ -50,13 +50,13 @@ fails with `No such file or directory`, stop and show the user this line to run themselves (it is deliberately not pre-approved): ``` -python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.1.1' +python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0' ``` -If it prints a version below 3.1.1, fails with `No such option '--version'` (an old +If it prints a version below 3.4.0 (including 3.1.x and 3.2.x — upgrade them), fails with `No such option '--version'` (an old `diffbot-python` install, which predates the flag), or warns about the `diffbot-python` rename, point the user at **Upgrading the `db` CLI** in the plugin README and stop. Never run an install, -upgrade, or uninstall line yourself. +upgrade, or uninstall line yourself. 3.1.0 added `--version` and the rename; 3.2.0 switched DQL to POST; 3.4.0 is the release these skills require. Save output files under `.diffbot/tmp/` in the working directory. `db` creates that folder itself, so don't `mkdir` it first. `db`, `jq`, and `cat` are not pre-approved — Claude will ask before running them. Always tell the user where an export was saved. diff --git a/skills/diffbot-deals/SKILL.md b/skills/diffbot-deals/SKILL.md index 94ba4cb..cd339fd 100644 --- a/skills/diffbot-deals/SKILL.md +++ b/skills/diffbot-deals/SKILL.md @@ -26,13 +26,13 @@ fails with `No such file or directory`, stop and show the user this line to run themselves (it is deliberately not pre-approved): ``` -python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.1.1' +python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0' ``` -If it prints a version below 3.1.1, fails with `No such option '--version'` (an old +If it prints a version below 3.4.0 (including 3.1.x and 3.2.x — upgrade them), fails with `No such option '--version'` (an old `diffbot-python` install, which predates the flag), or warns about the `diffbot-python` rename, point the user at **Upgrading the `db` CLI** in the plugin README and stop. Never run an install, -upgrade, or uninstall line yourself. +upgrade, or uninstall line yourself. 3.1.0 added `--version` and the rename; 3.2.0 switched DQL to POST; 3.4.0 is the release these skills require. Save output files under `.diffbot/tmp/` in the working directory. `db` creates that folder itself, so don't `mkdir` it first. `db`, `jq`, and `cat` are not pre-approved — Claude will ask before running them. diff --git a/skills/diffbot-dql/SKILL.md b/skills/diffbot-dql/SKILL.md index 3bdbdab..20e8fef 100644 --- a/skills/diffbot-dql/SKILL.md +++ b/skills/diffbot-dql/SKILL.md @@ -9,7 +9,7 @@ Query the Diffbot Knowledge Graph via the DQL API. Translate the user's plain-te ## The `db dql` CLI -All work in this skill is driven by the `db` CLI from the [`diffbot`](https://github.com/diffbot/diffbot-python) library. It owns token loading, URL encoding, HTTP, ontology lookup, and parallel probing. +All work in this skill is driven by the `db` CLI from the [`diffbot`](https://github.com/diffbot/diffbot-python) library. It owns token loading, the DQL HTTP call, ontology lookup, and parallel probing. DQL is `POST https://kg.diffbot.com/kg/v3/dql` with a JSON body (`query`, `size`, and any `from`, `format`, `filter`, `exportspec`, and other fields). The token stays the `token` query parameter; any other placement is rejected. GET still works as a low-level escape hatch, and the query is not put in the URL. Always use `~/.diffbot/venv/bin/db` — do not call the endpoint yourself. **The CLI lives in a dedicated virtualenv at `~/.diffbot/venv`, which the user installs once** — the skill does not assume `db` is on `PATH` or that any other venv exists, and it never installs the library itself. Step 1 checks that the CLI is there. **Always invoke with the fixed path `~/.diffbot/venv/bin/db`** — never bare `db` and never another venv's `db`, so no `PATH` assumption is made. `db` is not pre-approved; Claude will ask before each run. Throughout this document `db` is shorthand for `~/.diffbot/venv/bin/db`; expand it to the full path in every actual bash command. @@ -46,13 +46,13 @@ fails with `No such file or directory`, stop and show the user this line to run themselves (it is deliberately not pre-approved): ``` -python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.1.1' +python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0' ``` -If it prints a version below 3.1.1, fails with `No such option '--version'` (an old +If it prints a version below 3.4.0 (including 3.1.x and 3.2.x — upgrade them), fails with `No such option '--version'` (an old `diffbot-python` install, which predates the flag), or warns about the `diffbot-python` rename, point the user at **Upgrading the `db` CLI** in the plugin README and stop. Never run an install, -upgrade, or uninstall line yourself. +upgrade, or uninstall line yourself. 3.1.0 added `--version` and the rename; 3.2.0 switched DQL to POST; 3.4.0 is the release these skills require. Save output files under `.diffbot/tmp/` in the working directory. `db` creates that folder itself, so don't `mkdir` it first. `db`, `jq`, and `cat` are not pre-approved — Claude will ask before running them. diff --git a/skills/diffbot-entities/SKILL.md b/skills/diffbot-entities/SKILL.md index aba7368..ccf0c37 100644 --- a/skills/diffbot-entities/SKILL.md +++ b/skills/diffbot-entities/SKILL.md @@ -37,13 +37,13 @@ fails with `No such file or directory`, stop and show the user this line to run themselves (it is deliberately not pre-approved): ``` -python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.1.1' +python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0' ``` -If it prints a version below 3.1.1, fails with `No such option '--version'` (an old +If it prints a version below 3.4.0 (including 3.1.x and 3.2.x — upgrade them), fails with `No such option '--version'` (an old `diffbot-python` install, which predates the flag), or warns about the `diffbot-python` rename, point the user at **Upgrading the `db` CLI** in the plugin README and stop. Never run an install, -upgrade, or uninstall line yourself. +upgrade, or uninstall line yourself. 3.1.0 added `--version` and the rename; 3.2.0 switched DQL to POST; 3.4.0 is the release these skills require. Save output files under `.diffbot/tmp/` in the working directory. `db` creates that folder itself, so don't `mkdir` it first. `db`, `jq`, and `cat` are not pre-approved — Claude will ask before running them. Always tell the user where an export was saved. diff --git a/skills/diffbot-extract/SKILL.md b/skills/diffbot-extract/SKILL.md index 3816c1d..f027524 100644 --- a/skills/diffbot-extract/SKILL.md +++ b/skills/diffbot-extract/SKILL.md @@ -61,13 +61,13 @@ fails with `No such file or directory`, stop and show the user this line to run themselves (it is deliberately not pre-approved): ``` -python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.1.1' +python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0' ``` -If it prints a version below 3.1.1, fails with `No such option '--version'` (an old +If it prints a version below 3.4.0 (including 3.1.x and 3.2.x — upgrade them), fails with `No such option '--version'` (an old `diffbot-python` install, which predates the flag), or warns about the `diffbot-python` rename, point the user at **Upgrading the `db` CLI** in the plugin README and stop. Never run an install, -upgrade, or uninstall line yourself. +upgrade, or uninstall line yourself. 3.1.0 added `--version` and the rename; 3.2.0 switched DQL to POST; 3.4.0 is the release these skills require. Save output files under `.diffbot/tmp/` in the working directory. `db` creates that folder itself, so don't `mkdir` it first. `db`, `jq`, and `cat` are not pre-approved — Claude will ask before running them. Always tell the user where an export was saved. diff --git a/skills/diffbot-news/SKILL.md b/skills/diffbot-news/SKILL.md index 3f3b14b..12b9527 100644 --- a/skills/diffbot-news/SKILL.md +++ b/skills/diffbot-news/SKILL.md @@ -26,13 +26,13 @@ fails with `No such file or directory`, stop and show the user this line to run themselves (it is deliberately not pre-approved): ``` -python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.1.1' +python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0' ``` -If it prints a version below 3.1.1, fails with `No such option '--version'` (an old +If it prints a version below 3.4.0 (including 3.1.x and 3.2.x — upgrade them), fails with `No such option '--version'` (an old `diffbot-python` install, which predates the flag), or warns about the `diffbot-python` rename, point the user at **Upgrading the `db` CLI** in the plugin README and stop. Never run an install, -upgrade, or uninstall line yourself. +upgrade, or uninstall line yourself. 3.1.0 added `--version` and the rename; 3.2.0 switched DQL to POST; 3.4.0 is the release these skills require. Save output files under `.diffbot/tmp/` in the working directory. `db` creates that folder itself, so don't `mkdir` it first. `db`, `jq`, and `cat` are not pre-approved — Claude will ask before running them. diff --git a/skills/diffbot-organizations/SKILL.md b/skills/diffbot-organizations/SKILL.md index 884a087..e71dbf5 100644 --- a/skills/diffbot-organizations/SKILL.md +++ b/skills/diffbot-organizations/SKILL.md @@ -26,13 +26,13 @@ fails with `No such file or directory`, stop and show the user this line to run themselves (it is deliberately not pre-approved): ``` -python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.1.1' +python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0' ``` -If it prints a version below 3.1.1, fails with `No such option '--version'` (an old +If it prints a version below 3.4.0 (including 3.1.x and 3.2.x — upgrade them), fails with `No such option '--version'` (an old `diffbot-python` install, which predates the flag), or warns about the `diffbot-python` rename, point the user at **Upgrading the `db` CLI** in the plugin README and stop. Never run an install, -upgrade, or uninstall line yourself. +upgrade, or uninstall line yourself. 3.1.0 added `--version` and the rename; 3.2.0 switched DQL to POST; 3.4.0 is the release these skills require. Save output files under `.diffbot/tmp/` in the working directory. `db` creates that folder itself, so don't `mkdir` it first. `db`, `jq`, and `cat` are not pre-approved — Claude will ask before running them. diff --git a/skills/diffbot-people/SKILL.md b/skills/diffbot-people/SKILL.md index 6078cff..2f8cf06 100644 --- a/skills/diffbot-people/SKILL.md +++ b/skills/diffbot-people/SKILL.md @@ -33,13 +33,13 @@ fails with `No such file or directory`, stop and show the user this line to run themselves (it is deliberately not pre-approved): ``` -python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.1.1' +python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0' ``` -If it prints a version below 3.1.1, fails with `No such option '--version'` (an old +If it prints a version below 3.4.0 (including 3.1.x and 3.2.x — upgrade them), fails with `No such option '--version'` (an old `diffbot-python` install, which predates the flag), or warns about the `diffbot-python` rename, point the user at **Upgrading the `db` CLI** in the plugin README and stop. Never run an install, -upgrade, or uninstall line yourself. +upgrade, or uninstall line yourself. 3.1.0 added `--version` and the rename; 3.2.0 switched DQL to POST; 3.4.0 is the release these skills require. Save output files under `.diffbot/tmp/` in the working directory. `db` creates that folder itself, so don't `mkdir` it first. `db`, `jq`, and `cat` are not pre-approved — Claude will ask before running them. diff --git a/skills/diffbot-places/SKILL.md b/skills/diffbot-places/SKILL.md index f0f0e79..82570f9 100644 --- a/skills/diffbot-places/SKILL.md +++ b/skills/diffbot-places/SKILL.md @@ -26,13 +26,13 @@ fails with `No such file or directory`, stop and show the user this line to run themselves (it is deliberately not pre-approved): ``` -python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.1.1' +python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0' ``` -If it prints a version below 3.1.1, fails with `No such option '--version'` (an old +If it prints a version below 3.4.0 (including 3.1.x and 3.2.x — upgrade them), fails with `No such option '--version'` (an old `diffbot-python` install, which predates the flag), or warns about the `diffbot-python` rename, point the user at **Upgrading the `db` CLI** in the plugin README and stop. Never run an install, -upgrade, or uninstall line yourself. +upgrade, or uninstall line yourself. 3.1.0 added `--version` and the rename; 3.2.0 switched DQL to POST; 3.4.0 is the release these skills require. Save output files under `.diffbot/tmp/` in the working directory. `db` creates that folder itself, so don't `mkdir` it first. `db`, `jq`, and `cat` are not pre-approved — Claude will ask before running them. diff --git a/skills/diffbot-web-search/SKILL.md b/skills/diffbot-web-search/SKILL.md index 7be5be9..0d33664 100644 --- a/skills/diffbot-web-search/SKILL.md +++ b/skills/diffbot-web-search/SKILL.md @@ -100,11 +100,12 @@ the index does not have, or for a page whose current state matters. | `-m`, `--max-tokens` | none | Caps total response tokens — trims from the bottom of the ranking | | `-f`, `--format` | `list` | Output format: `list` (rich terminal), `json` (raw API), `text` (plain/agent-friendly) | -**Requires `diffbot` >= 3.1.1** (`-s` was added in 3.1.0; the package was formerly +**Requires `diffbot` >= 3.4.0** (`-s` was added in 3.1.0; the package was formerly `diffbot-python`, whose final release 0.3.0 lacks it). The Step 1 check reports the installed version. If `-s` is rejected as an unknown option, or `db` prints a -`FutureWarning` about the rename, the venv is older than 3.1.0 — point the user at -**Upgrading the `db` CLI** in the plugin README and stop. Don't upgrade it yourself. +`FutureWarning` about the rename, the venv is older than 3.1.0. Any install below +3.4.0, including 3.1.x, has to be upgraded — point the user at **Upgrading the `db` +CLI** in the plugin README and stop. Don't upgrade it yourself. `-m` is the other way to shrink a response, and it degrades sharply: measured on one query, 5000 → 10 results, 2000 → 5, 1000 → 1, and **200 → zero**. Below roughly 1000 @@ -126,13 +127,13 @@ fails with `No such file or directory`, stop and show the user this line to run themselves (it is deliberately not pre-approved): ``` -python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.1.1' +python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0' ``` -If it prints a version below 3.1.1, fails with `No such option '--version'` (an old +If it prints a version below 3.4.0 (including 3.1.x and 3.2.x — upgrade them), fails with `No such option '--version'` (an old `diffbot-python` install, which predates the flag), or warns about the `diffbot-python` rename, point the user at **Upgrading the `db` CLI** in the plugin README and stop. Never run an install, -upgrade, or uninstall line yourself. +upgrade, or uninstall line yourself. 3.1.0 added `--version` and the rename; 3.2.0 switched DQL to POST; 3.4.0 is the release these skills require. The token is read from `DIFFBOT_API_TOKEN` env var or `~/.diffbot/credentials`. If missing: From a3f63cd17cc9f950d21257f84ee241553dd42e2a Mon Sep 17 00:00:00 2001 From: Andrew Wessels Date: Tue, 17 Nov 2026 17:59:07 -1000 Subject: [PATCH 2/6] Document 1.3.0 and add a tag-triggered GitHub Release. Install pins now name v1.3.0. The workflow only creates the GitHub Release; there is no npm or PyPI publish. --- .github/workflows/release.yml | 64 +++++++++++++++++++++++++++++++++++ CHANGELOG.md | 11 ++++++ README.md | 8 ++--- 3 files changed, 79 insertions(+), 4 deletions(-) create mode 100644 .github/workflows/release.yml create mode 100644 CHANGELOG.md diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..3fb3d85 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,64 @@ +name: Release + +# diffbot-skills is not an npm or PyPI package. Pushing a version tag creates +# the GitHub Release for that tag. There is no registry token and no GitHub +# environment. github.token is the workflow's built-in token, not a stored secret. +on: + push: + tags: ["v*"] + workflow_dispatch: + +permissions: + contents: read + +# Never cancel an in-flight release. A re-push of the same tag queues. +concurrency: + group: release-${{ github.ref }} + cancel-in-progress: false + +jobs: + release: + name: GitHub Release + if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v') + runs-on: ubuntu-latest + timeout-minutes: 10 + permissions: + contents: write + steps: + - uses: actions/checkout@v4 + + - name: Check tag matches plugin versions + run: | + set -euo pipefail + tag="${GITHUB_REF_NAME#v}" + for f in \ + .claude-plugin/plugin.json \ + .cortex-plugin/plugin.json \ + .factory-plugin/plugin.json \ + .grok-plugin/plugin.json \ + .github/plugin/plugin.json + do + version=$(node -p "require('./${f}').version") + if [ "$version" != "$tag" ]; then + echo "::error::${f} version ${version} does not match tag v${tag}." + exit 1 + fi + echo "${f} ${version}" + done + + - name: Publish GitHub Release + env: + GH_TOKEN: ${{ github.token }} + run: | + set -euo pipefail + repo="${GITHUB_REPOSITORY}" + tag="${GITHUB_REF_NAME}" + if gh release view "$tag" --repo "$repo" >/dev/null 2>&1; then + echo "Release $tag already exists; leaving it." + else + gh release create "$tag" \ + --repo "$repo" \ + --title "$tag" \ + --generate-notes \ + --verify-tag + fi diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..423a272 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,11 @@ +# Changelog + +## 1.3.0 - 2026-11-17 + +### Changed + +- Install lines require `diffbot>=3.4.0`. 3.1.x and 3.2.x are not new enough. +- The DQL skill states `POST https://kg.diffbot.com/kg/v3/dql` with a JSON body. The token stays the `token` query parameter. GET is the low-level escape hatch. Agents keep using `~/.diffbot/venv/bin/db`. +- Plugin manifests are 1.3.0. Tag this release `v1.3.0`. + +There is no npm or PyPI package. The tag-triggered workflow creates the GitHub Release only. Marketplace SHA bumps (xAI and others) stay a separate step. diff --git a/README.md b/README.md index 40e1941..b9ba4da 100644 --- a/README.md +++ b/README.md @@ -27,8 +27,8 @@ npx skills add diffbot/diffbot-skills -g --all npx skills add diffbot/diffbot-skills -g -a claude-code -a cursor -a pi -y # Pin a release tag (git ref via URL or #fragment — @name selects a skill, not a tag) -npx skills add https://github.com/diffbot/diffbot-skills/tree/v1.2.3 -npx skills add diffbot/diffbot-skills#v1.2.3 +npx skills add https://github.com/diffbot/diffbot-skills/tree/v1.3.0 +npx skills add diffbot/diffbot-skills#v1.3.0 ``` Supported agents include Claude Code, Cursor, GitHub Copilot, Codex, Pi, Factory (Droid), Snowflake Cortex Code, ForgeCode, Gemini CLI, OpenCode, and [many more](https://github.com/vercel-labs/skills#supported-agents). Discover packages at [skills.sh](https://skills.sh). @@ -72,12 +72,12 @@ cortex plugin install diffbot/diffbot-skills Pin the release tag: ```bash -cortex plugin install github:diffbot/diffbot-skills@v1.2.3 +cortex plugin install github:diffbot/diffbot-skills@v1.3.0 ``` #### Cortex Code Desktop -Agent Settings → Plugins → Add from GitHub → `diffbot/diffbot-skills` (append `#v1.2.3` to pin the tag). +Agent Settings → Plugins → Add from GitHub → `diffbot/diffbot-skills` (append `#v1.3.0` to pin the tag). ### Factory.ai (Droid) From cbabd938831869cff505700c81244ab768478aa9 Mon Sep 17 00:00:00 2001 From: Andrew Wessels Date: Tue, 17 Nov 2026 18:28:08 -1000 Subject: [PATCH 3/6] Note that 1.3.0 keeps the 1.2.3 tool and export behavior. The branch is rebased onto main's 1.2.3 release, so allowed-tools stays gone and exports stay in the working directory. Co-authored-by: Cursor --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 423a272..deb5ba7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,7 @@ ### Changed +- Built on 1.2.3. Skills still omit `allowed-tools`, and exports stay in `.diffbot/tmp/` in the working directory. - Install lines require `diffbot>=3.4.0`. 3.1.x and 3.2.x are not new enough. - The DQL skill states `POST https://kg.diffbot.com/kg/v3/dql` with a JSON body. The token stays the `token` query parameter. GET is the low-level escape hatch. Agents keep using `~/.diffbot/venv/bin/db`. - Plugin manifests are 1.3.0. Tag this release `v1.3.0`. From 66dd807fdbabb825f1e8fd2cbe39e7696a83c507 Mon Sep 17 00:00:00 2001 From: Andrew Wessels Date: Tue, 17 Nov 2026 18:38:26 -1000 Subject: [PATCH 4/6] Point the diffbot CLI install lines at 3.4.0rc0 for CI verification. --- CHANGELOG.md | 2 +- README.md | 8 ++++---- docs/listing/anthropic/README.md | 2 +- docs/listing/anthropic/validation-proof.md | 2 +- skills/diffbot-crawl/SKILL.md | 2 +- skills/diffbot-deals/SKILL.md | 2 +- skills/diffbot-dql/SKILL.md | 2 +- skills/diffbot-entities/SKILL.md | 2 +- skills/diffbot-extract/SKILL.md | 2 +- skills/diffbot-news/SKILL.md | 2 +- skills/diffbot-organizations/SKILL.md | 2 +- skills/diffbot-people/SKILL.md | 2 +- skills/diffbot-places/SKILL.md | 2 +- skills/diffbot-web-search/SKILL.md | 2 +- 14 files changed, 17 insertions(+), 17 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index deb5ba7..40f4be2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,7 +5,7 @@ ### Changed - Built on 1.2.3. Skills still omit `allowed-tools`, and exports stay in `.diffbot/tmp/` in the working directory. -- Install lines require `diffbot>=3.4.0`. 3.1.x and 3.2.x are not new enough. +- Install lines require `diffbot>=3.4.0rc0,<4`. 3.1.x and 3.2.x are not new enough. - The DQL skill states `POST https://kg.diffbot.com/kg/v3/dql` with a JSON body. The token stays the `token` query parameter. GET is the low-level escape hatch. Agents keep using `~/.diffbot/venv/bin/db`. - Plugin manifests are 1.3.0. Tag this release `v1.3.0`. diff --git a/README.md b/README.md index b9ba4da..8f413f9 100644 --- a/README.md +++ b/README.md @@ -129,7 +129,7 @@ echo "DIFFBOT_API_TOKEN=YOUR_TOKEN_HERE" > ~/.diffbot/credentials && chmod 600 ~ 3. Install the `db` CLI once, into the virtualenv every skill reads: ```bash -python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0' +python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0rc0,<4' ``` This is a one-time user install, the same as putting `gh` or `wrangler` on your machine. @@ -141,12 +141,12 @@ python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4 ### Upgrading the `db` CLI -These skills require `diffbot` >= 3.4.0. If a skill reports a lower version, `db --version` fails with `No such option +These skills require `diffbot>=3.4.0rc0,<4` (the 3.4.0 release candidate) for this verification branch. The unison publish will raise the floor to `diffbot>=3.4.0`. If a skill reports a lower version, `db --version` fails with `No such option '--version'` (an old `diffbot-python` install), or `db` warns about the `diffbot-python` rename, upgrade in place: ```bash -~/.diffbot/venv/bin/pip install -U 'diffbot>=3.4.0' +~/.diffbot/venv/bin/pip install -U 'diffbot>=3.4.0rc0,<4' ``` 3.1.0 added `--version` and the rename from `diffbot-python`. 3.2.0 switched DQL to `POST https://kg.diffbot.com/kg/v3/dql` with a JSON body (the token stays the `token` query parameter; GET remains a low-level escape hatch). 3.4.0 is the cumulative release to install. 3.1.x and 3.2.x are not new enough and must be upgraded. The CLI sends that request; do not call the endpoint yourself. @@ -158,7 +158,7 @@ install afterwards no-ops on the surviving dist-info: ```bash ~/.diffbot/venv/bin/pip uninstall -y diffbot-python -~/.diffbot/venv/bin/pip install --force-reinstall --no-deps 'diffbot>=3.4.0' +~/.diffbot/venv/bin/pip install --force-reinstall --no-deps 'diffbot>=3.4.0rc0,<4' ``` ## Skills diff --git a/docs/listing/anthropic/README.md b/docs/listing/anthropic/README.md index 2f1d37d..350a0e9 100644 --- a/docs/listing/anthropic/README.md +++ b/docs/listing/anthropic/README.md @@ -64,7 +64,7 @@ home-directory `Read` allowlist tweak). Nothing had landed on main since Saturda | *BLOCKING: `allowed-tools` beyond Read, Grep, Glob, and LS* | every skill | `Bash` and `jq` removed from all ten. Nine skills keep only a `Read` entry scoped to a scratch folder under `~/.diffbot` (itself refused later; removed in 1.2.3). `diffbot-web-search` omits the `allowed-tools` key. No `${...}` paths, no `//` or `\\` paths, no URLs. `db` and `jq` prompt the user. | | *Pre-approves broad shell access (Bash)* | 10 | Resolved by the same Bash removal. | | *An image or font file the plugin's code could run* | 2 | Audited, files left as-is. The only image or font in the tree is `.claude-plugin/icon.png`, which the report already marked Info/passed. No hooks, scripts, commands, or skill instructions load or execute an image or font as code. No `icon` field added — it is not in the schema and `claude plugin validate --strict` fails on it. | -| *Download-and-run commands* (`curl \| sh`, `uvx`/`npx` of a remote URL, `pip install` from a URL) | 3 | Left as documentation. The plugin itself does not run them: there is no hook, script, command, or `` !`…` `` line, and no bundled installer was added. The README install / upgrade / `npx skills add` sections stay. Each skill's Step 1 block still shows `python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0'` for the user to run or approve, and still says the skill never installs, upgrades, or uninstalls the CLI. As of 1.3.0 that floor is 3.4.0; 3.1.x must be upgraded. 1.2.1's note that installing was "documented in the README only" was incomplete — the line also lives in those Step 1 blocks, as documentation. | +| *Download-and-run commands* (`curl \| sh`, `uvx`/`npx` of a remote URL, `pip install` from a URL) | 3 | Left as documentation. The plugin itself does not run them: there is no hook, script, command, or `` !`…` `` line, and no bundled installer was added. The README install / upgrade / `npx skills add` sections stay. Each skill's Step 1 block still shows `python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0rc0,<4'` for the user to run or approve, and still says the skill never installs, upgrades, or uninstalls the CLI. As of 1.3.0 that floor is 3.4.0; 3.1.x must be upgraded. 1.2.1's note that installing was "documented in the README only" was incomplete — the line also lives in those Step 1 blocks, as documentation. | ## Directory review refusal after v1.2.2 diff --git a/docs/listing/anthropic/validation-proof.md b/docs/listing/anthropic/validation-proof.md index ce30248..2bd0540 100644 --- a/docs/listing/anthropic/validation-proof.md +++ b/docs/listing/anthropic/validation-proof.md @@ -106,7 +106,7 @@ when *any* version is already present, so a venv created against 0.1.0 would nev upgrade. 0.1.0 sent the wrong query parameter for web-search `-n`, silently returning 10 results regardless — the version floor is what guarantees the documented flag behaves as described. As of plugin 1.3.0 the install and upgrade lines require -`diffbot>=3.4.0`. 3.1.0 added `--version` and the rename; 3.2.0 switched DQL to POST +`diffbot>=3.4.0rc0,<4`. 3.1.0 added `--version` and the rename; 3.2.0 switched DQL to POST with a JSON body (token stays the `token` query parameter); users on 3.1.x must upgrade. ## Permissions summary diff --git a/skills/diffbot-crawl/SKILL.md b/skills/diffbot-crawl/SKILL.md index 9adfe07..424b5e1 100644 --- a/skills/diffbot-crawl/SKILL.md +++ b/skills/diffbot-crawl/SKILL.md @@ -50,7 +50,7 @@ fails with `No such file or directory`, stop and show the user this line to run themselves (it is deliberately not pre-approved): ``` -python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0' +python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0rc0,<4' ``` If it prints a version below 3.4.0 (including 3.1.x and 3.2.x — upgrade them), fails with `No such option '--version'` (an old diff --git a/skills/diffbot-deals/SKILL.md b/skills/diffbot-deals/SKILL.md index cd339fd..7a981e9 100644 --- a/skills/diffbot-deals/SKILL.md +++ b/skills/diffbot-deals/SKILL.md @@ -26,7 +26,7 @@ fails with `No such file or directory`, stop and show the user this line to run themselves (it is deliberately not pre-approved): ``` -python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0' +python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0rc0,<4' ``` If it prints a version below 3.4.0 (including 3.1.x and 3.2.x — upgrade them), fails with `No such option '--version'` (an old diff --git a/skills/diffbot-dql/SKILL.md b/skills/diffbot-dql/SKILL.md index 20e8fef..019d52b 100644 --- a/skills/diffbot-dql/SKILL.md +++ b/skills/diffbot-dql/SKILL.md @@ -46,7 +46,7 @@ fails with `No such file or directory`, stop and show the user this line to run themselves (it is deliberately not pre-approved): ``` -python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0' +python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0rc0,<4' ``` If it prints a version below 3.4.0 (including 3.1.x and 3.2.x — upgrade them), fails with `No such option '--version'` (an old diff --git a/skills/diffbot-entities/SKILL.md b/skills/diffbot-entities/SKILL.md index ccf0c37..eb294b0 100644 --- a/skills/diffbot-entities/SKILL.md +++ b/skills/diffbot-entities/SKILL.md @@ -37,7 +37,7 @@ fails with `No such file or directory`, stop and show the user this line to run themselves (it is deliberately not pre-approved): ``` -python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0' +python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0rc0,<4' ``` If it prints a version below 3.4.0 (including 3.1.x and 3.2.x — upgrade them), fails with `No such option '--version'` (an old diff --git a/skills/diffbot-extract/SKILL.md b/skills/diffbot-extract/SKILL.md index f027524..1fbb6c8 100644 --- a/skills/diffbot-extract/SKILL.md +++ b/skills/diffbot-extract/SKILL.md @@ -61,7 +61,7 @@ fails with `No such file or directory`, stop and show the user this line to run themselves (it is deliberately not pre-approved): ``` -python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0' +python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0rc0,<4' ``` If it prints a version below 3.4.0 (including 3.1.x and 3.2.x — upgrade them), fails with `No such option '--version'` (an old diff --git a/skills/diffbot-news/SKILL.md b/skills/diffbot-news/SKILL.md index 12b9527..d3d24c8 100644 --- a/skills/diffbot-news/SKILL.md +++ b/skills/diffbot-news/SKILL.md @@ -26,7 +26,7 @@ fails with `No such file or directory`, stop and show the user this line to run themselves (it is deliberately not pre-approved): ``` -python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0' +python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0rc0,<4' ``` If it prints a version below 3.4.0 (including 3.1.x and 3.2.x — upgrade them), fails with `No such option '--version'` (an old diff --git a/skills/diffbot-organizations/SKILL.md b/skills/diffbot-organizations/SKILL.md index e71dbf5..545bfe8 100644 --- a/skills/diffbot-organizations/SKILL.md +++ b/skills/diffbot-organizations/SKILL.md @@ -26,7 +26,7 @@ fails with `No such file or directory`, stop and show the user this line to run themselves (it is deliberately not pre-approved): ``` -python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0' +python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0rc0,<4' ``` If it prints a version below 3.4.0 (including 3.1.x and 3.2.x — upgrade them), fails with `No such option '--version'` (an old diff --git a/skills/diffbot-people/SKILL.md b/skills/diffbot-people/SKILL.md index 2f8cf06..a614e46 100644 --- a/skills/diffbot-people/SKILL.md +++ b/skills/diffbot-people/SKILL.md @@ -33,7 +33,7 @@ fails with `No such file or directory`, stop and show the user this line to run themselves (it is deliberately not pre-approved): ``` -python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0' +python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0rc0,<4' ``` If it prints a version below 3.4.0 (including 3.1.x and 3.2.x — upgrade them), fails with `No such option '--version'` (an old diff --git a/skills/diffbot-places/SKILL.md b/skills/diffbot-places/SKILL.md index 82570f9..e6df9c2 100644 --- a/skills/diffbot-places/SKILL.md +++ b/skills/diffbot-places/SKILL.md @@ -26,7 +26,7 @@ fails with `No such file or directory`, stop and show the user this line to run themselves (it is deliberately not pre-approved): ``` -python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0' +python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0rc0,<4' ``` If it prints a version below 3.4.0 (including 3.1.x and 3.2.x — upgrade them), fails with `No such option '--version'` (an old diff --git a/skills/diffbot-web-search/SKILL.md b/skills/diffbot-web-search/SKILL.md index 0d33664..7741773 100644 --- a/skills/diffbot-web-search/SKILL.md +++ b/skills/diffbot-web-search/SKILL.md @@ -127,7 +127,7 @@ fails with `No such file or directory`, stop and show the user this line to run themselves (it is deliberately not pre-approved): ``` -python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0' +python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0rc0,<4' ``` If it prints a version below 3.4.0 (including 3.1.x and 3.2.x — upgrade them), fails with `No such option '--version'` (an old From aa76d59227ea097ca7c1a175ea050e1e283d6df9 Mon Sep 17 00:00:00 2001 From: Andrew Wessels Date: Tue, 17 Nov 2026 18:49:19 -1000 Subject: [PATCH 5/6] Add CI: manifests, SKILL.md frontmatter, claude plugin validate --strict, and documented diffbot install line --- .github/workflows/ci.yml | 135 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 135 insertions(+) create mode 100644 .github/workflows/ci.yml diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..9623ddd --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,135 @@ +name: CI + +# Checks for the plugin itself. The repo ships no scripts (directory policy), +# so every check lives inline here. No secrets are used: nothing calls the +# Diffbot API. +on: + pull_request: + push: + branches: [main] + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: ci-${{ github.ref }} + cancel-in-progress: true + +jobs: + manifests: + name: Manifests and skills + runs-on: ubuntu-latest + timeout-minutes: 10 + steps: + - uses: actions/checkout@v4 + + - name: Plugin manifests parse and agree on one version + run: | + set -euo pipefail + for f in .claude-plugin/marketplace.json .claude-plugin/plugin.json \ + .cortex-plugin/plugin.json .factory-plugin/plugin.json \ + .grok-plugin/plugin.json .github/plugin/plugin.json \ + docs/listing/*/marketplace-entry.json; do + jq empty "$f" || { echo "::error file=$f::invalid JSON"; exit 1; } + done + want=$(jq -r .version .claude-plugin/plugin.json) + echo "plugin version ${want}" + for f in .cortex-plugin/plugin.json .factory-plugin/plugin.json \ + .grok-plugin/plugin.json .github/plugin/plugin.json; do + got=$(jq -r .version "$f") + if [ "$got" != "$want" ]; then + echo "::error file=$f::version ${got} does not match .claude-plugin/plugin.json ${want}" + exit 1 + fi + done + if [ -f CHANGELOG.md ] && ! grep -Eq "^## \[?${want//./\\.}\]?" CHANGELOG.md; then + echo "::error file=CHANGELOG.md::no section for ${want}" + exit 1 + fi + + - name: SKILL.md frontmatter + run: | + set -euo pipefail + fail=0 + for f in skills/*/SKILL.md; do + dir=$(basename "$(dirname "$f")") + fm=$(awk 'NR==1 && $0!="---"{exit 1} NR>1 && $0=="---"{exit} NR>1{print}' "$f") || { + echo "::error file=$f::missing YAML frontmatter"; fail=1; continue; } + name=$(printf '%s\n' "$fm" | sed -n 's/^name:[[:space:]]*//p' | tr -d '"'"'") + desc=$(printf '%s\n' "$fm" | sed -n 's/^description:[[:space:]]*//p') + if [ "$name" != "$dir" ]; then + echo "::error file=$f::name '${name}' does not match directory '${dir}'"; fail=1 + fi + if [ -z "$desc" ]; then + echo "::error file=$f::empty description"; fail=1 + fi + # Since 1.2.3 nothing is pre-approved (Anthropic directory policy). + if printf '%s\n' "$fm" | grep -q '^allowed-tools:'; then + echo "::error file=$f::allowed-tools is not allowed (see docs/CLAUDE.md)"; fail=1 + fi + echo "ok ${f}" + done + exit "$fail" + + claude-validate: + name: claude plugin validate --strict + runs-on: ubuntu-latest + timeout-minutes: 10 + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: 22 + - run: npm install -g @anthropic-ai/claude-code + - run: claude --version + - run: claude plugin validate --strict . + + cli: + name: diffbot CLI install lines resolve + runs-on: ubuntu-latest + timeout-minutes: 15 + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: "3.12" + + - name: Every documented install line uses one specifier + id: spec + run: | + set -euo pipefail + specs=$(grep -rhoE "pip install( -U| --force-reinstall --no-deps)? '[^']+'" skills README.md \ + | grep -oE "'[^']+'" | tr -d "'" | sort -u) + echo "specifiers found:"; printf ' %s\n' $specs + count=$(printf '%s\n' "$specs" | grep -c .) + if [ "$count" -ne 1 ]; then + echo "::error::expected one diffbot specifier across skills and README, found ${count}" + exit 1 + fi + echo "spec=${specs}" >> "$GITHUB_OUTPUT" + + - name: Install exactly as documented + run: | + set -euo pipefail + python3 -m venv ~/.diffbot/venv + ~/.diffbot/venv/bin/pip install --quiet '${{ steps.spec.outputs.spec }}' + ~/.diffbot/venv/bin/pip show diffbot | sed -n '1,2p' + ~/.diffbot/venv/bin/db --version + + - name: Every db subcommand the skills call exists + run: | + set -euo pipefail + cmds=$(grep -rhoE "venv/bin/db [a-z][a-z-]*( [a-z][a-z-]*)?" skills README.md \ + | awk '{ if ($2 == "dql" && $3 != "") print $2" "$3; else print $2 }' | sort -u) + fail=0 + while IFS= read -r c; do + [ -z "$c" ] && continue + if ~/.diffbot/venv/bin/db $c --help >/dev/null 2>&1; then + echo "ok db ${c}" + else + echo "::error::'db ${c} --help' failed; a skill calls a subcommand this CLI does not have" + fail=1 + fi + done <<< "$cmds" + exit "$fail" From 2ecd48b907b50849903adb32fe57e2453488a933 Mon Sep 17 00:00:00 2001 From: Andrew Wessels Date: Wed, 18 Nov 2026 11:59:48 -1000 Subject: [PATCH 6/6] Require diffbot>=3.4.0,<4 (stable) in every install line. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 2 +- README.md | 8 ++++---- docs/listing/anthropic/README.md | 2 +- docs/listing/anthropic/validation-proof.md | 2 +- skills/diffbot-crawl/SKILL.md | 2 +- skills/diffbot-deals/SKILL.md | 2 +- skills/diffbot-dql/SKILL.md | 2 +- skills/diffbot-entities/SKILL.md | 2 +- skills/diffbot-extract/SKILL.md | 2 +- skills/diffbot-news/SKILL.md | 2 +- skills/diffbot-organizations/SKILL.md | 2 +- skills/diffbot-people/SKILL.md | 2 +- skills/diffbot-places/SKILL.md | 2 +- skills/diffbot-web-search/SKILL.md | 2 +- 14 files changed, 17 insertions(+), 17 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 40f4be2..5a80e0c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,7 +5,7 @@ ### Changed - Built on 1.2.3. Skills still omit `allowed-tools`, and exports stay in `.diffbot/tmp/` in the working directory. -- Install lines require `diffbot>=3.4.0rc0,<4`. 3.1.x and 3.2.x are not new enough. +- Install lines require `diffbot>=3.4.0,<4`. 3.1.x and 3.2.x are not new enough. - The DQL skill states `POST https://kg.diffbot.com/kg/v3/dql` with a JSON body. The token stays the `token` query parameter. GET is the low-level escape hatch. Agents keep using `~/.diffbot/venv/bin/db`. - Plugin manifests are 1.3.0. Tag this release `v1.3.0`. diff --git a/README.md b/README.md index 8f413f9..b32e697 100644 --- a/README.md +++ b/README.md @@ -129,7 +129,7 @@ echo "DIFFBOT_API_TOKEN=YOUR_TOKEN_HERE" > ~/.diffbot/credentials && chmod 600 ~ 3. Install the `db` CLI once, into the virtualenv every skill reads: ```bash -python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0rc0,<4' +python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0,<4' ``` This is a one-time user install, the same as putting `gh` or `wrangler` on your machine. @@ -141,12 +141,12 @@ python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4 ### Upgrading the `db` CLI -These skills require `diffbot>=3.4.0rc0,<4` (the 3.4.0 release candidate) for this verification branch. The unison publish will raise the floor to `diffbot>=3.4.0`. If a skill reports a lower version, `db --version` fails with `No such option +These skills require `diffbot>=3.4.0,<4`. If a skill reports a lower version, `db --version` fails with `No such option '--version'` (an old `diffbot-python` install), or `db` warns about the `diffbot-python` rename, upgrade in place: ```bash -~/.diffbot/venv/bin/pip install -U 'diffbot>=3.4.0rc0,<4' +~/.diffbot/venv/bin/pip install -U 'diffbot>=3.4.0,<4' ``` 3.1.0 added `--version` and the rename from `diffbot-python`. 3.2.0 switched DQL to `POST https://kg.diffbot.com/kg/v3/dql` with a JSON body (the token stays the `token` query parameter; GET remains a low-level escape hatch). 3.4.0 is the cumulative release to install. 3.1.x and 3.2.x are not new enough and must be upgraded. The CLI sends that request; do not call the endpoint yourself. @@ -158,7 +158,7 @@ install afterwards no-ops on the surviving dist-info: ```bash ~/.diffbot/venv/bin/pip uninstall -y diffbot-python -~/.diffbot/venv/bin/pip install --force-reinstall --no-deps 'diffbot>=3.4.0rc0,<4' +~/.diffbot/venv/bin/pip install --force-reinstall --no-deps 'diffbot>=3.4.0,<4' ``` ## Skills diff --git a/docs/listing/anthropic/README.md b/docs/listing/anthropic/README.md index 350a0e9..07fad4c 100644 --- a/docs/listing/anthropic/README.md +++ b/docs/listing/anthropic/README.md @@ -64,7 +64,7 @@ home-directory `Read` allowlist tweak). Nothing had landed on main since Saturda | *BLOCKING: `allowed-tools` beyond Read, Grep, Glob, and LS* | every skill | `Bash` and `jq` removed from all ten. Nine skills keep only a `Read` entry scoped to a scratch folder under `~/.diffbot` (itself refused later; removed in 1.2.3). `diffbot-web-search` omits the `allowed-tools` key. No `${...}` paths, no `//` or `\\` paths, no URLs. `db` and `jq` prompt the user. | | *Pre-approves broad shell access (Bash)* | 10 | Resolved by the same Bash removal. | | *An image or font file the plugin's code could run* | 2 | Audited, files left as-is. The only image or font in the tree is `.claude-plugin/icon.png`, which the report already marked Info/passed. No hooks, scripts, commands, or skill instructions load or execute an image or font as code. No `icon` field added — it is not in the schema and `claude plugin validate --strict` fails on it. | -| *Download-and-run commands* (`curl \| sh`, `uvx`/`npx` of a remote URL, `pip install` from a URL) | 3 | Left as documentation. The plugin itself does not run them: there is no hook, script, command, or `` !`…` `` line, and no bundled installer was added. The README install / upgrade / `npx skills add` sections stay. Each skill's Step 1 block still shows `python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0rc0,<4'` for the user to run or approve, and still says the skill never installs, upgrades, or uninstalls the CLI. As of 1.3.0 that floor is 3.4.0; 3.1.x must be upgraded. 1.2.1's note that installing was "documented in the README only" was incomplete — the line also lives in those Step 1 blocks, as documentation. | +| *Download-and-run commands* (`curl \| sh`, `uvx`/`npx` of a remote URL, `pip install` from a URL) | 3 | Left as documentation. The plugin itself does not run them: there is no hook, script, command, or `` !`…` `` line, and no bundled installer was added. The README install / upgrade / `npx skills add` sections stay. Each skill's Step 1 block still shows `python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0,<4'` for the user to run or approve, and still says the skill never installs, upgrades, or uninstalls the CLI. As of 1.3.0 that floor is 3.4.0; 3.1.x must be upgraded. 1.2.1's note that installing was "documented in the README only" was incomplete — the line also lives in those Step 1 blocks, as documentation. | ## Directory review refusal after v1.2.2 diff --git a/docs/listing/anthropic/validation-proof.md b/docs/listing/anthropic/validation-proof.md index 2bd0540..d1e79dd 100644 --- a/docs/listing/anthropic/validation-proof.md +++ b/docs/listing/anthropic/validation-proof.md @@ -106,7 +106,7 @@ when *any* version is already present, so a venv created against 0.1.0 would nev upgrade. 0.1.0 sent the wrong query parameter for web-search `-n`, silently returning 10 results regardless — the version floor is what guarantees the documented flag behaves as described. As of plugin 1.3.0 the install and upgrade lines require -`diffbot>=3.4.0rc0,<4`. 3.1.0 added `--version` and the rename; 3.2.0 switched DQL to POST +`diffbot>=3.4.0,<4`. 3.1.0 added `--version` and the rename; 3.2.0 switched DQL to POST with a JSON body (token stays the `token` query parameter); users on 3.1.x must upgrade. ## Permissions summary diff --git a/skills/diffbot-crawl/SKILL.md b/skills/diffbot-crawl/SKILL.md index 424b5e1..7a4d331 100644 --- a/skills/diffbot-crawl/SKILL.md +++ b/skills/diffbot-crawl/SKILL.md @@ -50,7 +50,7 @@ fails with `No such file or directory`, stop and show the user this line to run themselves (it is deliberately not pre-approved): ``` -python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0rc0,<4' +python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0,<4' ``` If it prints a version below 3.4.0 (including 3.1.x and 3.2.x — upgrade them), fails with `No such option '--version'` (an old diff --git a/skills/diffbot-deals/SKILL.md b/skills/diffbot-deals/SKILL.md index 7a981e9..a1b03d5 100644 --- a/skills/diffbot-deals/SKILL.md +++ b/skills/diffbot-deals/SKILL.md @@ -26,7 +26,7 @@ fails with `No such file or directory`, stop and show the user this line to run themselves (it is deliberately not pre-approved): ``` -python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0rc0,<4' +python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0,<4' ``` If it prints a version below 3.4.0 (including 3.1.x and 3.2.x — upgrade them), fails with `No such option '--version'` (an old diff --git a/skills/diffbot-dql/SKILL.md b/skills/diffbot-dql/SKILL.md index 019d52b..5c872ab 100644 --- a/skills/diffbot-dql/SKILL.md +++ b/skills/diffbot-dql/SKILL.md @@ -46,7 +46,7 @@ fails with `No such file or directory`, stop and show the user this line to run themselves (it is deliberately not pre-approved): ``` -python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0rc0,<4' +python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0,<4' ``` If it prints a version below 3.4.0 (including 3.1.x and 3.2.x — upgrade them), fails with `No such option '--version'` (an old diff --git a/skills/diffbot-entities/SKILL.md b/skills/diffbot-entities/SKILL.md index eb294b0..42b34ae 100644 --- a/skills/diffbot-entities/SKILL.md +++ b/skills/diffbot-entities/SKILL.md @@ -37,7 +37,7 @@ fails with `No such file or directory`, stop and show the user this line to run themselves (it is deliberately not pre-approved): ``` -python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0rc0,<4' +python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0,<4' ``` If it prints a version below 3.4.0 (including 3.1.x and 3.2.x — upgrade them), fails with `No such option '--version'` (an old diff --git a/skills/diffbot-extract/SKILL.md b/skills/diffbot-extract/SKILL.md index 1fbb6c8..3f336cc 100644 --- a/skills/diffbot-extract/SKILL.md +++ b/skills/diffbot-extract/SKILL.md @@ -61,7 +61,7 @@ fails with `No such file or directory`, stop and show the user this line to run themselves (it is deliberately not pre-approved): ``` -python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0rc0,<4' +python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0,<4' ``` If it prints a version below 3.4.0 (including 3.1.x and 3.2.x — upgrade them), fails with `No such option '--version'` (an old diff --git a/skills/diffbot-news/SKILL.md b/skills/diffbot-news/SKILL.md index d3d24c8..6ed7f43 100644 --- a/skills/diffbot-news/SKILL.md +++ b/skills/diffbot-news/SKILL.md @@ -26,7 +26,7 @@ fails with `No such file or directory`, stop and show the user this line to run themselves (it is deliberately not pre-approved): ``` -python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0rc0,<4' +python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0,<4' ``` If it prints a version below 3.4.0 (including 3.1.x and 3.2.x — upgrade them), fails with `No such option '--version'` (an old diff --git a/skills/diffbot-organizations/SKILL.md b/skills/diffbot-organizations/SKILL.md index 545bfe8..ab74412 100644 --- a/skills/diffbot-organizations/SKILL.md +++ b/skills/diffbot-organizations/SKILL.md @@ -26,7 +26,7 @@ fails with `No such file or directory`, stop and show the user this line to run themselves (it is deliberately not pre-approved): ``` -python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0rc0,<4' +python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0,<4' ``` If it prints a version below 3.4.0 (including 3.1.x and 3.2.x — upgrade them), fails with `No such option '--version'` (an old diff --git a/skills/diffbot-people/SKILL.md b/skills/diffbot-people/SKILL.md index a614e46..5750cdd 100644 --- a/skills/diffbot-people/SKILL.md +++ b/skills/diffbot-people/SKILL.md @@ -33,7 +33,7 @@ fails with `No such file or directory`, stop and show the user this line to run themselves (it is deliberately not pre-approved): ``` -python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0rc0,<4' +python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0,<4' ``` If it prints a version below 3.4.0 (including 3.1.x and 3.2.x — upgrade them), fails with `No such option '--version'` (an old diff --git a/skills/diffbot-places/SKILL.md b/skills/diffbot-places/SKILL.md index e6df9c2..33c35f0 100644 --- a/skills/diffbot-places/SKILL.md +++ b/skills/diffbot-places/SKILL.md @@ -26,7 +26,7 @@ fails with `No such file or directory`, stop and show the user this line to run themselves (it is deliberately not pre-approved): ``` -python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0rc0,<4' +python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0,<4' ``` If it prints a version below 3.4.0 (including 3.1.x and 3.2.x — upgrade them), fails with `No such option '--version'` (an old diff --git a/skills/diffbot-web-search/SKILL.md b/skills/diffbot-web-search/SKILL.md index 7741773..59d64bf 100644 --- a/skills/diffbot-web-search/SKILL.md +++ b/skills/diffbot-web-search/SKILL.md @@ -127,7 +127,7 @@ fails with `No such file or directory`, stop and show the user this line to run themselves (it is deliberately not pre-approved): ``` -python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0rc0,<4' +python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0,<4' ``` If it prints a version below 3.4.0 (including 3.1.x and 3.2.x — upgrade them), fails with `No such option '--version'` (an old