softnano-plugins

Shared plugin for the SoftNano lab. Provides reusable skills for HPC job management, code review, literature search, and more — usable from either Claude Code or Codex.

Install

Claude Code

From within a Claude Code session, add the marketplace and install the plugin:

/plugin marketplace add softnanolab/softnano-plugins
/plugin install softnano@softnanolab-plugins

Or add directly to ~/.claude/settings.json:

{
  "extraKnownMarketplaces": {
    "softnanolab-plugins": {
      "source": {
        "source": "github",
        "repo": "softnanolab/softnano-plugins"
      }
    }
  },
  "enabledPlugins": {
    "softnano@softnanolab-plugins": true
  }
}

Invoke skills as /softnano:<skill-name> — e.g. /softnano:monitor-jobs, /softnano:codex "review plan X".

To update or remove:

/plugin update softnano
/plugin remove softnano

To test a local checkout or branch without installing it globally, check out the branch and start Claude Code with the plugin directory:

claude --plugin-dir /path/to/softnano-plugins

Codex

Requires Codex 0.122.0 or newer (brew upgrade codex / npm install -g @openai/codex).

codex plugin marketplace add softnanolab/softnano-plugins

Then run /plugins inside a Codex session, select softnano, and install it. Invoke skills as $softnano:<skill-name> — e.g. $softnano:monitor-jobs, $softnano:claude "review plan X" — or pick them from the /skills menu.

To update or remove:

codex plugin marketplace upgrade softnanolab-plugins
codex plugin marketplace remove softnanolab-plugins

To test a branch before it is released:

codex plugin marketplace remove softnanolab-plugins || true
codex plugin marketplace add softnanolab/softnano-plugins --ref <branch-or-tag>

To test a local checkout:

codex plugin marketplace remove softnanolab-plugins || true
codex plugin marketplace add /path/to/softnano-plugins

Codex-specific notes:

Claude Code reads the root plugin; Codex reads the marketplace entry at plugins/softnano.
Keep skills/ and plugins/softnano/skills/ synchronized with scripts/sync-codex-skills.sh; verify with scripts/check-codex-skill-sync.sh and python3 scripts/check-codex-plugin.py. CI runs these checks on pull requests.
The cross-agent helper intentionally differs: Claude Code exposes /softnano:codex; Codex exposes $softnano:claude.
Claude-only frontmatter fields (argument-hint) are silently ignored by Codex.
allowed-tools and user-invocable are recognised by both CLIs. Avoid disable-model-invocation in Codex-packaged skills; the Codex plugin validator rejects it.
The plugin is named softnano even though the repo is softnano-plugins. Codex resolves the plugin name from plugins/softnano/.codex-plugin/plugin.json; the marketplace path must be non-empty.

Skills

The examples below use Claude Code slash-command syntax unless a section is marked Codex-only. In Codex, invoke shared skills with the same skill name but the $softnano:<skill-name> prefix.

`/softnano:submit-wandb-job`

Submit one or more wandb-logged training/finetuning jobs to the HPC scheduler. WANDB_PROJECT is pinned per repo (snake_case basename); WANDB_RUN_GROUP is asked per invocation. The training script must take the experiment/group name as a config key (e.g. Hydra meta.experiment_name=<group>); the skill checks the user's command passes it.

/softnano:submit-wandb-job [N] [--group <name>] [--one-off] [--skip-commit-check]

What it does:

Derives WANDB_PROJECT from .env or the repo basename (constant per repo)
Picks WANDB_RUN_GROUP: --one-off → tmp; explicit --group honored; otherwise suggests existing groups (from $JOBS_DIR/<project>/*/ and recent $LOGS_DIR/wandb/run-*/files/config.yaml) and asks via AskUserQuestion
Asks once to commit any uncommitted changes (recommended) or bypass — pins each run to a real git SHA. Use --skip-commit-check to submit a dirty tree anyway; those runs are flagged in the submission report
Collects the command + a short tag per job, and verifies the command passes the experiment/group name as a config key (so Hydra-style configs actually receive it)
Delegates scheduler templating to /softnano:cluster-instructions, writes scripts into $JOBS_DIR/<project>/<group>/, submits via sbatch/qsub, reports IDs + log paths
On mid-batch failure, asks whether to scancel/qdel the jobs that already made it into the queue

Refuses outside a git repo, prompts before proceeding on detached HEAD, never auto-commits, never --no-verify.

`/softnano:monitor-jobs`

Monitor SLURM/PBS jobs and their logs. Automatically detects running/pending jobs, tails logs, and reports errors.

/softnano:monitor-jobs [job-id]

What it does:

Auto-detects the HPC scheduler (SLURM or PBS Pro)
Lists active jobs or uses a provided job ID
Waits for pending jobs to start (polls automatically)
Tails logs and identifies errors, warnings, and training progress
Reports W&B run URLs, loss values, and training metrics
On errors: analyzes root cause and proposes fixes

If no job ID is given, it finds and monitors the user's active jobs.

`/softnano:cluster-instructions`

Detect which HPC cluster you are on and load the correct job submission instructions. Covers CX3/HX1 (PBS Pro), Isambard (SLURM), new MMM Young NG (SLURM), and old MMM Young (SGE).

/softnano:cluster-instructions [command-to-run]

What it does:

Detects the cluster from host/path and available scheduler commands
Checks if you are on a login node or compute node
Loads cluster-specific instructions (queues, templates, storage paths)
Submits the command via the correct scheduler, or reports the detected environment

Includes full reference docs for CX3/HX1 (PBS Pro), Isambard (SLURM), MMM Young NG (SLURM/A100), and MMM old Young (SGE) with job templates, queue tables, and common commands. softnanolab-campus is treated as a workstation/gateway host: it may expose SLURM commands, but it is not the MMM/HPC cluster target, so the skill instructs agents to SSH onward instead of treating campus-local scheduler commands as authoritative.

`/softnano:codex` (Claude Code)

Get a second opinion from OpenAI Codex CLI. Cross-check reasoning, validate plans, or get an independent code review.

/softnano:codex <task or question>

What it does:

Reads relevant files to build context
Constructs an unbiased prompt (no leading conclusions)
Runs Codex in read-only mode via codex exec --full-auto
Reports the Codex response and notes agreements/disagreements
Lets you decide how to proceed

`$softnano:claude` (Codex)

Get a second opinion from Claude Code while working in Codex. Cross-check reasoning, validate plans, or get an independent code review from Claude.

$softnano:claude <task or question>

What it does:

Reads relevant files to build context
Constructs an unbiased prompt (no leading conclusions)
Runs Claude in non-interactive mode via claude -p
Uses read-only Claude tools by default (Read, Grep, Glob, LS)
Reports the Claude response and notes agreements/disagreements

`/softnano:thermo-nuclear-code-quality-review`

An extremely strict maintainability review focused on abstraction quality, giant files, and spaghetti-condition growth. Adapted from Cursor.

What it does:

Performs a deep code-quality audit of the current branch's changes
Hunts for "code judo" moves — restructurings that preserve behavior while making the implementation dramatically simpler
Flags PRs that push files past 1000 lines, add ad-hoc branching to unrelated flows, leak feature logic into shared paths, or introduce unnecessary wrappers / casts / optionality
Prefers deleting complexity over rearranging it; pushes for canonical helpers and explicit type boundaries
Prioritizes a small number of high-conviction structural findings over cosmetic nits

`/softnano:edison`

Conduct scientific literature research using Edison's autonomous search API. Edison searches hundreds of papers with full-text analysis and returns a cited answer.

/softnano:edison <research question>

What it does:

Submits the research question to Edison's literature search API
Waits for the result (typically 1–5 minutes)
Reports the cited answer verbatim

Supports follow-up queries via --continue-from <task_id> to build on previous searches.

Prerequisites: EDISON_PLATFORM_API_KEY in the agent environment, and jq installed. Claude Code users can set it in ~/.claude/settings.json under "env"; Codex users can set it in their shell or project environment.

`/softnano:doi2bib`

Fetch a BibTeX entry for a given DOI via doi.org content negotiation.

/softnano:doi2bib <doi>

What it does:

Accepts a bare DOI or full https://doi.org/... URL
Runs curl -LH "Accept: text/bibliography; style=bibtex" https://doi.org/<DOI>
Returns the BibTeX entry verbatim in a code block, ready to paste into a .bib file

`/softnano:grill-me`

Stress-test a plan or design by having the agent interview you relentlessly, walking every branch of the decision tree until there's shared understanding.

/softnano:grill-me

What it does:

Asks one focused question at a time
Recommends an answer for each question
Resolves dependencies between decisions before moving on
Explores the codebase itself when a question is answerable that way

`/softnano:open-pr`

Open a GitHub pull request with an auto-generated, deeply-reviewed summary.

/softnano:open-pr [base-branch] [--draft]

What it does:

Fetches origin/<base-branch> (default main) and diffs against it
Runs pre-commit and pytest as the quality gate — never on a login node; uses cluster-instructions to submit a job when on HPC
Spawns 1–2 review subagents in parallel, each with a distinct lens (correctness, API, tests, security, performance)
Composes a PR body containing the change summary, gate results, verbatim reviewer notes, and a test plan
Pushes the branch and opens the PR via gh pr create, returning the URL

Refuses to open the PR if the gate fails or the diff is empty. Uses --draft automatically if any reviewer flags a blocker.

`/softnano:polish-pr`

Follow-up pass on an open PR: address Codex review comments, re-run the thermo-nuclear review, sync with the base branch, and push the updates.

/softnano:polish-pr [pr-number] [--base <branch>] [--no-rebase]

What it does:

Resolves the PR for the current branch (or the given number) and pulls open review threads via the GitHub GraphQL API
For each unresolved Codex thread: reads the code, applies a minimal fix, replies on the thread, and marks it resolved
Re-runs /softnano:thermo-nuclear-code-quality-review against the resulting diff and addresses blocker/should-fix findings
Fetches the base branch and rebases (or merges, if requested) when new commits have landed
Pushes the updated branch (--force-with-lease only when a rebase rewrote history) and reports what was resolved, skipped, or escalated

Never auto-resolves human reviewer threads, never force-pushes without --force-with-lease, and stops on rebase conflicts so the user can resolve them.

`/softnano:cleanup`

Post-merge teardown for a feature branch and its worktree.

/softnano:cleanup [pr-number]

What it does:

Verifies via gh pr view that the PR is actually MERGED — refuses otherwise
Deletes the remote feature branch (no-ops if GitHub already auto-deleted it; skipped for fork PRs)
Removes the current git worktree using ExitWorktree (or git worktree remove from the main worktree as a fallback) — never rm -rf
Safely deletes the local feature branch (-d; falls back to -D only after confirming the PR is merged, e.g. squash-merge cases)
Fast-forwards main in the main worktree and reports what was deleted

Refuses to delete main, refuses to operate on a dirty worktree without confirmation, and refuses to force-delete a branch without a verified-merged PR backing it.

`/softnano:notion-upload`

Upload local image files to a Notion page. Uses the Notion File Upload REST API to embed PNGs, JPGs, and other images directly into a page.

/softnano:notion-upload <notion_page_url_or_id> <file_path(s) or glob pattern>

What it does:

Resolves file paths (supports glob patterns like figures/*.png)
Uploads each image via the Notion File Upload API (3-step process)
Appends all images as blocks to the Notion page with auto-generated captions
Reports upload results and any failures

Prerequisites: NOTION_API_TOKEN in your project .env file or as an environment variable. Create an integration at https://www.notion.so/profile/integrations and share the target page with it.

Reference Docs

Project Structure

softnano-plugins/
├── .claude-plugin/
│   ├── plugin.json          # Claude Code plugin manifest
│   └── marketplace.json     # Claude Code marketplace manifest
├── .agents/plugins/
│   └── marketplace.json     # Codex marketplace manifest
├── skills/                  # Claude Code skill tree
│   ├── codex/SKILL.md       # Claude Code cross-agent helper
│   ├── monitor-jobs/SKILL.md
│   ├── thermo-nuclear-code-quality-review/SKILL.md
│   ├── edison/
│   │   ├── SKILL.md
│   │   └── scripts/edison_query.sh
│   ├── cluster-instructions/
│   │   ├── SKILL.md
│   │   ├── cx3.md
│   │   ├── isambard.md
│   │   ├── mmm-sge.md
│   │   └── mmm-slurm.md
│   ├── doi2bib/SKILL.md
│   ├── grill-me/SKILL.md
│   ├── cleanup/SKILL.md
│   ├── notion-upload/SKILL.md
│   ├── open-pr/SKILL.md
│   ├── polish-pr/SKILL.md
│   └── submit-wandb-job/SKILL.md
├── plugins/
│   └── softnano/            # Codex plugin root referenced by marketplace.json
│       ├── .codex-plugin/plugin.json
│       └── skills/          # Codex skill tree; uses claude/ instead of codex/
├── scripts/
│   ├── check-codex-skill-sync.sh
│   ├── check-codex-plugin.py
│   └── sync-codex-skills.sh
├── AGENTS.md -> CLAUDE.md
└── .gitignore

Adding New Skills

Create skills/<skill-name>/SKILL.md with frontmatter:

---
name: my-skill
description: What the skill does
argument-hint: "<expected arguments>"
allowed-tools: Bash, Read, Grep, Glob, Write
---

Omit argument-hint if the skill takes no arguments (see grill-me). Then run scripts/sync-codex-skills.sh, bump version in .claude-plugin/plugin.json and plugins/softnano/.codex-plugin/plugin.json (keep them in sync), run scripts/check-codex-skill-sync.sh and python3 scripts/check-codex-plugin.py, and push. Keep the cross-agent helper intentionally split: root skills/codex/ is for Claude Code, while plugins/softnano/skills/claude/ is for Codex.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

softnano-plugins

Install

Claude Code

Codex

Skills

`/softnano:submit-wandb-job`

`/softnano:monitor-jobs`

`/softnano:cluster-instructions`

`/softnano:codex` (Claude Code)

`$softnano:claude` (Codex)

`/softnano:thermo-nuclear-code-quality-review`

`/softnano:edison`

`/softnano:doi2bib`

`/softnano:grill-me`

`/softnano:open-pr`

`/softnano:polish-pr`

`/softnano:cleanup`

`/softnano:notion-upload`

Reference Docs

Project Structure

Adding New Skills

About

Uh oh!

Releases 7

Packages

Uh oh!

Contributors

Uh oh!

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 33 Commits
.agents/plugins		.agents/plugins
.claude-plugin		.claude-plugin
.github/workflows		.github/workflows
plugins/softnano		plugins/softnano
scripts		scripts
skills		skills
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
README.md		README.md

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

softnano-plugins

Install

Claude Code

Codex

Skills

/softnano:submit-wandb-job

/softnano:monitor-jobs

/softnano:cluster-instructions

/softnano:codex (Claude Code)

$softnano:claude (Codex)

/softnano:thermo-nuclear-code-quality-review

/softnano:edison

/softnano:doi2bib

/softnano:grill-me

/softnano:open-pr

/softnano:polish-pr

/softnano:cleanup

/softnano:notion-upload

Reference Docs

Project Structure

Adding New Skills

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 7

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`/softnano:submit-wandb-job`

`/softnano:monitor-jobs`

`/softnano:cluster-instructions`

`/softnano:codex` (Claude Code)

`$softnano:claude` (Codex)

`/softnano:thermo-nuclear-code-quality-review`

`/softnano:edison`

`/softnano:doi2bib`

`/softnano:grill-me`

`/softnano:open-pr`

`/softnano:polish-pr`

`/softnano:cleanup`

`/softnano:notion-upload`

Packages