Contributing¶
AGENTS.md holds the structural rules: skill layout, the SKILL.md format, validator limits, pipeline stage pages and the agent's skills table. This page covers the workflow.
Set up¶
Without push access, fork the repository, work on a branch of the fork, and open a pull request.
The default linked install picks up edits at once. The Codex agent is a rendered file: run make install-codex after editing the agent prompt.
Add or change a skill¶
- Create or edit
skills/<name>/SKILL.md. The frontmatternamemust equal the directory name, and the description needs a trigger phrase (Use when,Use fororTrigger when). Put long tool notes, examples and references indocs/,examples/orreferences/inside the skill directory. - A new omics pipeline stage is a decision page under
skills/omics-pipeline/references/, with a row in the stage-page table ofskills/omics-pipeline/SKILL.md. When the stage ships scripts, make it a stage skill instead:disable-model-invocation: truein its frontmatter, anagents/openai.yamlwithpolicy.allow_implicit_invocation: false, and a row in the stage-skill table; the skill validator checks all three. A skill the agent uses gets one row in the## Skillstable ofagents/literature-expert.md(columnsSkillandUse for). - Run
make test.
Keep each skill to one purpose and compose workflows by referencing other skills. A supplementary tool guide starts with Last verified, Tool version/release checked, Official docs/manual and Release/source lines. A version in a skill is the version its commands were checked against, not an install pin: install commands add packages without a version, and projects lock what they install. To refresh checked versions, run python3 scripts/check_tool_versions.py, re-check the commands of each guide it flags, and update the guide. Examples use you@example.org. A real email address in a tracked file fails the tests.
Run the checks¶
CI runs these on every push to main:
make test
find scripts skills -name '*.sh' -print0 | xargs -0 -r -n 1 bash -n
uvx --from mkdocs --with 'mkdocs-material==9.5.*' --with pymdown-extensions mkdocs build --strict
make test runs the skill, supplementary-doc and citation validators, and the unit tests. The skill validator also enforces 500 lines per SKILL.md, 400 characters per description, 3,500 characters across the descriptions of model-visible skills (hidden stage skills do not count), and working local links.
When a plugin manifest changes, also run claude plugin validate ., codex plugin marketplace add . and codex plugin list --available --json. For installer changes, run make install, make status and make validate, and try the change in a Claude Code or Codex session.
Documentation site¶
MkDocs Material builds the site from docs/ and leaves out docs/handoffs/. Preview it with:
A push to main that changes docs/, mkdocs.yml or .github/workflows/pages.yml builds the site with --strict and deploys it to https://fmschulz.github.io/omics-skills/. Deployment needs the repository's Pages source set to GitHub Actions (Settings, Pages), a one-time setting.
Release¶
Release notes live in GitHub Releases. The repository has no CHANGELOG.md.
- Set the same version in
.claude-plugin/plugin.jsonand.codex-plugin/plugin.json, and write.github/releases/vX.Y.Z.md. - Push to
mainand wait for CI and the docs build to pass. - Run
python3 scripts/check_release_sync.py --tag vX.Y.Z --main-ref origin/main. - Create an annotated tag on that
maincommit and push it..github/workflows/release.ymlchecks the tag, both manifests, the release notes andorigin/main, then publishes the release. - Check the release page, the source archives, the version of an installed plugin, and the docs site.
Questions and bug reports go to GitHub issues; include the make status output and the steps to reproduce.