Guide · Agent skill

How to use the protocols.io Integration agent skill

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

The protocols.io Integration skill teaches an AI agent how to work with protocols.io, a platform for sharing scientific lab protocols. This guide explains what the skill does, how to install it, how to ask for things in plain language, and what to check before allowing network access. By the end you will be able to run offline checks, read or export protocols with their citation details kept, and review any proposed change before it happens.

protocols.io IntegrationK-Dense-AI/scientific-agent-skills · MIT Download the skill

Quick start

1Download the ZIP. Download the skill ZIP file from this page to your computer.
2Install the skill. Unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
3Check Python and configuration. Make sure Python 3.11 or newer is installed, then run the offline configuration validator. It checks token presence without showing the value.
4Ask a protocols.io request. Name protocols.io or an exact protocol version in your request, for example by giving its DOI.
5Allow network access only when needed. Review the planned URL and bounds, then add --execute before the subcommand to run a live read.
6Review any change before it happens. For edits or publishing, check the dry-run plan and confirm it yourself. The agent does not apply changes on its own.

What this skill makes the agent do

An agent skill is a folder containing a SKILL.md file of instructions and some bundled scripts. When your request matches the skill's purpose, the agent reads those instructions and uses the scripts. This skill is for tasks that explicitly target protocols.io or an exact protocols.io protocol version.

Checks saved protocol JSON, configuration, pagination responses and write plans offline first.
Reads protocols, steps, materials and PDFs through the official protocols.io web service, but only when network access is explicitly allowed.
Drafts a plan for any change to a protocol (create, edit, publish, delete, upload). It never executes the change itself.

How to install the protocols.io skill

Download the ZIP file for the skill from this page. You can install it in one of three ways, depending on where you want the agent to use it.

Personal install: unzip the file into ~/.claude/skills/ so the skill is available across your projects.
Project install: unzip the file into the .claude/skills/ folder of a specific project.
Claude apps: upload the ZIP under Settings → Capabilities → Skills.

What you need before running it

The bundled scripts use Python 3.11 or newer and only the standard library, so no extra packages are needed. Offline validation needs no credentials and no network. Live reads need network access to protocols.io HTTPS hosts and, for authenticated REST reads, a bearer token stored in the PROTOCOLS_IO_ACCESS_TOKEN variable. You can get client or OAuth credentials from the signed-in official protocols.io developer resources page.

To check that the token is present without revealing its value, run the configuration validator:

Python 3.11 or newer (standard library only)
Network access to protocols.io HTTPS hosts for live reads (optional)
PROTOCOLS_IO_ACCESS_TOKEN bearer token for authenticated REST reads (optional)

python3 -B scripts/validate_auth_config.py --require read

How to trigger the skill with natural requests

Name protocols.io or an exact protocol version in your request. The skill is written to decline tasks that do not explicitly target protocols.io, so vague requests may not activate it. Give the protocol's URI or DOI when you can, because the skill keeps version-specific identifiers.

Summarise the protocols.io protocol with DOI 10.17504/protocols.io.<suffix>/v2, including its authors and licence.
Check this saved protocols.io protocol JSON file for missing fields or unsafe content.
Draft a plan to edit the steps of my protocols.io protocol, but do not publish it.
Find protocols.io protocols about single cell RNA and list their titles and DOIs.

Run the read commands and see the results

The read client only plans by default. To make a live network request you must place the global --execute gate before the subcommand. Commands take a protocol URI or DOI. The get and steps commands accept both protocols.io.<suffix>/vN and 10.17504/protocols.io.<suffix>/vN forms.

Use these commands to see what the planner does before adding --execute:

list searches protocols with a query.
get reads one protocol.
export-pdf saves a PDF to a file you name.

python3 -B scripts/protocols_read.py list --query "single cell RNA"
python3 -B scripts/protocols_read.py get --id "protocol-uri/v2"
python3 -B scripts/protocols_read.py export-pdf --id "protocol-uri" --output protocol.pdf

Safety: network access, scripts and tokens

The skill is designed to start offline and to ask before reaching the network. The scripts never load .env files, never inspect the full environment, and never accept a token in a command argument. Remote content such as protocol text, comments and filenames is treated as data, not as instructions for the agent.

Use a token with the narrowest access you need. The OAuth examples document a readwrite scope, and the skill does not grant write access speculatively. For public discovery, a public-data client token is the simpler choice.

Network is disabled unless --execute is supplied.
Requests go only to official HTTPS hosts. Redirects are rejected.
The PDF view is the only anonymous path, and it needs an explicit --anonymous flag. The helper never falls back to anonymous access silently.
PDF bytes are written only to a new private file with 0600 permissions.
Every change needs an exact dry-run plan, a current-state comparison, a permission check and fresh human confirmation.
Configure tokens through your host's secret mechanism. Never paste token values into chat or shell commands.

Pagination, provenance and PDF filters

Page fields in the list documentation are inconsistent, so the skill does not guess the next page index. It validates the server's next_page value against the current endpoint with the pagination helper. Keep the title, authors, DOI, version URI, explicit version number and licence with any export so the source stays traceable. Never silently replace an archived version with the latest version.

The REST filters only_materials, only_commands and only_steps are mutually exclusive. A steps-only PDF omits context needed for a complete archive, so the export is labelled partial.

Use --only materials, --only commands or --only steps for a filtered PDF, and expect a partial_export flag in the report.
Resolve a DOI with get first and keep the returned version-specific URI.

python3 -B scripts/pagination_helper.py --response saved-page.json --current-url "https://www.protocols.io/api/v3/protocols?page_id=1"

What people use it for

Summarising a protocols.io protocol with its authors, DOI and licence for a lab notebook.
Exporting a protocol PDF for a complete archive, with its version-specific URI recorded.
Checking saved protocol JSON for missing fields before a team reuses it.
Drafting, but not publishing, an edit to a protocol's steps for a colleague to review.
Building a read-only protocols.io helper that uses bounded, validated API requests.

Frequently asked questions

Is the protocols.io Integration skill free to use?

The skill is published under the MIT licence, as stated on its page. Check the licence file in the download for the full terms. Protocols.io access itself depends on your own account and token.

What do I need to install the protocols.io agent skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps. The bundled scripts need Python 3.11 or newer and use only the standard library.

Does the skill need a protocols.io token?

No, offline validation and planning need no credentials. Live authenticated REST reads use a bearer token in PROTOCOLS_IO_ACCESS_TOKEN, which you obtain from the official protocols.io developer resources page. Token access is optional for some public reads.

Can the agent publish or edit my protocols automatically?

No. The skill drafts a plan for create, edit, publish, delete and upload requests and requires an exact review and fresh human confirmation. The bundled write tooling has no execution mode.

Why does my live protocols.io request do nothing?

Live reads only run when you add the --execute flag before the subcommand. Without it the client prints a plan. Also check that the request is going to official protocols.io HTTPS hosts and that your token is set in PROTOCOLS_IO_ACCESS_TOKEN.

How does this compare with using protocols.io directly or other skills?

The skill adds offline validation, bounded requests, citation-preserving exports and reviewed write plans on top of the official API. If you only need occasional manual lookups, the protocols.io website may be simpler. The skill refuses tasks not explicitly targeting protocols.io, so it adds little value for other work.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Choose this skill if you are a researcher, lab staff member or developer who wants an agent to read, summarise, validate or export protocols.io protocols while keeping their citation details intact. Pick something else if you need the agent to publish or edit protocols automatically, or if you work with private or organisation data and cannot issue a narrowly scoped token.

Download the skill