Skills for Digital Research Alliance

Shared AI coding setup for the lab. It teaches Claude Code and/or Codex about our Slurm clusters, storage rules, login-node safety, experiment conventions, and reusable HPC workflows.

Recommended Setup

Run the tool you want to use at least once

• Claude Code: run claude and log in with /login
• Codex: run codex and log in

Clone this repo:

git clone https://github.com/ATATC/DRA-config ~/DRA-config

Open Claude Code or Codex and say:

Read ~/DRA-config/README.md and install the lab config for me.
Configure Claude Code, Codex, or both depending on what is available.

The assistant should inspect this repo, detect the Alliance cluster (e.g. Fir), write saved setup values, and run setup.sh.

Manual Setup

Use this if you want to run the installer yourself:

cd ~/DRA-config

# Claude Code only (default)
./setup.sh --modules fir --targets claude

# Codex only
./setup.sh --modules fir --targets codex

# Both
./setup.sh --modules fir --targets codex,claude

If you are on a cluster login node, setup.sh can usually auto-detect modules. Use --modules when you want to be explicit.

What Gets Installed

Target	Installed config	Reusable workflows
Claude Code	~/.claude/CLAUDE.md, generated settings.json, statusline, hooks	~/.claude/skills/*, ~/.claude/agents/*
Codex	~/.codex/AGENTS.md	~/.codex/skills/*

Shared workflows include:

• ccdb-clusters - Alliance-wide cluster mechanics, storage, billing, Python install guidance, and fair-share helper scripts.
• onboard - interactive setup helper.
• slurm-status - check GPU/resource availability.
• slurm-job - create or modify sbatch scripts.
• slurm-seff-report - retrofit a job script to emit an inline cgroup CPU/memory snapshot; final seff after job exit remains authoritative.
• slurm-debug - diagnose failed, killed, or pending jobs.
• submit-experiment - submit documented Slurm experiments.
• harvest - collect completed experiment results.
• connect - establish/verify key-based SSH access to the cluster (one-time key upload done by onboard).
• slurm-queue, slurm-resource, slurm-storage - Claude agents converted into Codex skills where needed.

Claude supports hooks/statusline directly. Codex does not, so login-node safety and tool usage rules are injected into AGENTS.md instead.

Updating

cd ~/DRA-config
git pull
./setup.sh --targets <same-targets-you-installed>

For example, use --targets claude for Claude Code only, --targets codex for Codex only, or --targets claude,codex if both tools are initialized. Or ask Claude Code/Codex to read this README and update the lab config for you.

Uninstalling

cd ~/DRA-config
./uninstall.sh

This removes repo-owned symlinks and strips the managed lab block from ~/.claude/CLAUDE.md and ~/.codex/AGENTS.md. Personal content outside the markers is preserved. Backups are kept under ~/.claude/backups/ and ~/.codex/backups/.

Source Layout

The repo uses a core-plus-adapter design:

shared/instructions/core.md      # Lab facts shared by Claude Code and Codex
shared/instructions/claude.md    # Claude-specific commands, hooks, agents
shared/instructions/codex.md     # Codex-specific AGENTS.md and skill guidance

modules/<cluster>/instructions/core.md
modules/<cluster>/instructions/claude.md
modules/<cluster>/instructions/codex.md

shared/skills/                   # Shared skills
shared/codex/skills/             # Codex-only skill adapters
shared/agents/                   # Claude agents, converted to Codex skills
shared/hooks/                    # Claude-only hooks
shared/settings.json             # Claude-only settings template

Why this shape:

• Shared cluster/storage policy lives once, so Claude and Codex do not drift.
• Tool-specific behavior stays in small adapter files.
• The installer is slightly more compositional, but future tools can be added without duplicating all lab policy.

Skill Authoring

Skills in this repo follow the Agent Skills conventions below. Apply them when adding or editing a skill (most map directly to the issues this bundle was hardened against):

• Progressive disclosure. Keep SKILL.md lean — only the key path. The name + description (~100 words) is always in context; the body loads when the skill triggers; put heavy reference material (tables, long examples) in references/ and executable logic in scripts/. Reference bundled scripts via ${CLAUDE_SKILL_DIR}/scripts/..., never relative paths.
• description = what + when. Third person, stating both what the skill does and the trigger conditions/keywords a user would say. Claude tends to under-trigger — be explicit about when to use it.
• Single responsibility. One skill, one job; keep the body well under 500 lines (split if it grows). Prefer several small skills over one giant one.
• allowed-tools matches the body. Grant exactly the commands the skill runs, in space-pattern syntax (Bash(sbatch *), not Bash(sbatch:*)); no over-broad grants.
• Single source of truth, not prose. State-tracking workflows (e.g. submit-experiment, harvest) keep a structured file (metadata.yaml) as the SSOT and derive human-readable views from it — never parse markdown for state.
• Fail loud. Helper scripts exit non-zero with a clear message on real errors; never emit empty/partial output that silently breaks a downstream command.
• Test before shipping. Validate a new or changed skill in a fresh session (ideally via a subagent) against a couple of realistic prompts before relying on it.

References

• Anthropic (official): Agent Skills docs · anthropics/skills (incl. skill-creator)
• Community: mattpocock/skills (write-a-skill) · obra/superpowers (writing-skills)

Contributing

Common changes:

• New cluster: add modules/<name>/instructions/core.md, optional claude.md / codex.md, and optional skill templates.
• New reusable workflow: add it under shared/skills/.
• Claude-only automation: use shared/hooks/, shared/agents/, or shared/settings.json.
• Codex-only adaptation: use shared/codex/.

Keep durable lab facts in core.md; keep tool syntax in the adapter files.