gene-review
Skill1 starsChanged 33 days agoBSD-3-ClauseView on GitHub
Review the Gene Ontology annotations of a gene using the ai4curation/ai-gene-review toolkit: fetch UniProt and EBI-GOA data, cache the literature, judge every existing annotation (ACCEPT / MODIFY / REMOVE / NEW ...), and write a validated GENE-ai-review.yaml. Use when a curator asks to "review", "audit", "check" or "curate" the GO annotations of a gene or gene product in any organism (e.g. "review DANRE fezf2", "audit the GO terms on human TP53"), or asks for a gene review, an annotation review, or an ai-gene-review. Works from any directory; sets up its own checkout of ai-gene-review on first use.
- Commits and pushes
In this repository11 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- amigoSkill
- annotate-functionSkill
- gocam-best-practiceSkill
- gocam-reviewSkill
- noctuaSkill
- pubmed-eutilsSkill
- reportSkill
- save-to-drop-boxSkill
- summarySkill
- uniprot-databaseSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
16 rules. About 0 are common, 9 are distinctive, and 7 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈9
Distinctive · estimate
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 36
If the user just wants to explore, then seed using DANRE as it is quite small.
- Distinctive: line 40
Run the bootstrap script. It is idempotent and prints a status block.
- Distinctive: line 51
Read the status block. In particular:
- Distinctive: line 57
If the script fails outright, report the error verbatim and stop.
- Very specific: line 109
Before any just fetch-gene, check both Git and the working tree.
- Very specific: line 118
If cat-file succeeds, this is an existing review to augment.
- Very specific: line 121
If it is absent from HEAD but the YAML exists locally, also augment it and preserve the local work.
- Very specific: line 124
Only if the review is absent from both HEAD and disk should you use just fetch-gene <ORGANISM> <GENE> to seed a new review.
- Very specific: line 135
Follow the inner skill's augment an existing review path.
- Distinctive: line 184
If the page shows a "Trust HTML" button in its toolbar, tell the curator it is safe to click: the file was generated locally from their …
- Distinctive: line 190
If the file browser does not yet show a file you just created, click the refresh icon at the top of the browser.
- Very specific: line 195
Check before fetching or editing: Run git status --short -- genes/<ORGANISM>/<GENE> and inspect any existing diff.
- Distinctive: line 211
Report where things landed: When done, tell the curator the absolute paths of the review YAML and notes file, the validation result, and …
- Distinctive: line 240
If they do, every step below involves GitHub authentication and each can fail in ways that need the curator's action.
- Very specific: line 287
Commit and confirm there is something to push: Commit with a message of the form Create gene review: <ORGANISM> <GENE> (or Re-review ...).
- Distinctive: line 308
If the push is refused with a permissions error, the curator does not have write access yet.
≈ “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.
Files
Gene review (ai-gene-review, from anywhere)
This skill is a front door. The review method, guidelines, validators and
scripts all live in the ai4curation/ai-gene-review repository; this skill makes
sure a (partial) checkout of it exists (usually in ~/ai-gene-review), then hands you over to the skills inside it. Do not
re-derive the method from memory: read the inner skills and follow them.
Arguments: $ARGUMENTS — a uniprot organism code and a gene symbol, e.g. DANRE fezf2,
human TP53, PSEPK PP_4218. If either is missing, ask before doing anything else.
Organism codes are UniProt species mnemonics (DANRE, MOUSE, SCHPO, ...) except
for a few lowercase GO names (human, mouse, yeast, worm).
If the user just wants to explore, then seed using DANRE as it is quite small.
Step 1 — make sure the toolkit is ready
Run the bootstrap script. It is idempotent and prints a status block.
AIGR_ORGANISMS="<ORGANISM>" bash "${CLAUDE_SKILL_DIR}/scripts/bootstrap.sh"What it does: clones ai-gene-review into $AIGR_HOME (default ~/ai-gene-review)
as a small sparse checkout if absent, adds the organism's genes/ directory, installs
uv and just if missing, and syncs the Python environment. First run takes a few
minutes; later runs a few seconds. Tell the user it is a one-off when it is slow.
Read the status block. In particular:
deep research: unavailablemeans the automated literature-synthesis step of the review will fail. That is expected in many environments. You will synthesise the literature yourself from the cached papers and record that in the gene's-notes.mdfile, exactly as the inner skill instructs for that case.- If the script fails outright, report the error verbatim and stop.
Then cd "$AIGR_HOME" (or cd ~/ai-gene-review). Every just command below must
run from inside that directory. The shell keeps its working directory between your
commands, so one cd is enough; re-cd if you move elsewhere.
Adding another organism to the checkout
The checkout is sparse: an organism directory can exist on disk while some of its committed reviews are excluded. If the curator turns to a different organism (say SCHPO after starting with DANRE), hydrate that directory first. Either re-run the bootstrap with the new organism, or use git directly:
git -C "$AIGR_HOME" sparse-checkout add genes/SCHPO history/genes/SCHPOThis pulls the files for that organism from GitHub on the spot (a few seconds,
tens of MB; SCHPO has about 150 reviewed genes). git -C "$AIGR_HOME"
sparse-checkout list shows the selected cones. An exact genes/<ORGANISM> entry
includes the whole organism; genes/<ORGANISM>/<GENE> includes only one gene.
An organism not yet in the repository can still be added to the sparse selection;
just fetch-gene creates its directory when the first gene is fetched. If adding
the cone fails, resolve the error before fetching.
For ortholog/paralog reviews used as references, also re-run the bootstrap with
AIGR_ORGANISMS="<ORGANISM>". If you add an individual gene with
git sparse-checkout add genes/<ORGANISM>/<GENE>, follow it by adding the whole
genes/<ORGANISM> and history/genes/<ORGANISM> cones before fetching any gene
from that organism. The bootstrap's organisms: line reports whole organism
cones, not partially populated directories.
Ignore a warning of the form "paths are not up to date and were left despite
sparse patterns" naming files under publications/. It is cosmetic: the
validator caches papers there on demand, outside the sparse set. The command
still succeeded.
Step 2 — load the method
The repository's own instructions are not loaded automatically when you start outside it. Read these before touching any YAML, in this order:
$AIGR_HOME/CLAUDE.md— from the heading "Gene Review Guidelines" to the end. It defines the action vocabulary, the "do not overrule curators from incomplete evidence" and "do not add what curators deliberately declined to add" rules, how IBA annotations are to be read, and how references are reviewed.$AIGR_HOME/.claude/skills/review/SKILL.md— the step-by-step review workflow.$AIGR_HOME/.claude/skills/annotation-reviewer/SKILL.md— how to judge each annotation and fill inexisting_annotations[].review.
Before fetching: distinguish an existing review from a new gene
Before any just fetch-gene, check both Git and the working tree. A missing file
on disk does not mean a new review: it may be excluded by sparse checkout.
From $AIGR_HOME, substitute the actual organism and gene in these commands:
git cat-file -e HEAD:genes/<ORGANISM>/<GENE>/<GENE>-ai-review.yaml
git status --short -- genes/<ORGANISM>/<GENE>- If
cat-filesucceeds, this is an existing review to augment. In a sparse checkout, rungit sparse-checkout add genes/<ORGANISM> history/genes/<ORGANISM>and confirm the YAML is on disk before fetching. Read and preserve its reviews. - If it is absent from
HEADbut the YAML exists locally, also augment it and preserve the local work. If the Git check fails for any reason other than a missing path (for example, an invalidHEAD), resolve that before proceeding. - Only if the review is absent from both
HEADand disk should you usejust fetch-gene <ORGANISM> <GENE>to seed a new review.
For an existing review, fetch only if its derived data needs refreshing, after confirming the YAML is present and inspecting the pre-edit status below. Then add missing GOA rows without replacing existing annotations or their reviews:
uv run ai-gene-review seed-goa genes/<ORGANISM>/<GENE>/<GENE>-ai-review.yamlFollow the inner skill's augment an existing review path. When refreshed GOA changes a GO_REF, an older row can fail validation as "not in GOA". Compare it with the replacement GOA row and, when it represents the same annotation with updated provenance, carry the review onto that row (updating its rationale or references as needed). Reconcile the obsolete row with the current GOA data; do not drop the annotation just because its GO_REF changed. Validate the result.
With this existing/new decision made, follow the review skill, substituting
$ARGUMENTS for its placeholders.
Where it says to invoke the annotation-reviewer subagent, do that work yourself
following the annotation-reviewer skill, unless a subagent is available to you.
Step 3 — other tasks in the same toolkit
Route by what the curator asks for. Read the named file, then follow it.
| Curator wants | Read |
| review a gene's GO annotations (default) | .claude/skills/review/SKILL.md + annotation-reviewer/SKILL.md |
| ADVANCED: review computational function predictions (ProtNLM, InterPro2GO, ...) | .claude/skills/review-function-prediction/SKILL.md |
| ADVANCED: review a UniProt ARBA / UniRule rule | .claude/skills/rule-reviewer/SKILL.md |
| summarise what cited papers say about a gene | .claude/skills/reference-findings-summarizer/SKILL.md |
| ADVANCED: a pathway summary after a review | .claude/skills/pathway-inference-agent/SKILL.md |
| ADVANCED: curate a module (pathway/complex) or a GO-CAM review | .claude/skills/module-curation/SKILL.md, .claude/skills/gocam-curation/SKILL.md |
Paths are relative to $AIGR_HOME. Skills not listed here (boss, pm,
aigr-pr-review, ...) are for repository maintainers; leave them unless asked.
Step 4 — render the review as HTML and show it to the curator
The YAML is the record, but it is not pleasant to read. Once a review validates, render it:
just render <ORGANISM> <GENE>This writes genes/<ORGANISM>/<GENE>/<GENE>-ai-review.html next to the YAML and
prints the path. Re-run it after any further edit; it overwrites.
Curators usually cannot open a file path you print. Walk them to it in JupyterLab:
- In the file browser on the left, if it is not showing your home directory, click the folder icon at the top of the path bar to go there.
- Open
ai-gene-review, thengenes, then the organism folder, then the gene folder (forDANRE fezf2:ai-gene-review › genes › DANRE › fezf2). - Double-click
<GENE>-ai-review.html. It opens in a new tab as a rendered page. If JupyterLab shows the raw HTML source instead, right-click the file and choose Open With › HTML Viewer. - If the page shows a "Trust HTML" button in its toolbar, tell the curator it is safe to click: the file was generated locally from their review and the button only enables the page's own styling and scripts.
- The
<GENE>-notes.mdin the same folder opens the same way (double-click gives a rendered Markdown preview; Open With › Editor shows the source).
If the file browser does not yet show a file you just created, click the refresh icon at the top of the browser; it does not always update on its own.
Rules that apply because you are running from outside the repository
- Check before fetching or editing. Run
git status --short -- genes/<ORGANISM>/<GENE>and inspect any existing diff. AnMon a review you have not edited can signal an earlier clobber byfetch-gene. Compare it withgit show HEAD:genes/<ORGANISM>/<GENE>/<GENE>-ai-review.yamlbefore continuing. Preserve local work; do not blindly restore over it. - Validate explicitly. Inside the repo, hooks validate a review file on every
edit. Those hooks do not fire here. After every edit to
*-ai-review.yaml, runjust validate <ORGANISM> <GENE>and fix what it reports before moving on. - Never hand-edit derived files (
*-uniprot.txt,*-goa.tsv,*-deep-research-*.md,publications/*). Regenerate them withjust fetch-geneorjust fetch-gene-pmids. - Never write a file named
*-deep-research-<provider>.mdyourself. If deep research is unavailable, your synthesis goes in<GENE>-notes.md. - Do not commit or push unless the curator asks. Reviewing needs no GitHub
identity. If they do ask, check
gh auth statusandgit config user.emailfirst and tell them plainly what is missing rather than trying to work around it. - Report where things landed. When done, tell the curator the absolute paths of the review YAML and notes file, the validation result, and whether deep research ran or was replaced by manual synthesis.
If something is off
just: command not foundafter bootstrap →export PATH="$HOME/.local/bin:$PATH".- Validation complains that
file:references or GO_REFs cannot be resolved → the checkout is missingconf/; rungit -C "$AIGR_HOME" sparse-checkout add conf. - The organism directory is missing →
git -C "$AIGR_HOME" sparse-checkout add genes/<ORG>; if the organism is new to the repo,just fetch-genecreates it. - To force a full working tree:
AIGR_FULL=1on the bootstrap (about 4 GB). git addsays paths "exist outside of your sparse-checkout definition" → usegit add --sparse <paths>forpublications/, or add the cone for anything undergenes/orhistory/(git sparse-checkout add history/genes/<ORG>), then re-add.gh pr createfails with "No commits between main and<branch>" → the branch was pushed with nothing on it; checkgit log origin/main..HEAD, commit, push again.
Advanced — contributing a review back
By default the checkout is read-only in practice. It is a public clone over
HTTPS with no credentials attached, and pushing to ai4curation/ai-gene-review
requires the curator's GitHub account to have been added to that repository. For
now the primary purpose of this skill is exploration; reviews live in the
curator's home directory. If a curator would like their review to become part of
the project, the simplest route is to contact Chris Mungall or Seth Carbon and
they will arrange access or take the files from there. Say this before starting
any of the steps below, and only continue if the curator explicitly wants to.
If they do, every step below involves GitHub authentication and each can fail in ways that need the curator's action. Go one step at a time, show them what you are running, and stop at the first thing that does not work rather than improvising.
- GitHub login for
gh.gh auth status. If not logged in, rungh auth login --hostname github.com --git-protocol https --web, read the one-time code from its output, and tell the curator: open https://github.com/login/device in a new browser tab, enter this code, and authorize. Wait, then re-checkgh auth status. - Let git use that login.
gh auth setup-git(once per user). Without itgit pushfails with could not read Username. - Git identity.
git config --global user.nameanduser.email; if either is empty, take the name fromgh api user --jq .nameand ask the curator which email to use (their GitHub noreply address is fine if they prefer privacy). - Branch, render, history record — from inside
$AIGR_HOME.git fetch origin main && git checkout -b review-<ORGANISM>-<GENE>. Re-runjust render <ORGANISM> <GENE>so the committed HTML matches the final YAML. Scaffold the history record the repository requires:just new-history --kind gene --organism <ORGANISM> --slug <GENE> --event CREATE --outcome changed --summary "Create review: <ORGANISM> <GENE>" --agent-tool claude-code --model <model> --details "<one paragraph>", thenjust validate-history <path it printed>. Use--event EDITand a summary such asRe-review <GENE> against current GOAwhen you augmented an existing review; add--issue Nor--url <URL>for anything the work relates to. Never write the record's filename or session id by hand. Stage explicitly; never
git add -A. The sparse checkout refuses paths outside its cones with "matched paths that exist outside of your sparse-checkout definition, so will not be updated in the index", andpublications/is never in a cone. Run these as separate commands, not one&&chain, so a refusal cannot silently skip the commit:git add genes/<ORGANISM>/<GENE> history/genes/<ORGANISM>/<GENE> git add --sparse $(git status --short | awk '$1=="??" && $2 ~ /^publications\//{print $2}') git diff --cached --name-status--sparse(git 2.35+) stages files outside the cones without hydrating the whole directory. Include only the newly cachedpublications/PMID_*.mdyour review quotes; CI's reference validator needs them. Leave outuv.lock,cache/go/terms.csv, and re-fetched copies of already-tracked publications whose diff is whitespace only (git diff --stat publications/shows them): the environment sync and the validator touch these as side effects. The PR template says not to commit derived files, yet the repository tracks*-goa.tsv,*-uniprot.txtand the rendered HTML for every review; include the gene directory asfetch-geneandrenderproduced it, and say so in the PR body. Read the staged list back before committing.- Commit and confirm there is something to push. Commit with a message of the
form
Create gene review: <ORGANISM> <GENE>(orRe-review ...). Then rungit log origin/main..HEAD --oneline; if it prints nothing, the commit did not happen (usually a refusedgit addearlier). Do not push until it lists your commit. - Push and open the PR.
git push -u origin review-<ORGANISM>-<GENE>, thengh pr create --repo ai4curation/ai-gene-review --head review-<ORGANISM>-<GENE> --base main --filland edit the body to follow the repository's PR template (.github/PULL_REQUEST_TEMPLATE.md: summary withCloses #Nif a tracking issue exists,just validateoutput, test plan). Pass--headexplicitly; without itghsometimes claims the branch was not pushed. A "Warning: N uncommitted changes" fromghrefers to the side-effect files you left unstaged and is fine. "No commits between main and<branch>" means the branch was pushed empty: go back to step 6. - Link the PR from the history record. Append the PR URL to
links.prsin the record from step 4, runjust validate-historyon it again, commit (History record: link PR #N), and push. Records are append-only for their target path, but adding links before merge is expected. - Report the PR URL and tell the curator that CI will validate the review and a maintainer will look at it; they do not need to do anything further.
If the push is refused with a permissions error, the curator does not have write access yet. Do not try to fork around it; point them back to Chris or Seth.
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
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.

