agentleFS
ZimoLiaoZimoLiao/scholaraio/.claude/skills/scientific-runtime/SKILL.md

scientific-runtime

Skill585 starsChanged 3 months agoMITView on GitHub

Use when serving scientific CLI tasks through ScholarAIO, especially when the agent should prefer scholaraio toolref, handle partial coverage safely, or avoid turning user work into documentation maintenance.

The file

Show its rules and text

We split this skill into the rules it gives an agent

16 rules. About 0 are common, 12 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈12

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use it alongside a tool-specific scientific skill such as:

    line 13
  2. Distinctive:

    Use the tool-specific skill for workflow and scientific norms.

    line 44
  3. Very specific:

    Use toolref first for commands, parameters, program pages, and option meanings.

    line 45
  4. Very specific:

    If toolref is sufficient, continue normally.

    line 46
  5. Very specific:

    If toolref is partial, fall back to official docs and continue the task.

    line 47
  6. Distinctive:

    Do not turn the current user task into documentation maintenance work.

    line 49
  7. Distinctive:

    Before writing configuration or scripts, first resolve:

    line 72
  8. Very specific:

    If toolref does not fully answer the question:

    line 80
  9. Distinctive:

    do not ask the user to stop and repair the docs layer first

    line 84
  10. Distinctive:

    do not expose internal refactor details unless they materially affect current behavior

    line 85
  11. Distinctive:

    If it is a one-off edge case, do not derail the user task.

    line 100
  12. Distinctive:

    When code changes are involved:

    line 108
  13. Distinctive:

    treat package-internal reorganizations as an implementation detail

    line 111
  14. Distinctive:

    if a refactor changes behavior visible through CLI or top-level imports, treat that as a regression until proven otherwise

    line 112
  15. Distinctive:

    When answering the user:

    line 126
  16. Distinctive:

    keep maintenance details short

    line 128

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Scientific Runtime Protocol

This is a shared runtime skill for scientific CLI work.

It is not a tool manual. It tells the agent how to behave when serving real users on scientific tool tasks.

Use it alongside a tool-specific scientific skill such as:

  • quantum-espresso
  • lammps
  • gromacs
  • openfoam
  • bioinformatics

Core Principle

ScholarAIO is for users, not for people who want to co-maintain the internal documentation layer.

So the agent should absorb complexity whenever possible.

The user should experience:

  • natural language help
  • reliable parameter lookup
  • graceful fallback when coverage is partial

The user should not experience:

  • being asked to manually patch toolref
  • being forced to learn internal parser gaps
  • being blocked because a documentation layer is imperfect

Runtime Protocol

For any scientific CLI task:

  1. Identify the scientific tool or sub-tool that matches the problem.
  2. Use the tool-specific skill for workflow and scientific norms.
  3. Use toolref first for commands, parameters, program pages, and option meanings.
  4. If toolref is sufficient, continue normally.
  5. If toolref is partial, fall back to official docs and continue the task.
  6. Mention the coverage gap briefly only when it affects confidence or maintainability.
  7. Do not turn the current user task into documentation maintenance work.

Toolref-First Behavior

The agent should prefer:

  • scholaraio toolref show <tool> ... for precise lookups
  • scholaraio toolref search <tool> "..." for natural-language entry

The stable public surfaces are:

  • the scholaraio toolref ... CLI
  • the top-level scholaraio.stores.toolref package facade

The agent should not route users through internal implementation modules such as:

  • scholaraio.stores.toolref.fetch
  • scholaraio.stores.toolref.manifest
  • scholaraio.stores.toolref.storage
  • scholaraio.stores.toolref.search

Those internal module boundaries may change during refactors. User-facing guidance should stay anchored to the CLI and the top-level package behavior.

Before writing configuration or scripts, first resolve:

  • which program or subcommand is relevant
  • which parameters are high-risk
  • which defaults or restrictions matter for validity

When Toolref Is Incomplete

If toolref does not fully answer the question:

  • continue using the official documentation source
  • clearly separate "task progress" from "maintenance opportunity"
  • do not ask the user to stop and repair the docs layer first
  • do not expose internal refactor details unless they materially affect current behavior

Use this pattern:

  • "I used toolref for the main entry point."
  • "For this deeper detail, I fell back to the official docs because current coverage is partial."

Escalation Rule

Escalate a gap to onboarding or maintenance only when:

  • the same gap appears repeatedly
  • it blocks a common task
  • it affects correctness, not just convenience

If it is a one-off edge case, do not derail the user task.

Separation Of Responsibilities

  • tool-specific skill: when to use the tool, workflow, scientific norms
  • toolref: interface and parameter reference
  • scientific runtime: how to behave under uncertainty or partial coverage

When code changes are involved:

  • preserve the public scholaraio.stores.toolref entry surface
  • treat package-internal reorganizations as an implementation detail
  • if a refactor changes behavior visible through CLI or top-level imports, treat that as a regression until proven otherwise

Anti-Patterns

Do not:

  • dump raw flags from memory
  • tell the user to "go improve toolref first"
  • confuse a successful CLI run with a valid scientific result
  • replace scientific judgment with parameter lookup alone
  • instruct the user to use internal module names as if they were the supported interface

Output Style

When answering the user:

  • keep maintenance details short
  • foreground scientific progress and decision-making
  • mention fallback only when it materially changes confidence or provenance

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.