Bundle portable skills for Deep Agents

[tdpham2]

Summary

Deep Agent skills currently require callers to provision backend files and configure every source, and checkpointed catalogs can hide later updates. This adds bundled chemgraph and pbs-hpc skills that are available automatically across local, state, store, and custom remote filesystem backends.

• Ship skill instructions, chemistry/CLI guidance, PBS facility references, and a job template in wheels and source distributions. Serve them through an immutable /chemgraph-skills/ route using importlib.resources.
• Expand the bundled Polaris reference with login/shared-node guidance, modules, proxy settings, queues, PBS/MPI examples, GPU affinity, MPS/MIG, storage, and monitoring. Keep deployment paths configurable and preserve ChemGraph execution boundaries.
• Discover sources in order: bundled → personal → project → explicit. Later matching names win. Add --[no-]deepagent-discover-skills and corresponding Python/TOML settings. Support both /workspace and /workspace/ composite route keys without mutating the caller's backend.
• Refresh metadata before each new turn, including reconstructed sessions and the default general-purpose child. Preserve pending action approvals, saved personal roots, shell path mappings, and legacy session fingerprints when discovery is disabled.
• Load sources independently: failures in optional sources produce warnings while other skills remain available. Backend filesystem boundaries remain enforced, and stale warnings clear after recovery.
• Reject unreadable required sources before the model call. Explicit state/store sources must contain files before each turn; existing empty filesystem directories remain valid. Custom backends retain their reported-error semantics.
• Let the standalone default prompt use attached chemistry tools while retaining the supervisor workspace worker's delegation role and caller-supplied prompts.

CLI example

chemgraph run --interactive --workflow deep_agent --deepagent-workspace .

Ask: “Read the chemgraph and pbs-hpc skills, then prepare a PBS script using dummy values and validate it with bash -n without submitting it.”

The skills guide documents source precedence, source initialization, diagnostics, and filesystem boundaries. Deep Agents uses read_file to load skills; file operations route by path, while execute uses the default backend's executor. Templates/helpers must be copied into that executor's filesystem before execution. Remote execution still requires an appropriate backend.

Related issues

None.

Type of change

• Bug fix
• New feature
• Docs
• Chore / refactor / CI

How was this tested?

• ruff check . — passed.
• git diff --check — passed.
• Focused skill, backend, distribution, Deep Agent, and CLI tests — 162 passed.
• pytest tests/ -k "not tblite" -q --tb=short — 1,195 passed, 21 skipped, 2 deselected, using Python 3.12 and the project's pinned dependencies.
• Regression coverage includes optional symlink/download failures and recovery, both workspace route spellings and precedence, missing/seeded/removed state/store sources through nested composites, real store-backed reads/writes and skill reads, and propagation of interrupts, cancellation, and programming errors.
• Existing coverage verifies immutable resources, wheel/sdist contents, extracted and zip-imported wheels, discovery refresh, child-agent access, CLI/TOML overrides, chemistry tool calls, and approval/session restoration.
• Polaris examples: all seven Bash blocks pass bash -n; local simulations verify GPU assignments for ranks 0–7, literal argument forwarding, MPI launch arguments with spaced paths, and missing-allocation failures.
• Skill frontmatter validation passed on a temporary copy excluding the existing compatibility field, which the generic validator does not recognize; the field remains unchanged in the bundled skill.
• No live LLM, Globus Compute endpoint, or HPC submission tests were enabled.

Checklist

• Branched off the latest main and targets main
• PR is focused on portable Deep Agent skills
• ruff check . passes
• pytest tests/ -k "not tblite" passes
• Added/updated tests for the change
• Updated docs / README for user-facing changes