Skip to content
Back to search

materials-simulation-skills

Agent Skills for computational materials science -- numerical stability, solvers, meshing, convergence, and simulation workflows.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/HeshamFS/materials-simulation-skills with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/HeshamFS/materials-simulation-skills'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/heshamfs--materials-simulation-skills/badge.svg)](/listings/heshamfs--materials-simulation-skills)

HTML

<a href="/listings/heshamfs--materials-simulation-skills"><img src="/api/listings/heshamfs--materials-simulation-skills/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

The repo follows the open standard, so the ecosystem installers work out of the box:

npx skills add HeshamFS/materials-simulation-skills          # any agent → ~/.agents/skills/
gh skill install HeshamFS/materials-simulation-skills --pin v1.0.0   # version-pinned

Or install a curated **bundle** into a specific agent with the bundled `mss` CLI:

mss bundles                                                  # list bundles
mss install --agent claude --bundle verification-and-validation

Claude Code users can also `/plugin marketplace add HeshamFS/materials-simulation-skills`. Full per-agent guide → **[docs/INSTALL.md](docs/INSTALL.md)**.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 161 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "$schema": "https://json.schemastore.org/claude-code-marketplace.json",
  3. "name": "materials-simulation-skills",
  4. "description": "Validated, agent-agnostic Agent Skills for computational materials science and numerical simulation.",
  5. "owner": {
  6. "name": "Hesham Salama",
  7. "url": "https://github.com/HeshamFS"
  8. },
  9. "metadata": {
  10. "version": "1.0.0"
  11. },
  12. "plugins": [
  13. {
  14. "name": "core-numerical",
  15. "description": "All core numerical skills.",
  16. "source": "./",
  17. "strict": false,
  18. "skills": [
  19. "./skills/core-numerical/convergence-study",
  20. "./skills/core-numerical/differentiation-schemes",
  21. "./skills/core-numerical/linear-solvers",
  22. "./skills/core-numerical/mesh-generation",
  23. "./skills/core-numerical/nonlinear-solvers",
  24. "./skills/core-numerical/numerical-integration",
  25. "./skills/core-numerical/numerical-stability",
  26. "./skills/core-numerical/time-stepping"
  27. ]
  28. },
  29. {
  30. "name": "data-management",
  31. "description": "All data management skills.",
  32. "source": "./",
  33. "strict": false,
  34. "skills": [
  35. "./skills/data-management/fair-simulation-packager"
  36. ]
  37. },
  38. {
  39. "name": "hpc-deployment",
  40. "description": "All hpc deployment skills.",
  41. "source": "./",
  42. "strict": false,
  43. "skills": [
  44. "./skills/hpc-deployment/hpc-runtime-doctor",
  45. "./skills/hpc-deployment/slurm-job-script-generator"
  46. ]
  47. },
  48. {
  49. "name": "meta",
  50. "description": "All meta skills.",
  51. "source": "./",
  52. "strict": false,
  53. "skills": [
  54. "./skills/meta/skill-evaluator"
  55. ]
  56. },
  57. {
  58. "name": "ontology",
  59. "description": "All ontology skills.",
  60. "source": "./",
  61. "strict": false,
  62. "skills": [
  63. "./skills/ontology/ontology-explorer",
  64. "./skills/ontology/ontology-mapper",
  65. "./skills/ontology/ontology-validator"
  66. ]
  67. },
  68. {
  69. "name": "robustness",
  70. "description": "All robustness skills.",
  71. "source": "./",
  72. "strict": false,
  73. "skills": [
  74. "./skills/robustness/simulation-failure-triage"
  75. ]
  76. },
  77. {
  78. "name": "simulation-workflow",
  79. "description": "All simulation workflow skills.",
  80. "source": "./",
  81. "strict": false,
  82. "skills": [
  83. "./skills/simulation-workflow/md-analysis-planner",
  84. "./skills/simulation-workflow/parameter-optimization",
  85. "./skills/simulation-workflow/performance-profiling",
  86. "./skills/simulation-workflow/post-processing",
  87. "./skills/simulation-workflow/simulation-orchestrator",
  88. "./skills/simulation-workflow/simulation-validator",
  89. "./skills/simulation-workflow/workflow-engine-mapper"
  90. ]
  91. },
  92. {
  93. "name": "verification-validation",
  94. "description": "All verification validation skills.",
  95. "source": "./",
  96. "strict": false,
  97. "skills": [
  98. "./skills/verification-validation/benchmark-and-mms-planner"
  99. ]
  100. },
  101. {
  102. "name": "reproducible-campaigns",
  103. "description": "Plan, run, diagnose, and FAIR-package multi-run simulation campaigns across HPC.",
  104. "source": "./",
  105. "strict": false,
  106. "skills": [
  107. "./skills/simulation-workflow/parameter-optimization",
  108. "./skills/simulation-workflow/simulation-orchestrator",
  109. "./skills/simulation-workflow/performance-profiling",
  110. "./skills/hpc-deployment/slurm-job-script-generator",
  111. "./skills/hpc-deployment/hpc-runtime-doctor",
  112. "./skills/robustness/simulation-failure-triage",
  113. "./skills/data-management/fair-simulation-packager",
  114. "./skills/simulation-workflow/workflow-engine-mapper"
  115. ]
  116. },
  117. {
  118. "name": "verification-and-validation",
  119. "description": "Prove a result is trustworthy: stability, convergence, manufactured solutions, and pre/post-flight validation.",
  120. "source": "./",
  121. "strict": false,
  122. "skills": [
  123. "./skills/core-numerical/numerical-stability",
  124. "./skills/core-numerical/convergence-study",
  125. "./skills/verification-validation/benchmark-and-mms-planner",
  126. "./skills/simulation-workflow/simulation-validator"
  127. ]
  128. },
  129. {
  130. "name": "full",
  131. "description": "Every materials-simulation domain skill.",
  132. "source": "./",
  133. "strict": false,
  134. "skills": [
  135. "./skills/verification-validation/benchmark-and-mms-planner",
  136. "./skills/core-numerical/convergence-study",
  137. "./skills/core-numerical/differentiation-schemes",
  138. "./skills/data-management/fair-simulation-packager",
  139. "./skills/hpc-deployment/hpc-runtime-doctor",
  140. "./skills/core-numerical/linear-solvers",
  141. "./skills/simulation-workflow/md-analysis-planner",
  142. "./skills/core-numerical/mesh-generation",
  143. "./skills/core-numerical/nonlinear-solvers",
  144. "./skills/core-numerical/numerical-integration",
  145. "./skills/core-numerical/numerical-stability",
  146. "./skills/ontology/ontology-explorer",
  147. "./skills/ontology/ontology-mapper",
  148. "./skills/ontology/ontology-validator",
  149. "./skills/simulation-workflow/parameter-optimization",
  150. "./skills/simulation-workflow/performance-profiling",
  151. "./skills/simulation-workflow/post-processing",
  152. "./skills/robustness/simulation-failure-triage",
  153. "./skills/simulation-workflow/simulation-orchestrator",
  154. "./skills/simulation-workflow/simulation-validator",
  155. "./skills/hpc-deployment/slurm-job-script-generator",
  156. "./skills/core-numerical/time-stepping",
  157. "./skills/simulation-workflow/workflow-engine-mapper"
  158. ]
  159. }
  160. ]
  161. }
README.md · README · 175 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Materials Simulation Skills
  2. [![CI](https://github.com/HeshamFS/materials-simulation-skills/actions/workflows/ci.yml/badge.svg)](https://github.com/HeshamFS/materials-simulation-skills/actions/workflows/ci.yml)
  3. [![PyPI](https://img.shields.io/pypi/v/materials-simulation-skills.svg)](https://pypi.org/project/materials-simulation-skills/)
  4. [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
  5. [![Python 3.10-3.12](https://img.shields.io/badge/Python-3.10--3.12-blue.svg)](https://www.python.org/)
  6. [![Agent Skills](https://img.shields.io/badge/Agent_Skills-standard-orange.svg)](https://agentskills.io)
  7. **Give your AI coding agent real expertise in numerical methods, simulation best practices, and computational materials science, so it stops guessing.**
  8. ```text
  9. You: Check if dt=0.001 is stable for my advection problem with v=2.0 m/s and dx=0.01.
  10. Agent: I'll use the numerical-stability skill to check this.
  11. [runs cfl_checker.py --dx 0.01 --dt 0.001 --velocity 2.0 --json]
  12. CFL number = 0.2 (limit: 1.0) -- stable.
  13. Recommended max dt = 0.005 with safety factor 1.0.
  14. ```
  15. **24 skills** cover numerical methods, simulation workflows, HPC deployment, verification and validation, FAIR data, robustness, and materials ontologies. They follow the open [Agent Skills standard](https://agentskills.io) and work in **20+ tools**, including Claude Code, Codex, Cursor, Antigravity and GitHub Copilot.
  16. ---
  17. ## How it works
  18. ```mermaid
  19. flowchart LR
  20. A["You ask a<br/>simulation question"] --> B["The agent picks<br/>the matching skill"]
  21. B --> C["The skill's script runs<br/>with your numbers"]
  22. C --> D["The agent explains<br/>the checked result"]
  23. ```
  24. A skill is a folder of instructions plus small, tested scripts. Your agent finds it on its own and loads it only when a question needs it, so there is nothing to wire up and no prompt to write.
  25. ---
  26. ## Quick start
  27. ### 1. Install
  28. ```bash
  29. npx skills add HeshamFS/materials-simulation-skills
  30. ```
  31. <details>
  32. <summary>Other ways to install</summary>
  33. **Pinned to a release**
  34. ```bash
  35. gh skill install HeshamFS/materials-simulation-skills --pin v1.0.0
  36. ```
  37. **As a Claude Code plugin**
  38. ```text
  39. /plugin marketplace add HeshamFS/materials-simulation-skills
  40. ```
  41. **A curated bundle into one agent, with the `mss` CLI**
  42. ```bash
  43. pip install materials-simulation-skills
  44. mss bundles # list bundles
  45. mss install --agent claude --bundle verification-and-validation
  46. ```
  47. The per-agent guide is in **[docs/INSTALL.md](docs/INSTALL.md)**.
  48. </details>
  49. ### 2. Ask your agent
  50. Describe the task in your own words. The agent picks the skill:
  51. ```text
  52. Is dt=0.001 stable for advection with v=2.0 m/s and dx=0.01?
  53. ```
  54. ```text
  55. My GMRES solve stalls. Which preconditioner should I try?
  56. ```
  57. You can also name a skill:
  58. ```text
  59. Use convergence-study to check if my mesh is in the asymptotic range:
  60. h = 0.4, 0.2, 0.1 gave stress = 98.5, 99.6, 99.9 MPa.
  61. ```
  62. ### 3. Check the result
  63. The agent runs the skill's script with your numbers and explains the output, as in the example at the top. Every script also runs by hand, so you can check any answer yourself:
  64. ```bash
  65. pip install materials-simulation-skills
  66. mss list # list skills
  67. mss run numerical-stability cfl_checker -- --dx 0.01 --dt 0.001 --velocity 2.0 --json
  68. ```
  69. ---
  70. ## What's inside
  71. **24 skills** in 8 categories. The full catalog is in **[docs/SKILLS.md](docs/SKILLS.md)**, and in machine-readable form in [`skills_index.json`](skills_index.json).
  72. | Category | Skills | Focus |
  73. |---|---|---|
  74. | Core Numerical | 8 | stability, time-stepping, meshing, convergence, integration, differentiation, linear/nonlinear solvers |
  75. | Simulation Workflow | 7 | validation, DOE/optimization, orchestration, post-processing, profiling, workflow mapping, MD analysis |
  76. | Ontology | 3 | CMSO/ASMO exploration, mapping, validation |
  77. | HPC Deployment | 2 | SLURM script generation, runtime diagnosis |
  78. | Verification & Validation | 1 | manufactured solutions, benchmarks, pass/fail reports |
  79. | Data Management | 1 | FAIR reproducibility packaging |
  80. | Robustness | 1 | cross-code failure triage and retry ladders |
  81. | Meta | 1 | `skill-evaluator`: evaluate any skill across any agent CLI |
  82. ---
  83. ## How it's tested
  84. - **Scripts are tested.** Unit, integration, analytic-oracle and negative-control tests run in CI on Python 3.10 to 3.12 across Linux, macOS and Windows.
  85. - **Documented numbers are checked.** Every eval case runs its script and asserts the exact output, so the docs cannot drift from the code. Latest run ([2026-10-20](docs/evaluations/2026-10-20.md)): 115 cases, 131 checks, 725 assertions passed.
  86. - **Rules cite their source**, such as ASME V&V20, the SchedMD `sbatch` spec and CMSO IRIs.
  87. - **Not yet shown:** that a live agent gives better scientific answers with these skills than without them. The harness to measure it exists, and the work is tracked in [#13](https://github.com/HeshamFS/materials-simulation-skills/issues/13).
  88. Read **[validation scope and remaining limits](docs/VALIDATION_SCOPE.md)** before treating a passing check as evidence about a physical simulation. Method and harness: [evaluation methodology](docs/EVALUATION_METHODOLOGY.md) · [eval harness](docs/EVAL_HARNESS.md).
  89. ---
  90. ## Contributing
  91. Contributions are welcome: a new skill, a fix, docs, or just an idea.
  92. - **Looking for something to pick up?** See the [roadmap issues](https://github.com/HeshamFS/materials-simulation-skills/issues?q=is%3Aissue+is%3Aopen+label%3Aroadmap) and the [good first issues](https://github.com/HeshamFS/materials-simulation-skills/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).
  93. - **Have an idea or a skill to propose?** Open an [issue](https://github.com/HeshamFS/materials-simulation-skills/issues/new/choose). Early ideas are useful even without code.
  94. - **Want to build a skill?** **[CONTRIBUTING.md](CONTRIBUTING.md)** has a step-by-step guide with script and test templates. A skill ships a tested script plus an eval case with a deterministic `script_check`, and passes `mss validate` and `mss eval`.
  95. - **Where it's headed:** **[ROADMAP.md](ROADMAP.md)**.
  96. To work on the repository itself:
  97. ```bash
  98. git clone https://github.com/HeshamFS/materials-simulation-skills.git
  99. cd materials-simulation-skills && pip install -e ".[dev]"
  100. mss eval # run the deterministic eval gate
  101. python -m pytest tests/ # full test suite
  102. ```
  103. ---
  104. ## Documentation
  105. | Doc | What's in it |
  106. |---|---|
  107. | [docs/SKILLS.md](docs/SKILLS.md) | Full skill catalog, how skills work, repo layout |
  108. | [docs/INSTALL.md](docs/INSTALL.md) | Install for every supported agent |
  109. | [docs/EVALUATION_METHODOLOGY.md](docs/EVALUATION_METHODOLOGY.md) | How skills are evaluated, with results |
  110. | [docs/EVAL_HARNESS.md](docs/EVAL_HARNESS.md) | The three-layer evaluation harness |
  111. | [docs/PROTOCOL.md](docs/PROTOCOL.md) | The Materials Simulation Skill Protocol |
  112. | [docs/SECURITY.md](docs/SECURITY.md) | Safeguards and security tiers |
  113. | [CONTRIBUTING.md](CONTRIBUTING.md) · [ROADMAP.md](ROADMAP.md) | Contributing guide · direction |
  114. ---
  115. ## License
  116. [Apache 2.0](LICENSE)
  117. ## Acknowledgements
  118. - [Agent Skills standard](https://agentskills.io): open specification for portable agent capabilities
  119. - [Anthropic](https://anthropic.com): original developer of the Agent Skills format
  120. - [agentskills/agentskills](https://github.com/agentskills/agentskills): reference implementation and validation library
skills/meta/skill-evaluator/scripts/agent_adapters.py · Bundled script · 404 lines · 5 findings marked
  1. #!/usr/bin/env python3
  2. """Pluggable per-CLI adapters for driving coding agents in headless mode.
  3. The skill-evaluator harness is *agent-agnostic*: the same Agent Skill is portable
  4. across many coding-agent CLIs, so the evaluator that exercises a skill must be too.
  5. This module encodes, for each supported CLI, exactly how to (a) run one prompt
  6. non-interactively, (b) request structured output, (c) auto-approve tool use so the
  7. run does not hang on a permission prompt, and (d) where to drop a skill so the CLI
  8. discovers it (and how to run a clean no-skill baseline).
  9. Every fact here was researched official-docs-first and independently cross-checked
  10. (June 2026). See ``references/adapters.md`` for sources, confidence, and caveats.
  11. CLIs and their flags evolve; each adapter carries a ``confidence`` and the harness
  12. supports ``--dry-run`` so you can print and verify the exact command before running.
  13. This file is data + pure helpers + a small CLI (``--list`` / ``--show`` / ``--build``),
  14. with no third-party dependencies, so the skill stays self-contained and portable.
  15. """
  16. from __future__ import annotations
  17. import argparse
  18. import json
  19. import shlex
  20. import sys
  21. from typing import Any
  22. # ---------------------------------------------------------------------------
  23. # Adapter registry. Each entry is pure data so it serializes to JSON for
  24. # inspection; build_argv() turns it into a concrete command.
  25. #
  26. # invocation spec fields:
  27. # subcommands tokens between the binary and the flags (e.g. codex `exec`)
  28. # prompt_flag flag that carries the prompt, or None for a trailing positional
  29. # json_flags flags that request machine-readable output ([] = plain text)
  30. # model_flag flag to select the model (model value supplied at call time)
  31. # bypass_flags flags that auto-approve tool use in headless mode (CRITICAL:
  32. # without these the run blocks on an interactive approval prompt)
  33. # workdir_flag flag to point the agent at a working directory, or None
  34. # workdir_via_cwd if True, the runner sets the process cwd instead of a flag
  35. # extra_flags flags always added (quiet/no-color/skip-checks/etc.)
  36. # baseline_extra flags added ONLY for the no-skill baseline run
  37. # result_kind how to read the agent's answer from stdout:
  38. # "json:<dotted.path>" parse one JSON doc, take that field
  39. # "jsonl-last" parse JSONL, take last assistant text
  40. # "raw" stdout is the answer (plain text)
  41. # ---------------------------------------------------------------------------
  42. ADAPTERS: dict[str, dict[str, Any]] = {
  43. "claude-code": {
  44. "display_name": "Claude Code",
  45. "binary": "claude",
  46. "auth_env": ["ANTHROPIC_API_KEY", "CLAUDE_CODE_OAUTH_TOKEN"],
  47. "skills_project_subdir": ".claude/skills",
  48. "skills_personal_dir": "~/.claude/skills",
  49. "install": "curl -fsSL https://claude.ai/install.sh | bash (or: npm i -g @anthropic-ai/claude-code)",
  50. "default_model": None,
  51. "confidence": "high",
  52. "invocation": {
  53. "subcommands": [],
  54. "prompt_flag": "-p",
  55. "json_flags": ["--output-format", "json"],
  56. "model_flag": "--model",
  57. "bypass_flags": ["--dangerously-skip-permissions"],
  58. "workdir_flag": "--add-dir",
  59. "workdir_via_cwd": False,
  60. "extra_flags": [],
  61. "baseline_extra": ["--bare"], # --bare disables skill/CLAUDE.md/MCP auto-discovery
  62. "result_kind": "json:result",
  63. },
  64. "notes": "Baseline uses --bare to guarantee NO skills are auto-discovered. "
  65. "--bare needs ANTHROPIC_API_KEY (it ignores CLAUDE_CODE_OAUTH_TOKEN).",
  66. },
  67. "openai-codex": {
  68. "display_name": "OpenAI Codex CLI",
  69. "binary": "codex",
  70. "auth_env": ["OPENAI_API_KEY"],
  71. "skills_project_subdir": ".agents/skills",
  72. "skills_personal_dir": "~/.agents/skills",
  73. "install": "npm i -g @openai/codex (note the @openai scope)",
  74. "default_model": None,
  75. "confidence": "high",
  76. "invocation": {
  77. "subcommands": ["exec"],
  78. "prompt_flag": None, # prompt is the trailing positional
  79. "json_flags": ["--json"],
  80. "model_flag": "-m",
  81. "bypass_flags": ["--dangerously-bypass-approvals-and-sandbox"],
  82. "workdir_flag": "-C",
  83. "workdir_via_cwd": False,
  84. "extra_flags": ["--skip-git-repo-check"],
  85. "baseline_extra": [],
  86. "result_kind": "jsonl-last",
  87. },
  88. "notes": "`codex exec --json` streams JSONL events; the final agent message is "
  89. "the last event with assistant text. Workdir flag is -C/--cd (not --add-dir).",
  90. },
  91. "antigravity": {
  92. "display_name": "Google Antigravity CLI",
  93. "binary": "agy",
  94. "auth_env": ["ANTIGRAVITY_API_KEY"],
  95. "skills_project_subdir": ".agents/skills",
  96. "skills_personal_dir": "~/.agents/skills",
  97. "install": "curl -fsSL https://antigravity.google/cli/install.sh | bash (then: agy install)",
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 103 on GitHub
  98. "default_model": None,
  99. "confidence": "medium",
  100. "invocation": {
  101. "subcommands": [],
  102. "prompt_flag": "-p",
  103. "json_flags": [], # `agy -p` prints plain text; JSON via `agy run --output json`
  104. "model_flag": "--model",
  105. "bypass_flags": ["--dangerously-skip-permissions"],
  106. "workdir_flag": "--add-dir",
  107. "workdir_via_cwd": False,
  108. "extra_flags": ["--no-color"],
  109. "baseline_extra": [],
  110. "result_kind": "raw",
  111. },
  112. "notes": "Replaced the retired Gemini CLI on 2026-06-18. Skills use the .agents/ "
  113. "convention. For structured output the CI form is "
  114. "`agy run --prompt-file F --yes --no-color --output json`. Verify flags with "
  115. "`agy --help` for your version (medium confidence; CLI is new).",
  116. },
  117. "cursor-cli": {
  118. "display_name": "Cursor CLI",
  119. "binary": "cursor-agent",
  120. "auth_env": ["CURSOR_API_KEY"],
  121. "skills_project_subdir": ".cursor/skills",
  122. "skills_personal_dir": "~/.cursor/skills",
  123. "install": "curl https://cursor.com/install -fsS | bash",
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 129 on GitHub
  124. "default_model": None,
  125. "confidence": "high",
  126. "invocation": {
  127. "subcommands": [],
  128. "prompt_flag": "-p",
  129. "json_flags": ["--output-format", "json"],
  130. "model_flag": "--model",
  131. "bypass_flags": ["--force"],
  132. "workdir_flag": None,
  133. "workdir_via_cwd": True,
  134. "extra_flags": [],
  135. "baseline_extra": [],
  136. "result_kind": "json:result",
  137. },
  138. "notes": "Also auto-discovers .claude/skills and .agents/skills (compat). Runs in cwd.",
  139. },
  140. "github-copilot-cli": {
  141. "display_name": "GitHub Copilot CLI",
  142. "binary": "copilot",
  143. "auth_env": ["COPILOT_GITHUB_TOKEN", "GH_TOKEN", "GITHUB_TOKEN"],
  144. "skills_project_subdir": ".github/skills",
  145. "skills_personal_dir": "~/.copilot/skills",
  146. "install": "npm i -g @github/copilot (requires Node 22+)",
  147. "default_model": None,
  148. "confidence": "high",
  149. "invocation": {
  150. "subcommands": [],
  151. "prompt_flag": "-p",
  152. "json_flags": ["--output-format", "json"],
  153. "model_flag": "--model",
  154. "bypass_flags": ["--allow-all-tools"],
  155. "workdir_flag": "--add-dir",
  156. "workdir_via_cwd": False,
  157. "extra_flags": ["--no-ask-user", "--silent"],
  158. "baseline_extra": [],
  159. "result_kind": "jsonl-last",
  160. },
  161. "notes": "The new standalone agentic `copilot` (NOT `gh copilot`). --output-format json "
  162. "emits JSONL (one object per line). Also discovers .claude/skills, .agents/skills.",
  163. },
  164. "amp": {
  165. "display_name": "Sourcegraph Amp CLI",
  166. "binary": "amp",
  167. "auth_env": ["AMP_API_KEY"],
  168. "skills_project_subdir": ".agents/skills",
  169. "skills_personal_dir": "~/.config/agents/skills",
  170. "install": "curl -fsSL https://ampcode.com/install.sh | bash",
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 176 on GitHub
  171. "default_model": None,
  172. "confidence": "high",
  173. "invocation": {
  174. "subcommands": [],
  175. "prompt_flag": "-x",
  176. "json_flags": [], # one-shot -x prints text; --stream-json for events
  177. "model_flag": None,
  178. "bypass_flags": ["--dangerously-allow-all"],
  179. "workdir_flag": None,
  180. "workdir_via_cwd": True,
  181. "extra_flags": [],
  182. "baseline_extra": [],
  183. "result_kind": "raw",
  184. },
  185. "notes": "`amp -x \"<prompt>\"` is the execute/scripting mode. No model flag on the CLI. "
  186. "Discovers .agents/skills and .claude/skills.",
  187. },
  188. "opencode": {
  189. "display_name": "opencode",
  190. "binary": "opencode",
  191. "auth_env": ["ANTHROPIC_API_KEY", "OPENAI_API_KEY"],
  192. "skills_project_subdir": ".opencode/skills",
  193. "skills_personal_dir": "~/.config/opencode/skills",
  194. "install": "curl -fsSL https://opencode.ai/install | bash (the sst/opencode at opencode.ai)",
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 200 on GitHub
  195. "default_model": None,
  196. "confidence": "high",
  197. "invocation": {
  198. "subcommands": ["run"],
  199. "prompt_flag": None, # trailing positional
  200. "json_flags": ["--format", "json"],
  201. "model_flag": "-m",
  202. "bypass_flags": ["--dangerously-skip-permissions"],
  203. "workdir_flag": None,
  204. "workdir_via_cwd": True,
  205. "extra_flags": [],
  206. "baseline_extra": [],
  207. "result_kind": "raw",
  208. },
  209. "notes": "Model is provider/model, e.g. anthropic/claude-sonnet-4. --format json emits a "
  210. "stream of JSON events. Discovers .opencode/skills, .claude/skills, .agents/skills.",
  211. },
  212. "grok-cli": {
  213. "display_name": "Grok CLI (xAI, official)",
  214. "binary": "grok",
  215. "auth_env": ["XAI_API_KEY"],
  216. "skills_project_subdir": ".grok/skills",
  217. "skills_personal_dir": "~/.grok/skills",
  218. "install": "curl -fsSL https://x.ai/cli/install.sh | bash",
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 224 on GitHub
  219. "default_model": None,
  220. "confidence": "medium",
  221. "invocation": {
  222. "subcommands": [],
  223. "prompt_flag": "-p",
  224. "json_flags": ["--output-format", "json"],
  225. "model_flag": "--model",
  226. "bypass_flags": ["--always-approve"],
  227. "workdir_flag": "--cwd",
  228. "workdir_via_cwd": False,
  229. "extra_flags": ["--no-auto-update"],
  230. "baseline_extra": [],
  231. "result_kind": "raw",
  232. },
  233. "notes": "The OFFICIAL xAI CLI (docs.x.ai/build). A community CLI (superagent-ai/grok-cli, "
  234. "npm 'grok-dev') uses the SAME binary name `grok` but different flags — verify which "
  235. "you have. Also reads .claude/skills and ~/.claude/skills.",
  236. },
  237. }
  238. # Aliases so users can name a CLI loosely.
  239. ALIASES = {
  240. "claude": "claude-code", "claude-code": "claude-code",
  241. "codex": "openai-codex", "openai-codex": "openai-codex", "openai": "openai-codex",
  242. "agy": "antigravity", "antigravity": "antigravity", "antigravity-cli": "antigravity",
  243. "gemini": "antigravity", "gemini-cli": "antigravity", # Gemini CLI retired -> Antigravity
  244. "cursor": "cursor-cli", "cursor-agent": "cursor-cli", "cursor-cli": "cursor-cli",
  245. "copilot": "github-copilot-cli", "github-copilot": "github-copilot-cli",
  246. "github-copilot-cli": "github-copilot-cli", "gh-copilot": "github-copilot-cli",
  247. "amp": "amp", "sourcegraph-amp": "amp",
  248. "opencode": "opencode",
  249. "grok": "grok-cli", "grok-cli": "grok-cli", "xai": "grok-cli",
  250. }
  251. def resolve(cli: str) -> str:
  252. """Resolve a CLI name/alias to a canonical adapter id."""
  253. key = cli.strip().lower()
  254. if key in ALIASES:
  255. return ALIASES[key]
  256. raise KeyError(
  257. f"Unknown coding-agent CLI: {cli!r}. Known: {', '.join(sorted(ADAPTERS))}"
  258. )
  259. def get(cli: str) -> dict[str, Any]:
  260. return ADAPTERS[resolve(cli)]
  261. def build_argv(
  262. cli: str,
  263. prompt: str,
  264. workdir: str | None = None,
  265. model: str | None = None,
  266. with_skill: bool = True,
  267. ) -> list[str]:
  268. """Construct the concrete argv for one non-interactive run.
  269. The returned list is ready for subprocess (no shell). When the adapter uses
  270. ``workdir_via_cwd`` the workdir is NOT in argv — the runner must set cwd.
  271. """
  272. a = get(cli)
  273. inv = a["invocation"]
  274. argv: list[str] = [a["binary"], *inv["subcommands"]]
  275. argv += list(inv["json_flags"])
  276. if model and inv["model_flag"]:
  277. argv += [inv["model_flag"], model]
  278. argv += list(inv["bypass_flags"])
  279. if workdir and inv["workdir_flag"]:
  280. argv += [inv["workdir_flag"], workdir]
  281. argv += list(inv["extra_flags"])
  282. if not with_skill:
  283. argv += list(inv["baseline_extra"])
  284. if inv["prompt_flag"]:
  285. argv += [inv["prompt_flag"], prompt]
  286. else:
  287. argv += [prompt]
  288. return argv
  289. def command_string(argv: list[str]) -> str:
  290. """Shell-quoted, copy-pasteable command string (for display / dry-run)."""
  291. return " ".join(shlex.quote(tok) for tok in argv)
  292. def runs_in_cwd(cli: str) -> bool:
  293. return bool(get(cli)["invocation"]["workdir_via_cwd"])
  294. # --------------------------------------------------------------------------- CLI
  295. def _cmd_list(args: argparse.Namespace) -> int:
  296. rows = [
  297. {
  298. "id": cid,
  299. "display_name": a["display_name"],
  300. "binary": a["binary"],
  301. "skills_project_subdir": a["skills_project_subdir"],
  302. "auth_env": a["auth_env"],
  303. "confidence": a["confidence"],
  304. }
  305. for cid, a in ADAPTERS.items()
  306. ]
  307. if args.json:
  308. print(json.dumps({"adapters": rows}, indent=2))
  309. else:
  310. for r in rows:
  311. print(f"{r['id']:20s} {r['binary']:14s} skills={r['skills_project_subdir']:16s} "
  312. f"auth={r['auth_env'][0]:22s} conf={r['confidence']}")
  313. return 0
  314. def _cmd_show(args: argparse.Namespace) -> int:
  315. try:
  316. a = get(args.cli)
  317. except KeyError as exc:
  318. print(str(exc), file=sys.stderr)
  319. return 2
  320. if args.json:
  321. print(json.dumps({"id": resolve(args.cli), **a}, indent=2))
  322. else:
  323. print(json.dumps({"id": resolve(args.cli), **a}, indent=2))
  324. return 0
  325. def _cmd_build(args: argparse.Namespace) -> int:
  326. """Print the exact argv/command for a run (dry-run helper)."""
  327. try:
  328. argv = build_argv(
  329. args.cli, args.prompt, workdir=args.workdir, model=args.model,
  330. with_skill=not args.baseline,
  331. )
  332. except KeyError as exc:
  333. print(str(exc), file=sys.stderr)
  334. return 2
  335. payload = {
  336. "cli": resolve(args.cli),
  337. "argv": argv,
  338. "command": command_string(argv),
  339. "runs_in_cwd": runs_in_cwd(args.cli),
  340. "with_skill": not args.baseline,
  341. }
  342. if args.json:
  343. print(json.dumps(payload, indent=2))
  344. else:
  345. print(payload["command"])
  346. return 0
  347. def build_parser() -> argparse.ArgumentParser:
  348. p = argparse.ArgumentParser(description="Inspect and build coding-agent CLI adapter commands")
  349. sub = p.add_subparsers(dest="command", required=True)
  350. lp = sub.add_parser("list", help="List supported CLIs")
  351. lp.add_argument("--json", action="store_true")
  352. lp.set_defaults(func=_cmd_list)
  353. sp = sub.add_parser("show", help="Show one adapter's full spec")
  354. sp.add_argument("cli")
  355. sp.add_argument("--json", action="store_true")
  356. sp.set_defaults(func=_cmd_show)
  357. bp = sub.add_parser("build", help="Build the exact run command for a CLI (dry-run)")
  358. bp.add_argument("cli")
  359. bp.add_argument("--prompt", required=True)
  360. bp.add_argument("--workdir", default=None)
  361. bp.add_argument("--model", default=None)
  362. bp.add_argument("--baseline", action="store_true", help="Build the no-skill baseline command")
  363. bp.add_argument("--json", action="store_true")
  364. bp.set_defaults(func=_cmd_build)
  365. return p
  366. def main(argv: list[str] | None = None) -> int:
  367. args = build_parser().parse_args(argv)
  368. return args.func(args)
  369. if __name__ == "__main__":
  370. raise SystemExit(main())

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.