Installation Guide¶
Omics Skills supports Claude Code and Codex through the same skill source tree, but the two runtimes use different agent formats. Claude Code reads the canonical Markdown agents. Codex reads TOML agent definitions rendered during installation.
Requirements¶
Install Git, Bash, Python 3, and at least one supported runtime:
git --version
python3 --version
claude --version # if using Claude Code
codex --version # if using Codex
make install does not require a system Python environment. Development commands and skill-local Python helpers use uv.
Install from a Plugin Marketplace¶
Claude Code¶
Test a local checkout before publishing it:
claude plugin validate .
claude plugin marketplace add .
claude plugin install omics-skills@omics-skills
Codex¶
codex plugin marketplace add fmschulz/omics-skills
codex plugin list --available --json
codex plugin add omics-skills@omics-skills
For a local checkout, use codex plugin marketplace add .. The repository includes .codex-plugin/plugin.json and a repo marketplace at .agents/plugins/marketplace.json.
Install from a Checkout¶
Clone the repository and install both runtime integrations:
Install one runtime only:
The default install links skills and Claude agents to the checkout. Use copies when the checkout will not remain available:
The shell installer provides the same non-interactive choices when Make is unavailable:
Installed Files¶
The checkout installer writes only runtime configuration and omics-skills-owned entries:
~/.agents/skills/<skill>/ shared skill links or copies
~/.agents/omics-skills/ router and generated catalog
~/.claude/agents/<agent>.md Claude agent links or copies
~/.claude/skills link to ~/.agents/skills
~/.codex/agents/<agent>.toml rendered Codex subagent definitions
~/.codex/skills compatibility link to ~/.agents/skills
The canonical skill location for Codex is ~/.agents/skills. The ~/.codex/skills link is retained for compatibility. Because Codex agents are generated TOML rather than symlinks, rerun make install-codex-agents after editing a Markdown agent source.
Existing files with an omics-skills agent or skill name are moved to timestamped backups. Unrelated files and backups in the shared directories are left alone.
Manual Installation¶
Install shared skills and Claude agents with symlinks:
mkdir -p ~/.agents/skills ~/.claude/agents
for skill in "$PWD"/skills/*; do
ln -sfn "$skill" "$HOME/.agents/skills/$(basename "$skill")"
done
for agent in "$PWD"/agents/*.md; do
ln -sfn "$agent" "$HOME/.claude/agents/$(basename "$agent")"
done
ln -sfn "$HOME/.agents/skills" "$HOME/.claude/skills"
Render Codex agents instead of copying the Markdown files:
mkdir -p ~/.codex/agents
for agent in "$PWD"/agents/*.md; do
name=$(basename "$agent" .md)
python3 scripts/render_codex_agent.py "$agent" "$HOME/.codex/agents/$name.toml"
done
ln -sfn "$HOME/.agents/skills" "$HOME/.codex/skills"
Verify the Installation¶
For a full checkout installation:
Inspect the relevant files directly when only one runtime was installed:
ls -l ~/.claude/agents/omics-scientist.md
python3 -c "import pathlib,tomllib; tomllib.loads(pathlib.Path.home().joinpath('.codex/agents/omics-scientist.toml').read_text())"
ls -ld ~/.agents/skills/bio-annotation
python3 ~/.agents/omics-skills/skill_index.py route "annotate these proteins"
Use the Installation¶
Start Claude Code with a named agent:
Start Codex normally, then ask it to delegate to omics-scientist, or mention a skill explicitly with $bio-annotation. Codex discovers custom TOML subagents in ~/.codex/agents/.
The router can be queried independently of either runtime:
Optional Routing Hook¶
Install a prompt hook that adds a router hint for both runtimes:
Disable it for one shell session without uninstalling it:
Remove it with make uninstall-hook.
Python Dependencies¶
Skill helpers should declare their own environment through Pixi or PEP 723 metadata. For legacy requirements.txt files, the repository installer can create a local uv environment:
This writes .venv/ inside the checkout and does not modify system Python.
Update¶
For linked installs, pull the checkout and rebuild generated artifacts:
For copied installs, the same command replaces only the selected omics-skills entries. Plugin installs are updated through their respective marketplace commands.
Select Components¶
Run make install in a terminal to use the interactive selector. For automation, pass explicit lists:
make install-selected \
SELECTED_AGENT_FILES="omics-scientist.md" \
SELECTED_SKILL_DIRS="bio-logic bio-annotation"
Missing selected names fail the installation instead of reporting partial success. The generated catalog contains only the selected components.
Troubleshooting¶
Agent changes do not appear in Codex¶
Codex agents are generated TOML files. Regenerate them:
Skills disappeared after moving the checkout¶
Linked installs retain the old absolute paths. Reinstall from the new location:
A skill is not selected¶
Check the router result before changing prompts:
Then inspect the skill description and the owning agent's Task Recognition Patterns.
A local plugin is not listed¶
Confirm that the marketplace resolves to the checkout and that both plugin manifests use the same version.
Uninstall¶
Use the Makefile for a complete non-interactive uninstall:
The shell uninstaller asks for confirmation:
Both uninstallers remove only known omics-skills entries. They preserve unrelated agents, skills, and backups in shared runtime directories.