phd-skills: Claude Code guardrails for paper reproduction and experiment runs
PhD Research Skills for Claude Code: paper reproduction, experiment design, paper review, result comparison and more.
At a glance
- What is it?
- fcakyon/phd-skills is a Claude Code plugin of commands, auto-triggering skills, agents and silent hooks aimed at research workflows. The interesting part is not the command count, it is the hooks that fire without being asked.
- Who is it for?
- Adopt phd-skills if you already run Claude Code against training code and want pre-flight checks, epoch-aligned comparisons and a stop hook that re-reads conclusions against artifacts. Skip it if your work is not Claude Code based, or if you want a general literature tool rather than run guardrails, since the plugin is a set of behaviours for one agent, not a standalone application.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 74 days ago.
- What is it written in?
- Mainly Shell, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The failures phd-skills was built to catch
The README opens with a list of concrete incidents rather than a feature pitch. Among them: a typo that turned a confirmation into an unwanted upload of thousands of files, an analysis that ran over a full dataset when a specific 4k/2k/2k split was requested, a claim that a test covered a bug it had never verified, a 50-hour training job restarted without diffing the config against the reference run, and an `rm -rf` on a path recalled from memory rather than checked, which destroyed local checkpoints. The author, Fatih Cagatay Akyon, states the plugin came out of 300+ Claude Code sessions and that every guardrail traces to a real mistake.
That framing matters for who this is for. It is not aimed at people who want an assistant that writes more prose. It is aimed at researchers who already let an agent touch training scripts, checkpoints and remote machines, and who have felt the cost of a confident wrong answer. The unit of value here is a prevented action, not a generated artifact.
Commands, auto-triggering skills, agents and silent hooks
The repository is a Claude Code plugin, and the layout reflects that: a `.claude-plugin/` directory, a `plugin/` directory, a `README.md` and a `LICENSE`. Nothing in the top-level listing suggests a runtime service, a database or a daemon.
There are four distinct mechanisms. Commands are explicit, typed invocations such as `/phd-skills:xray`, which the README describes as auditing a paper against code and data across five parallel dimensions, and `/phd-skills:factcheck`, which verifies BibTeX entries and cited claims against DBLP. Skills are described as auto-triggering: you describe a problem in natural language and the matching skill activates, for example `debug` when you ask why a loss is diverging, or `compare` when you ask to compare one run to a baseline. Agents are delegated to automatically by Claude; `paper-auditor` cross-checks paper claims against code and data and, per the README, runs in an isolated worktree and remembers patterns across sessions, while `experiment-analyzer` reads results from wandb, neptune, tensorboard, mlflow or local files and hands off to the `compare` and `debug` skills.
The fourth mechanism is the one worth attention. Hooks are documented as running silently and never being invoked by hand. The README names three: a stop hook that puts conclusions in front of a fresh-context research peer for review against actual artifacts, a guard against in-place edits to git-tracked source over SSH, and a check for unverified commands or paths in outbound teammate messages. A plugin that adds commands is easy to evaluate. A plugin that intervenes without a prompt is a different kind of commitment, because its behaviour is only visible when it blocks something.
Installing phd-skills and running a first reproduction
Installation goes through the Claude Code plugin marketplace. Two commands, run in that order:
claude plugin marketplace add fcakyon/phd-skills
claude plugin install phd-skills@phd-skillsThe README states the plugin works correctly the moment it is installed. There is an optional setup step, `/phd-skills:setup`, described as a 30-second tour of what was auto-detected, with opt-in extras for notifications, an allowlist and LaTeX. The README does not document a rollback path for the setup step, so treat the opt-in extras as the part to read before confirming.
For a first real use, open Claude Code in your project directory and reproduce a paper from an arxiv identifier:
/phd-skills:reproduce arxiv 2508.12345The README describes this as reproducing a paper from an arxiv URL through to replication runs. The identifier in the example is the one the README uses. Expect the skill to drive the reproduction rather than emit a single script. If you would rather test the guardrails before the reproduction path, the cheaper entry point is to describe a failing run in plain language and let the `debug` skill trigger on its own, since the README lists phrases like "why is X failing" as the trigger.
Zero dependencies and no MCP server, and what that buys
The README badges state zero dependencies and that MCP is not required. For a plugin whose job is to constrain an agent, that is a defensible design choice: there is no server process to keep alive, no credential to store, and no extra surface for the agent to reason about. The whole thing is shell and markdown, consistent with the repository's primary language being Shell.
The trade-off is that the plugin cannot enforce anything outside Claude Code. The hooks described in the README are hooks in the Claude Code sense, so a researcher who launches training from a terminal, or who edits a config in an editor without an agent involved, gets none of this. The guardrails are attached to the agent's actions, not to the filesystem. If your failure mode is a human typo in a shell command, phd-skills is not the layer that catches it.
Where the guardrails stop: silent hooks and unverifiable coverage
The most consequential claim in the README is also the hardest to check from the outside. Hooks that run silently and are never invoked by hand have no visible interface. When one fires, you see a blocked action; when one does not fire, nothing tells you whether the condition was absent or the hook failed to load. The README does not include a way to list active hooks or confirm they are registered, and it does not document logging for them.
There is a second boundary. The plugin's stated purpose is catching AI mistakes in research workflows, and several of its listed incidents are about the agent's own confidence: claiming a test covered a bug, trusting numbers without looking at a generated figure, declaring an experiment diverging from a non-converged proxy metric. Those are behavioural corrections, and behavioural corrections in an agent are probabilistic. The README does not claim the hooks make mistakes impossible, and a reader should not infer that. The honest reading is that phd-skills adds friction at specific decision points: before launching, before concluding, before editing tracked source over SSH.
A third limitation is scope of language. The plugin is built around Claude Code specifically. The commands use the `/phd-skills:` namespace and the skills trigger on Claude Code's natural-language routing. Nothing in the repository suggests a portable format, so adopting this does not carry over to another agent tool.
phd-skills compared with a general research skill library
The related searches around this project mix two different things: lists of PhD skills in the career sense, and AI research skill libraries for coding agents. phd-skills is firmly the second, and the distinction from a general skill library is the approach, not the feature list.
A general library, whether called a skill library or an academic research skill set, tends to be a collection of prompts and commands you invoke when you remember to. The value is breadth: many topics, many outputs. phd-skills inverts that. Its commands are a minority of what it ships. The bulk is skills that trigger from a described problem and agents that Claude delegates to on its own, plus hooks that the README says you never invoke. The README states the contrast directly: other plugins give you more commands, this plugin gives you guardrails.
That is a real difference in what you are adopting. A command library is inert until called and easy to evaluate. A guardrail set changes agent behaviour by default, which is more useful if the failure modes match yours and more annoying if they do not. The README does not document a way to disable individual hooks, so the granularity of that control is unclear from what the repository describes.
Maintenance status and licence
The repository is not archived. The last push was on 2026-07-03, which is recent relative to the releases listed: v1.0.0 on 2026-03-11, v1.1.0 on 2026-03-14, and v1.3.0 on 2026-05-09, whose release title is "Catch AI mistakes before they cost weeks of compute". The cadence across those three releases is roughly two months, and there is no published roadmap in the README.
Upgrade cost looks low by construction. The plugin declares zero dependencies and no MCP requirement, so a version bump does not drag a dependency tree with it. The thing that can change between versions is hook behaviour, and since hooks are silent by design, a version bump is the moment to re-read the release notes rather than assume the guardrails are unchanged.
Licensing is MIT, per the repository metadata and the LICENSE file at the top level. MIT is permissive, but this is a description of the licence identifier, not legal advice. If you are packaging the plugin into a commercial product or a regulated environment, read the LICENSE file itself and check how your organisation treats MIT-licensed agent tooling.
Editorial conclusion
Adopt phd-skills if you already run Claude Code against training code and want pre-flight checks, epoch-aligned comparisons and a stop hook that re-reads conclusions against artifacts. Skip it if your work is not Claude Code based, or if you want a general literature tool rather than run guardrails, since the plugin is a set of behaviours for one agent, not a standalone application. Before relying on it, verify that the hooks actually fire in your setup, because the README describes them as running silently and never being invoked by hand, and confirm the MIT licence terms against the LICENSE file in the repository root.
Frequently asked questions
What's a PhD like, and does phd-skills address that?
phd-skills addresses the operational side of research computing, not the experience of doing a PhD. Its commands and skills cover paper reproduction, debugging runs, comparing experiments and preparing code for release, which are the parts of a PhD that involve training jobs and artifacts.
What is a PhD useful for, and does phd-skills fit that?
The plugin is scoped to research workflows rather than career questions. The README describes it as built for reproducing papers from arxiv, debugging runs, comparing experiments at the same epoch and launching runs with a pre-flight checklist.
What makes up a PhD, and what does phd-skills cover of it?
The README covers the parts that involve code and artifacts: paper reproduction, experiment design, result comparison, paper review, literature gap analysis and dataset curation. It does not claim to cover the rest of a PhD.
What makes someone a PhD, and is phd-skills meant for that?
phd-skills is a Claude Code plugin, not a programme or an assessment. The README says it was built after 300+ Claude Code sessions and that every guardrail traces to a real mistake made during PhD research.
Community notes