Skip to content

host_compatibility.md

Latest commit

 

History

History
59 lines (37 loc) · 6.66 KB

host_compatibility.md

File metadata and controls

59 lines (37 loc) · 6.66 KB

Host Compatibility

How MedSci Skills installs and runs across agent hosts, what is verified, and what is not.

The guiding rule: a cell is VERIFIED only with a source URL and retrieval date. Everything else is UNVERIFIED — never "target support". MedSci Skills will not claim a host works until install and discovery are confirmed against that host's official documentation.

Canonical source

The single source of truth for every skill is skills/<name>/SKILL.md. The repository follows the Agent Skills open standard: a skill is a directory containing a SKILL.md (YAML frontmatter + Markdown body) plus optional scripts/, references/, and assets/ subdirectories, loaded by progressive disclosure (name + description at startup; body on activation; bundled files on demand). The installer copies these directories verbatim into host skill folders — there is no per-host fork of any skill.

Host matrix

Install paths below were read from each host's official documentation on 2026-06-03. Skill counts and conventions drift; re-verify at the cited source.

Host Status Discovered install path(s) Source (retrieved 2026-06-03)
Claude Code VERIFIED Personal ~/.claude/skills/<name>/SKILL.md; project .claude/skills/<name>/SKILL.md https://code.claude.com/docs/en/skills
OpenAI Codex VERIFIED Personal ~/.agents/skills/; repo .agents/skills/ (scanned cwd→repo root); system /etc/codex/skills; config ~/.codex/config.toml ([[skills.config]]) https://developers.openai.com/codex/skills
Cursor VERIFIED Native ~/.cursor/skills/, .cursor/skills/, ~/.agents/skills/, .agents/skills/; also reads ~/.claude/skills/, .claude/skills/, ~/.codex/skills/, .codex/skills/ for compatibility https://cursor.com/docs/skills
GitHub Copilot VERIFIED Project .github/skills/, .claude/skills/, .agents/skills/; personal ~/.copilot/skills/, ~/.agents/skills/ https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/add-skills
Generic Agent Skills standard standard-aligned <root>/<name>/SKILL.md; validate with skills-ref validate ./<name> https://agentskills.io/specification · https://github.com/agentskills/agentskills
OpenClaw UNVERIFIED — roadmap Not confirmed against official docs; no install code —
Hermes UNVERIFIED — roadmap Not confirmed against official docs; no install code —

What this means in practice

The verified paths converge on two directories, which is why the existing installer needs no per-host rewrite:

  • ~/.claude/skills/ (+ project .claude/skills/) is read by Claude Code (native), GitHub Copilot, and Cursor (compatibility).
  • ~/.agents/skills/ (+ project .agents/skills/) is read by Codex (native), Cursor (native), and GitHub Copilot.

installers/install.py already installs to both (--target claude → ~/.claude/skills, --target codex → ~/.agents/skills). The codex → ~/.agents/skills mapping is verified correct against the Codex docs above. The installer's optional .cursor/rules/medsci-skills.mdc project rule is now legacy: Cursor reads ~/.claude/skills and ~/.agents/skills directly, so a separate Cursor install is no longer required for skill discovery (the rule remains a convenience for steering, not a requirement).

OpenClaw and Hermes stay on the roadmap with no install code or support claim until their official conventions are confirmed.

Claude-specific assumptions inventory

These are points where the repository or a workflow assumes a Claude Code environment. The skill packages are portable; some workflows are not.

Frontmatter (portable with a caveat). Each SKILL.md uses name, description, triggers, tools, model. The open standard requires only name and description; triggers, tools, and model are non-standard fields. Compliant hosts ignore unknown fields, so they do not break discovery, but they are not interpreted off-Claude. (tools is also not the standard's allowed-tools.) A future alignment could move these under the standard's metadata map or add a compatibility field; out of scope here.

Install / config paths.

  • ~/.claude/skills, ~/.agents/skills — install destinations (both verified above).
  • ~/.claude/rules, ~/.claude/hooks — host-local user configuration, not part of any skill package and not installed by this repo. Behaviors that depend on user rules or hooks do not transfer to other hosts.

Runtime references inside skills.

  • ${CLAUDE_SKILL_DIR} — used by ~150 asset references across the skills to locate bundled scripts//references/. Hosts that set this variable (or an equivalent skill-root variable) resolve them; a few skills also accept ${MEDSCI_SKILLS_ROOT:-$HOME/workspace/medsci-skills} as a fallback. On a host that sets neither, bundled-asset paths must be resolved relative to the skill root.
  • MCP tool names — some skills reference Claude MCP servers in their bodies (for example PubMed / CrossRef / Zotero / Google Drive, named like mcp__claude_ai_* or mcp__zotero__*). These are not declared in the tools frontmatter and are host-specific: off-Claude hosts without the same MCP servers fall back to the skills' deterministic scripts or to manual workflow.

Skill portability vs full-workflow portability

  • Skill packaging is portable. Every SKILL.md + bundled scripts//references/ is standard-compliant and installs into the verified hosts above without modification.
  • Full-workflow portability varies. A workflow degrades off-Claude when it depends on (a) a Claude MCP server for live data (citation verification, Zotero sync, Drive I/O), (b) host-local ~/.claude/rules / ~/.claude/hooks, or (c) a skill-root environment variable the host does not set.

Skills whose value is mostly bundled deterministic scripts + reference material (for example reporting-checklist audits, figure generation, sample-size calculation, statistical code) port most cleanly. Skills whose value depends on live MCP retrieval (literature search, reference verification, Zotero/Drive sync) need those servers configured on the target host, or fall back to manual steps. Per-skill specifics are recorded in each skill's Quality Card (evidence_surface and known_limitations).

Part of MedSci Skills. See also docs/competitive_positioning.md and the per-skill reference in docs/skills/. Install instructions are in the main README.