noctua
Skill1 starsChanged 32 days agoBSD-3-ClauseView on GitHub
Use whenever you need to access the GO-CAM store (Noctua). This is accomplished via an API called barista.
- Reads credentials
In this repository11 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- amigoSkill
- annotate-functionSkill
- gene-reviewSkill
- gocam-best-practiceSkill
- gocam-reviewSkill
- 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
13 rules. About 0 are common, 8 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈8
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 13
Use for listing and searching models, create/read/update on models.
- Very specific: line 49
Run this before every barista command (a saved token lives in ~/.env and is not loaded automatically).
- Distinctive: line 59
Verify with an authenticated call:
- Distinctive: line 72
Only the user can do this.
- Distinctive: line 97
Each curator uses their own token: Never reuse someone else's, and never carry one user's token into another user's work.
- Distinctive: line 144
All that reference a gene product
- Distinctive: line 167
real save: If the dev server restarts before that, anything unsaved is simply gone: a model that has picked up a real save survives a …
- Distinctive: line 200
Store: after meaningful work and always before exporting.
- Very specific: line 237
Read the model back afterwards (barista get-model) and confirm the change you meant is there.
- Very specific: line 243
When you remove evidence from an edge (remove-annotation of an evidence value, or deleting/re-adding an edge), also delete the evidence …
- Distinctive: line 252
When a curator has built something they care about, tell them where it stands and offer to submit it.
- Very specific: line 339
Use variable names (via --assign) for readability when building complex models
- Distinctive: line 341
Always add evidence to support facts in models
≈ “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
About
Use for listing and searching models, create/read/update on models.
Command Line Client
This uses the noctua command line tool, which should have been installed when we ran uv tool install noctua
I recommend:
alias barista='noctua barista'You can get help at any time
barista --helpsubcommands also have help
Tokens — do this FIRST, before any model work
A barista token is personal: it comes from a human logging in with their ORCID, it carries that person's identity (models they create are attributed to it), and it expires. There is no shared or service token — each curator uses their own.
Set this up at the start of a session, not after something fails. Building a model and only then discovering you can't write wastes the user's time.
Step 1 — load any token the user already saved
set -a; [ -f ~/.env ] && . ~/.env; set +aRun this before every barista command (a saved token lives in ~/.env and is
not loaded automatically). If a previous session already set one up, this is all
you need.
Step 2 — verify it actually works
Do not assume a token is good just because BARISTA_TOKEN is set, and do not
use list-models as the check — list-models reads the search index and
succeeds with no token at all, or with a garbage one. It proves nothing.
Verify with an authenticated call:
noctua barista get-model --model <any-known-model-id>- Works → you're set.
"You are using a bad token; please remove it."→ the token is invalid or expired. Go to step 3.BARISTA token not provided→ no token yet. Go to step 3.
Step 3 — walk the user through getting one
Only the user can do this; it's an interactive login.
- Open http://noctua-dev.berkeleybop.org/workbench/noctua-landing-page/
- Click Login and authenticate with ORCID.
- Copy the barista token shown on the page.
Logging in on the web page does not hand the token to this shell — they have to paste it. Offer to save it so they only do this once:
echo 'BARISTA_TOKEN=<paste-token-here>' > ~/.env && chmod 600 ~/.envThen re-run step 1 and re-verify with step 2.
The token is the curator's identity — it becomes provenance
The token is not just access, it is who the work belongs to. Barista stamps
the ORCID behind it onto every model as contributor, and that provenance
travels: it is carried in the GO-CAM YAML, per activity, all the way into a
go-cam-drop-box submission. Nothing downstream validates it, so a wrong ORCID is
never caught — it just quietly ships as a false claim about who did the science.
Two practical consequences:
- Each curator uses their own token. Never reuse someone else's, and never carry one user's token into another user's work.
- Sanity-check the identity. Barista responses include the ORCID as
uid(e.g."uid": "https://orcid.org/0000-0002-1825-0097"). If it isn't the person you're working with, stop and say so before building anything.
The token is stored in the user's own ~/.env (mode 0600); ordinary unix
permissions on the box are the protection, which is proportionate for a dev
server.
The dev server's API namespace is minerva_public_dev
The noctua barista CLI already addresses the right server and namespace;
prefer it over hand-written HTTP calls. When a raw call is unavoidable (the
/save-to-drop-box skill shows the sanctioned form), the path is
http://barista-dev.berkeleybop.org/api/minerva_public_dev/....
minerva_public_dev is the dev server's API namespace for curator tooling.
minerva_public is production's namespace and does not exist on
noctua-dev; do not substitute it, and do not copy namespace names from
production URLs or examples.
Read Access
To dump a model in minerva JSON:
barista export-model --model 646ff70100002557This is the low-level triple representation used natively in Noctua
In gocam-yaml:
barista export-model --model 646ff70100002557 -f gocam-yamlThis is the structured version
Search and Browsing models
Most recent 50:
barista list-models --limit 50All that reference a gene product
barista list-models --gp UniProtKB:Q14457Search by title
barista list-models --title "immune"IMPORTANT — noctua-dev is a proving ground, not a save
Do not tell the user their work is safe because it is on noctua-dev. The dev
server is a place to build and test models. Models there can and do disappear:
a model can read back successfully and still be gone from the store later
(UnknownIdentifierException: Could not find a model for id: …), forcing a
rebuild.
Why this happens — the mechanism matters. A model built through these barista commands lives in minerva's memory. It reads back perfectly, it is editable, and it looks completely real — but it is not on disk until something triggers a real save. If the dev server restarts before that, anything unsaved is simply gone: a model that has picked up a real save survives a reboot, one that has not blinks out.
So "I just read it back and it's fine" proves the model exists right now, not that it will survive. Never treat a successful read as evidence of durability.
Two rules follow:
- Never explain a missing model as "search-index lag." That explanation is wrong and leaves the curator waiting for models that no longer exist. If a model is missing, check whether it still exists (below) and say plainly what you find.
list-modelsand the landing page are not proof of persistence. They read the search index. The authoritative check is reading the model by ID:noctua barista get-model --model <model-id>UnknownIdentifierExceptionmeans the model is gone — not hidden, not pending. It must be rebuilt.
The durable save is the go-cam-drop-box — see the /save-to-drop-box skill.
Since 2026-09-24 a submission is the model in two formats under its dev id
(gocam-py YAML + minerva TTL), both exported from the same stored state of
the model on noctua-dev. So a model must exist on noctua-dev and be
stored there before it can be submitted; nothing can be submitted from
notes or a hand-written YAML. Its state (development, production, ...) is
the curator's call and travels as set.
Store, state, comments, export
- Store after meaningful work and always before exporting. An unstored model
lives only in minerva's memory and is gone at the next dev restart (this has
cost curators finished models). Store with the minerva
storeoperation and verify"modified-p": falseafterwards — the exact commands are in/save-to-drop-box, step 2. - State and comments are model annotations, set on dev:
barista update-metadata --model <id> --add --comment "..."and, only when the curator asks,barista update-metadata --model <id> --state .... Never add comments to an exported YAML by hand; CI compares YAML and TTL comments. - Export both files back to back from the stored state (
/save-to-drop-box, step 3). Any later edit means store + re-export both again.
Raw minerva requests: only when barista has no command for it
The barista commands take the model id as an argument and are the first
choice. When an operation has no command (changing an individual's class, for
example) and you post to m3BatchPrivileged yourself:
- Send the same four fields the store command in
/save-to-drop-boxsends (token=$BARISTA_TOKEN,intention=action,provided-by=http://geneontology.org,requests=...); the export there goes to the read-onlym3Batchand needs none of them. - Build the JSON in a shell variable and pass it inline,
--data-urlencode "requests=$payload"; a quoted heredoc (payload=$(cat <<'EOF' ... EOF)) keeps apostrophes in labels and comments intact. If it must come from a file, create that file withmktemp, never a fixed path such as/tmp/req.json: the hub is one machine shared by every curator, and on 2026-10-14 a stale file of that name, left by one curator, was posted by another curator's session with their token, which put their name on a model they never touched. - Chain the steps with
&&(the write, then the curl that reads the file) so a failed write never reaches the send.set -euo pipefailbelongs at the top of a standalone script only; inside a function or an interactive shell it leaks into the caller or is switched off by an&&/ifcontext. - Print the payload before sending it and check that every
model-idin it is the model the curator is working on. The dev server accepts any valid token for any model, so "don't edit models you didn't create" is yours to enforce. - Read the model back afterwards (
barista get-model) and confirm the change you meant is there; asuccessreply only says the server accepted what it received.
Evidence hygiene
When you remove evidence from an edge (remove-annotation of an evidence
value, or deleting/re-adding an edge), also delete the evidence individual
(barista delete-individual). Evidence individuals that no axiom references are
"disconnected individuals"; production's QC battery flags them and the drop-box
CI now rejects them. Likewise avoid attaching evidence to the same edge twice as
separate axioms.
Offer the durable save — don't force it
When a curator has built something they care about, tell them where it stands and offer to submit it. Then respect the answer. Plenty of work here is deliberate experimentation that nobody wants to keep, and that is fine — the point is that the user is informed, not that everything gets submitted.
Say something like: "This currently only exists on the dev server, which can lose models. The durable save is a PR to the go-cam-drop-box — want me to submit it?"
Editing a model that was already submitted or merged
Once a model is merged into go-cam-drop-box, that becomes the source of truth for that ID. It flows onward to production, and when it does it will clobber other copies — including any edits made on noctua-dev afterwards.
So if the user edits a model on noctua-dev that has already been submitted or merged, point this out and offer to carry the change back:
- PR still open → update that PR with the new version.
- Already merged → open a new PR against the merged model.
Otherwise their edit looks fine on noctua-dev and is silently overwritten later.
Not currently supported: pulling a merged drop-box model that is no longer on
noctua-dev back onto the dev server to edit it. barista create-model cannot be
given an ID (it only takes --title), so a replayed model gets a fresh minerva
ID, loses its gcdb-<UUID> linkage, and a PR from it would fork the source of
truth instead of updating it. If a curator needs this, the simpler path is to
deprecate the old model (model-state=deleted) and create a new one with a note
explaining the lineage. Flag the limitation rather than improvising a round-trip.
More Information
Please see the /gocam-best-practice skill
Using the Barista Command-Line Tool
The barista command (alias for noctua barista) provides tools for model creation and editing.
Key Commands
Viewing Models
# Export model in Minerva JSON format
barista export-model --model <model-id>
# Export in GO-CAM YAML format
barista export-model --model <model-id> -f gocam-yaml
# List recent models
barista list-models --limit 50
# Search models by gene product
barista list-models --gp UniProtKB:Q14457
# Search models by title
barista list-models --title "immune"Creating and Editing Models
# Create a new empty model
barista create-model
# Add an individual (molecular activity, BP, or CC)
barista add-individual --model <model-id> --class <GO-term> --assign <variable-name>
# Create a relationship between individuals
barista add-fact --model <model-id> \
--subject <variable-or-id> \
--object <variable-or-id> \
--predicate <relation-id>
# Add evidence to support a relationship
barista add-fact-evidence --model <model-id> \
--subject <variable-or-id> \
--object <variable-or-id> \
--evidence <evidence-code> \
--reference <PMID>Important Notes
- Commands use the test server by default; production requires the explicit
--liveflag - Use variable names (via
--assign) for readability when building complex models - Production models with state="production" are protected against accidental deletion
- Always add evidence to support facts in models
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.

