Skills, MCP & Plugins¶
You will explain your conventions to an agent exactly once — if you write them down in the places the agent actually looks.
CLAUDE.md: the project brief¶
A markdown file at the project root, loaded automatically every session. Treat it as the briefing you'd give a new student:
# CLAUDE.md
- Python via uv; run anything with `uv run`.
- Units: natural units (G = c = 1) everywhere. Masses in solar masses.
- Every physics function gets a docstring with the equation it implements
and a reference (paper + equation number).
- Run `uv run pytest` before declaring any task done.
- Plots: matplotlib, save to artifacts/, never plt.show().
Five lines like these eliminate 80% of "the agent did it wrong" frustration. When the agent makes a mistake you find yourself correcting twice — that's a CLAUDE.md line.
Skills: reusable procedures¶
A skill is a markdown file describing a procedure the agent can invoke
by name (.claude/skills/, or shared via plugins). Where CLAUDE.md says
"how things are here," a skill says "how to do this multi-step task":
---
name: parameter-scan
description: Run a parameter scan and produce the standard report
---
1. Read scan_config.yaml for the grid.
2. Run each point with `uv run python -m project.scan --point ...`,
parallelizing across available cores.
3. Collect into artifacts/scan.parquet.
4. Produce artifacts/scan_report.md with the standard corner plot, the
best-fit table, and any failed points flagged.
Now /parameter-scan does in one command what took you a paragraph of
prompting — and it does it the same way every time. Skills are how a
research group standardizes its agentic workflows: write once, commit to
the repo, everyone's agent inherits the procedure.
MCP: giving the agent instruments¶
The Model Context Protocol connects agents to external systems as first-class tools: databases, arXiv search, Slack, your experiment's data catalog, a browser. If a skill is a procedure, an MCP server is an instrument — something the agent can operate.
> Find the three most recent papers on quasinormal mode spectral
> instability and summarize what each adds.
Plugins¶
Plugins bundle skills + MCP servers + configuration into something installable — the unit of sharing workflows between people and groups. The pattern for a research group: one plugin, containing your skills and your data-access MCP servers, installed by every member.
The progression
CLAUDE.md (facts about here) → skills (procedures) → MCP (instruments) → plugins (the shareable bundle). Start with CLAUDE.md today; add the rest when you feel the repetition.