Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -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",
Expand Down
2 changes: 1 addition & 1 deletion .cortex-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -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",
Expand Down
2 changes: 1 addition & 1 deletion .factory-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -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",
Expand Down
2 changes: 1 addition & 1 deletion .github/plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -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",
Expand Down
135 changes: 135 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -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"
64 changes: 64 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
@@ -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
2 changes: 1 addition & 1 deletion .grok-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -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",
Expand Down
12 changes: 12 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
# Changelog

## 1.3.0 - 2026-11-17

### 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,<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`.

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.
20 changes: 11 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down Expand Up @@ -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)

Expand Down Expand Up @@ -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,<4'
```

This is a one-time user install, the same as putting `gh` or `wrangler` on your machine.
Expand All @@ -141,22 +141,24 @@ 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,<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.1.1'
~/.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.

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
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,<4'
```

## Skills
Expand Down Expand Up @@ -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)

Expand Down
2 changes: 1 addition & 1 deletion docs/listing/anthropic/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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,<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

Expand Down
8 changes: 5 additions & 3 deletions docs/listing/anthropic/validation-proof.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <pkg>` 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,<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

Expand Down
4 changes: 2 additions & 2 deletions docs/listing/xai/xai-pr.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/`).
Expand Down
6 changes: 3 additions & 3 deletions skills/diffbot-crawl/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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,<4'
```

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.
Expand Down
Loading
Loading