From paper-protocol
Load a published paper repository, local publication-staging tree, non-APP paper repository, or arXiv paper into your current project. Use when a user wants to consult, build on, test, import, or discuss a paper. For arXiv IDs or URLs, fetch metadata/source, search for associated public code, and create a protocol-shaped local import before continuing with paper classification.
How this skill is triggered — by the user, by Claude, or both
Slash command
/paper-protocol:load-paperThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Load a published paper into your project so you can consult it, reproduce results, and build on the work. This is a reader/import utility, not a required part of publishing or validating an APP publication.
Load a published paper into your project so you can consult it, reproduce results, and build on the work. This is a reader/import utility, not a required part of publishing or validating an APP publication.
For debugging or exploratory review, this skill can also inspect a local APP candidate such as publication-staging/. In that case, do not clone anything; treat the supplied local staging directory as the paper repo root. The /publish-paper workflow performs its required final paper-agent smoke test directly from the staging root rather than depending on this loader.
User says something like:
If the user supplies a local staging path such as publication-staging/, skip cloning:
cd publication-staging
Then continue with the APP compliance and exploration checks below, treating this directory as the repo root. This is a pre-publication test; it does not imply the staged tree is publicly released.
For remote public repos:
mkdir -p papers/
git clone <url> papers/<repo-name>
If the user specifies a version:
git clone --branch v1.0.0 <url> papers/<repo-name>
If the user does not specify a version and the default branch is not exactly at a release tag, the repo can still be explored, but it cannot be verified as an APP publication from that checkout. For APP verification, prefer checking out an explicit release tag. If GitHub release metadata is available, identify the latest release tag and offer to check it out before verification.
If the user gives an arXiv ID or URL instead of a GitHub URL, use the arXiv input mode in arxiv.md. That mode creates a local import under papers/arxiv-ARXIV_ID/, then returns here for APP compliance and exploration checks using that import root.
If the clone fails (private repo, wrong URL), inform the user and ask for the correct URL or access.
Do not treat AGENTS.md or CLAUDE.md alone as proof of APP compliance. Classify the repo into one of three levels:
AGENTS.md, CLAUDE.md, README, or other useful docs, but no verified APP release manifest.AGENTS.md with YAML frontmatter containing protocol: agentic-publication-protocol, but no verified release manifest.APP_PUBLICATION.json release manifest. The manifest must match the repo URL, tag, commit, tree, validation report hash, and human approval record, and its app_publication_id must recompute correctly.Look for agent and human documentation:
AGENTS.mdCLAUDE.mdREADME.mdIf AGENTS.md exists, read it and check:
protocol: agentic-publication-protocol?APP_PUBLICATION.json for that tag?If AGENTS.md does not exist, still continue. Read CLAUDE.md, README, docs, paper files, and code entry points directly. The repo is not APP-structured, but it may still be useful.
For local publication-staging/, stop at APP-structured candidate at most. Staging can be tested for reader-agent usability, but it is not a verified APP publication because it has no public release manifest.
For remote public repos, verify the manifest before calling the repo fully APP-compliant.
Identify the checkout and tag:
cd <repo-root>
COMMIT_SHA=$(git rev-parse HEAD)
TREE_SHA=$(git rev-parse HEAD^{tree})
TAG=$(git describe --tags --exact-match 2>/dev/null || true)
If TAG is empty, the checkout is not a verified APP publication. Report it as an APP-structured candidate if AGENTS.md has APP frontmatter.
Download the release manifest:
gh release download "$TAG" --pattern APP_PUBLICATION.json --dir /tmp/app-manifest
If gh is unavailable, use the GitHub releases API or ask the user to provide the APP_PUBLICATION.json release asset. Do not trust a committed APP_PUBLICATION.json file as the canonical manifest unless it exactly matches the release asset.
Verify manifest fields:
jq -e '.protocol == "agentic-publication-protocol"' /tmp/app-manifest/APP_PUBLICATION.json
jq -e '.publication_type == "app-publication"' /tmp/app-manifest/APP_PUBLICATION.json
jq -e --arg tag "$TAG" '.tag == $tag' /tmp/app-manifest/APP_PUBLICATION.json
jq -e --arg commit "$COMMIT_SHA" '.commit == $commit' /tmp/app-manifest/APP_PUBLICATION.json
jq -e --arg tree "$TREE_SHA" '.tree == $tree' /tmp/app-manifest/APP_PUBLICATION.json
jq -e '.validation.stage == "full" and .validation.result == "passed"' /tmp/app-manifest/APP_PUBLICATION.json
jq -e '.human_approval.approved == true' /tmp/app-manifest/APP_PUBLICATION.json
Verify the validation report hash if the report is present in the repo:
REPORT_SHA=$(shasum -a 256 supplementary/validation-report.md | awk '{print $1}')
jq -e --arg report "$REPORT_SHA" '.validation.validation_report_sha256 == $report' \
/tmp/app-manifest/APP_PUBLICATION.json
If the validation report is a release asset rather than committed in the repo, download that asset and hash it instead.
Recompute the APP publication ID. Remove app_publication_id from the manifest, canonicalize the payload with sorted keys and compact JSON, hash it, and compare:
jq 'del(.app_publication_id)' /tmp/app-manifest/APP_PUBLICATION.json \
| jq -S -c . > /tmp/app-manifest/APP_PUBLICATION.payload.canonical.json
COMPUTED_ID="app-v1:sha256:$(shasum -a 256 /tmp/app-manifest/APP_PUBLICATION.payload.canonical.json | awk '{print $1}')"
MANIFEST_ID=$(jq -r '.app_publication_id' /tmp/app-manifest/APP_PUBLICATION.json)
test "$COMPUTED_ID" = "$MANIFEST_ID"
Also compare the manifest repo_url to the clone URL after normalizing common GitHub forms ([email protected]:user/repo.git, https://github.com/user/repo, https://github.com/user/repo.git). If they do not identify the same GitHub repo, do not mark the publication as verified.
If all checks pass, report the repo as a verified APP publication and include the app_publication_id.
If any check fails, report the highest level that is still supported:
For verified APP publications or APP-structured candidates, read the AGENTS.md and report to the user:
paper_format in frontmatter)app_publication_id if verifiedsupplementary/ exists) — know-how, author notes, sessions, additional materialsskills/ exists) — list each skill with its name and description from the SKILL.md frontmatterFor agent-readable non-APP repos, read the available docs in this order:
AGENTS.md, if present, even without APP frontmatter.CLAUDE.md, especially for imports or pointers to other docs.README.md.Report:
For non-APP repos with no agent-readable docs, proceed by inspecting the content directly. Do not stop just because AGENTS.md, CLAUDE.md, or README is missing. Report:
Before running anything from the paper:
environment/requirements.txt or equivalentcd <repo-root>
pip install -r environment/requirements.txt # or equivalent
data/README.md first for URLs, download commands, local destinations, and required-for-default-workflow flags; AGENTS.md Repository Structure may carry a high-level pointer. For non-APP repos, search README, docs, scripts, notebooks, configs, and paper source. If the user needs data that isn't in the repo:
The paper, code, and data are the ground truth. For APP repos, the paper document, accompanying code in code/, and data documented in data/README.md are authoritative for claims, results, and reproduction details. Supplementary materials provide additional context but are secondary. If anything in the supplementary materials conflicts with the ground truth, defer to the paper, code, and data. For non-APP repos, first identify the most likely canonical paper file by inspecting filenames, README/docs, build files, and paper directories.
When the user asks questions about this paper, route to the right source:
Routing guide — which file for which question:
| User asks about... | Primary source | Also check |
|---|---|---|
| What the paper claims, methods, results | Paper, code, data (ground truth) | AGENTS.md Paper Summary |
| Why a specific choice was made | supplementary/know-how.md | Paper source for what the choice was |
| What to know before reading | supplementary/authors-note.md | AGENTS.md Paper Summary |
| How to reproduce a figure | code/figure-reproduction/README.md if present | AGENTS.md figure summary, README/docs, scripts, notebooks, paper source, run the command |
| How to run an analysis or workflow | skills/ if present | AGENTS.md "What You Can Do", README/docs, scripts |
| What parameters to change | AGENTS.md "Extend the work" if present | Code configs, scripts, notebooks |
| Computational requirements | AGENTS.md Computational Requirements if present | README/docs, environment files, imports, scripts |
Explaining:
supplementary/, use them to explain the reasoning behind decisions — but note that these provide context, not authoritative claimssupplementary/know-how.md exists, use it to answer "why did you do X?" questions — this is where tacit knowledge livessupplementary/authors-note.md exists, use it for the authors' perspective on what matters beyond the paperReproducing:
code/figure-reproduction/README.md. It is the authoritative map from paper figures/tables to reproduction scripts when present.code/figure-reproduction/README.md, trust the code README and report the inconsistency.data/README.md first for APP repos; otherwise search README/docs, scripts, notebooks, configs, and paper source for download instructions. Tell the user what's needed, how large it is, and offer to download it (with approval) before retrying.Extending:
Using skills:
skills/, read the SKILL.md files to discover what capabilities the authors providedAttribution:
Feedback loop:
If the user loads multiple papers into papers/:
If the user wants to reference the paper from their own AGENTS.md or CLAUDE.md:
For Claude Code:
# In the user's CLAUDE.md:
@papers/paper-name/AGENTS.md
For any platform: Add to the user's AGENTS.md:
## Referenced Papers
- [Paper Title](papers/paper-name/AGENTS.md) — [one-line description of how it relates to this project]
This makes the paper context available whenever the user works on their project.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub lionsr/agenticpublicationprotocol --plugin paper-protocol