agentleFS
geneontologygeneontology/go-skills/skills/gocam-best-practice/SKILL.md

gocam-best-practice

Skill1 starsChanged 32 days agoBSD-3-ClauseView on GitHub

This skill should be used when creating, editing, or validating GO-CAM (Gene Ontology Causal Activity Model) models. It provides comprehensive annotation guidelines for molecular functions, biological processes, cellular components, and causal relationships following GO Consortium standards.

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
  1. Distinctive:

    Use this skill when:

    line 26
  2. Distinctive:

    How_to_annotate_complexes_in_GO-CAM.md: When and how to represent protein complexes

    line 38
  3. Very specific:

    Add individuals: Use barista add-individual to create activity nodes

    line 48
  4. Very specific:

    Connect activities: Use barista add-fact to create causal relationships

    line 49
  5. Very specific:

    Validate: Check against guidelines in references/ files

    line 52
  6. Distinctive:

    Every GO-CAM model consists of:

    line 75
  7. Distinctive:

    BP should always be included: If no relevant BP fits, question whether the model is valid — a standard annotation may be more appropriate.

    line 112
  8. Distinctive:

    Use direct regulation only when the mechanism is known and immediate (no intervening activity).

    line 113
  9. Very specific:

    When a MF's has output chemical is the has input of the next MF, the provides input for edge is inferred and is not materialized.

    line 115
  10. Very specific:

    The handoff shares one individual: When the has output of one activity is the has input of the next activity (the molecule is passed …

    line 119
  11. Distinctive:

    Before finalizing a GO-CAM model, verify:

    line 152
  12. Distinctive:

    Be specific: Use the most specific GO term and relation available

    line 221
  13. Distinctive:

    Document evidence: Always include supporting references

    line 222
  14. Distinctive:

    Test first: Use test server before committing to production

    line 223
  15. Very specific:

    Check relevant guideline files in references/ directory

    line 254
  16. Very specific:

    Search for similar examples using barista list-models

    line 255

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md
<!-- claude4go: The "This is a copy of the official … https://docs.google.com/…" notices throughout this skill (in SKILL.md, the README, and every references/ file) are HUMAN source-of-truth pointers. You cannot access Google Docs. Do not attempt to fetch them, do not treat the local .md as incomplete because of them, and do not cite the Doc URL as your source. Treat the local markdown as authoritative for curation. -->

GO-CAM Best Practice Skill

This skill provides expert guidance for creating and editing GO-CAM (Gene Ontology Causal Activity Model) models using the barista command-line tool. GO-CAM models represent biological knowledge as networks of causal relationships between molecular activities.

When to Use This Skill

Use this skill when:

  • Creating new GO-CAM models from biological pathway descriptions
  • Editing existing GO-CAM models to add activities or relationships
  • Validating GO-CAM models against annotation best practices
  • Annotating specific molecular function types (transcription factors, receptors, transporters, etc.)
  • Representing protein-containing complexes as enablers
  • Annotating various molecular functions such as adaptors, carriers, or sequestering proteins
  • Adding evidence to support relationships (causal and others)

Core Guidelines

  • GO-CAM_annotation_guidelines_README.md: Overview of GO-CAM annotation principles
  • How_to_annotate_complexes_in_GO-CAM.md: When and how to represent protein complexes
  • Gene_product_identifiers.md: Choosing the enabler identifier (MOD accession vs UniProtKB)
  • Relation_selection.md: Causal and contextual relations, with usage for each
  • Evidence_and_evidence_codes.md: Evidence codes, the with/from field, references, and the ISS ortholog-transfer recipe

Workflow for Creating a GO-CAM Model

  1. Plan the model: Identify the biological pathway or process to represent
  2. Identify gene products: Determine which gene products are involved
  3. Define activities: For each gene product, determine its molecular function(s)
  4. Add individuals: Use barista add-individual to create activity nodes
  5. Connect activities: Use barista add-fact to create causal relationships
  6. Add context: Specify inputs, locations, and processes
  7. Add evidence: Support all facts with evidence codes and references
  8. Validate: Check against guidelines in references/ files
  9. Export and review: Export the model to review its structure

Core Concepts

Metadata

  • Each model should have a title, a date_created, a contributor and a model state.
  • Recommended practices for naming a GO-CAM model is to include: (This is a copy of the official documentation: https://docs.google.com/document/d/1a5YZBJrnJ9LKJxPVpXk62dJJGpHB2b9zH8-xr_Rm1Vs/edit?tab=t.0)
    1. The GO Biological Process term that best represents the biological process or pathway being modeled.
    2. Additional relevant biological context, such as cells, tissues, specific genes, if not already represented in the GO BP term but helpful for distinguishing models.
    3. Species. If there are two species (host-symbiont), separate the species with a hyphen.
    4. Limit the title length to 60 characters.

Examples:

  • BMP signaling pathway via dpp-tkv/put (D.mel)
  • 'de novo' AMP biosynthetic process (Mouse)
  • Antifungal innate immune response in the hypodermis via transforming growth factor beta receptor signaling pathway (C. elegans)
  • Mumps-V inhibition of STAT1/STAT3 via DDB1/CUL4A (Human-Paramyxovirus)

GO-CAM Structure

Every GO-CAM model consists of:

  • Individuals (nodes): Molecular activities (MF), biological processes (BP), cellular components (CC), inputs, outputs and enablers
  • Facts (edges): Relationships between individuals, including (but not limited to) causal relations
  • Evidence: Publications and evidence codes supporting each fact

Activity Units

An activity unit is the fundamental building block of GO-CAM models:

  • Enabler the gene product (protein or RNA) or protein-containing complex that mediates the Molecular Function
  • MF (Molecular Function): The activity 'enabled' by a gene product or protein-containing complex
  • Context: Additional information via contextual relations such as 'has input', 'occurs in', 'part of'

Identifiers: MOD accessions vs UniProtKB

The enabler's identifier depends on the organism: use the model-organism-database (MOD) accession for model organisms (MGI, RGD, ZFIN, FB, SGD, WB, PomBase, and others), and UniProtKB for human and all other organisms. This is not something a curator should freely specify. See references/Gene_product_identifiers.md for the full species list, the MGI double-prefix exception (MGI:MGI:...), and how this applies to the ISS with/from field.

Representation of molecular activites enabled by protein-containing complexes

See documentation at How_to_annotate_complexes_in_GO-CAM.md.

Annotation Guidelines by Activity Type

The references/ directory contains detailed guidelines for specific annotation scenarios. Load these files when working with the corresponding activity types:

  • DNA-binding_transcription_factor_activity_annotation_guidelines.md (also covers transcription coregulator activity)
  • Signaling_receptor_activity_annotation_guidelines.md
  • Transporter_activity_annotation_annotation_guidelines.md
  • E3_ubiquitin_ligases.md
  • Molecular_adaptor_activity.md
  • Molecular_carrier_activity.md
  • Sequestering_activity.md
  • Enzyme_regulator_activity.md
  • Chemical_entities_ChEBI.md

Relations: causal and contextual

Molecular functions are linked to each other with causal relations, and to their context (BP, CC, inputs, outputs, temporal phase) with contextual relations. Picking the right relation is central to GO-CAM modeling. See references/Relation_selection.md for the full tables: all causal relations (direct/indirect, positive/negative, provides input for, removes input for, constitutively upstream of, causally upstream of), the small-molecule activator/inhibitor relations, the contextual-relations table, and input/output specification rules.

Key reminders:

  • BP should always be included. If no relevant BP fits, question whether the model is valid — a standard annotation may be more appropriate.
  • Use direct regulation only when the mechanism is known and immediate (no intervening activity); otherwise use indirect.
  • 'has input' captures the direct target (enzyme substrate, gene regulated by a TF, receptor activated by a ligand, effector activated by a receptor). Only primary inputs/outputs — not chemical-group donors.
  • When a MF's has output chemical is the has input of the next MF, the provides input for edge is inferred and is not materialized.

Distinct Individuals for Distinct Roles (one exception: the handoff)

The handoff shares one individual. When the has output of one activity is the has input of the next activity (the molecule is passed downstream), use one individual for both facts. That shared node is what represents the handoff, and provides input for is inferred from it (see references/Chemical_entities_ChEBI.md).

Every other role gets its own individual, even when it is the same molecular entity (same ChEBI ID/UniProtKB ID/MOD ID/GO protein-containing complex ID): the inputs of two different reactions are two individuals, and the outputs of two different reactions are two individuals. In particular, a molecule that is the has input (RO:0002233) of one activity and the enabled by (RO:0002333) of another activity must be represented as two separate individuals of that class — never a single shared instance.

Concrete example: a chaperone folds actin (chaperone activity has input actin), and folded actin then enables a downstream structural molecule activity. Create two actin individuals — one as the chaperone's input, a separate one as the enabler of the downstream activity.

Likewise for BPs: each MF, even if it is part of the same BP as another MF, should be modeled as part of distinct instances of the BP.

Why this matters: an activity unit is anchored on its enabler individual, which includes all its context (BP, CC, input, biological phase). Reusing one individual across multiple roles across different enablers entangles the two activity units so they can no longer be cleanly separated. While the Noctua Graph Editor still draws every raw triple, the Visual Pathway Editor (VPE) — which reconstructs the GO-CAM activity-flow view centered on enabler individuals — silently drops the causal edge between the two activities when elements of the context are shared. Distinct instances make the activities separable and the causal relations rendered correctly.

How to build it with barista: assign a distinct variable per role, e.g.

# chaperone's input: its own actin instance
barista add-individual -m $MODEL --class UniProtKB:P60709 --assign actin_input --session s
barista add-fact -m $MODEL -s chaperone_mf -t actin_input -p RO:0002233 --session s  # has input

# downstream activity's enabler: a SEPARATE actin instance
barista add-individual -m $MODEL --class UniProtKB:P60709 --assign actin_enabler --session s
barista add-fact -m $MODEL -s actin_mf -t actin_enabler -p RO:0002333 --session s    # enabled by

Evidence

All facts MUST be supported with an evidence code and a reference, and the code must reflect what the cited paper actually demonstrates — never over-claim (e.g. IDA for a function that was only inferred). See references/Evidence_and_evidence_codes.md for the code-by-code guide (IDA/IMP/IGI/IPI/IEP/IC/NAS/TAS), when with/from is required or must be empty, reference form, the ISS ortholog-transfer recipe (ECO:0000250 + GO_REF:0000024 with the source ortholog's MOD id in with/from), and how to handle IBA/IEA annotations fetched from AmiGO.

Validation Checklist

Before finalizing a GO-CAM model, verify:

  • The most specific available GO term is used for every MF/BP/CC (prefer child terms over parents)
  • No 'obsolete' term is used in the model
  • No terms in the 'go_check_do_not_annotate' gocheck_do_not_annotate http://purl.obolibrary.org/obo/go#gocheck_do_not_annotate or gocheck_obsoletion_candidate http://purl.obolibrary.org/obo/go#gocheck_obsoletion_candidate subsets
  • All activities have appropriate molecular function term
  • Causal relations match the biological mechanism (direct vs. indirect)
  • 'has input' relations specify the correct, direct targets
  • When the output of a MF is the input of the next MF, only 'has ouput' 'and 'has input' relations should be created, not 'provides input for'. 'Provides input for' is only used when the output and input are not specified.
  • A handoff (the 'has output' of one MF is the 'has input' of the next) uses one shared individual
  • Otherwise no individual is reused across roles: inputs of different reactions, outputs of different reactions, and a molecule that is both a 'has input' and an 'enabled by' each have a separate individual (shared instances break VPE causal-edge rendering); as well, each MF should be linked to a different instance of all contextual information (CC, BPs)
  • Cellular components are specified with 'occurs in', and cells and anatomical parts can be added with the 'part of' relation.
  • Activities are connected to biological processes with 'part of'.
  • Multiple BPs can be nested using the 'part of' relation.
  • All facts have supporting evidence, and each evidence code reflects what the cited paper ACTUALLY shows; e.g. use ISS + GO_REF:0000024 for a MF/BP/CC inferred from sequence similarity rather than asserting IDA from a paper that does not demonstrate it)
  • Protein-containing complex representation follows guidelines
  • Relation directionality is correct (subject → object)

Examples

Example 1: Simple Kinase Activation

# Create model
barista create-model --title "MAPK signaling example"

# Add receptor activity
barista add-individual --model $MODEL_ID --class GO:0004888 --assign receptor

# Add kinase activity
barista add-individual --model $MODEL_ID --class GO:0004674 --assign kinase

# Connect with causal relationship
barista add-fact --model $MODEL_ID \
  --subject receptor --object kinase \
  --predicate RO:0002629  # directly positively regulates

Example 2: Transcription Factor with Target Gene

# Add transcription activator activity
barista add-individual --model $MODEL_ID \
  --class GO:0001228 --assign tf_activity  # DNA-binding transcription activator

# Specify the target gene as input
barista add-fact --model $MODEL_ID \
  --subject tf_activity \
  --object <gene-id> \
  --predicate RO:0002233  # has input

# Add the target gene's molecular function
barista add-individual --model $MODEL_ID \
  --class <target-mf> --assign target_activity

# Connect TF to target activity (indirect regulation)
barista add-fact --model $MODEL_ID \
  --subject tf_activity \
  --object target_activity \
  --predicate RO:0002407  # indirectly positively regulates

Tips for Effective GO-CAM Modeling

  1. Start simple: Begin with core activities and expand incrementally
  2. Use variables: Assign readable names to individuals for easier reference
  3. Consult examples: Refer to example models in the guidelines
  4. Be specific: Use the most specific GO term and relation available
  5. Document evidence: Always include supporting references
  6. Test first: Use test server before committing to production
  7. Review guidelines: Load relevant reference files before annotating complex cases
  8. Think causally: Focus on how activities mechanistically affect each other

Common Mistakes to Avoid

  • Using obsolete terms
  • Using terms from the 'go_check_do_not_annotate' or gocheck_obsoletion_candidate subsets
  • Using 'has input' to specify a ligand for a receptor (should use causal relation instead)
  • Using direct regulation when the mechanism is multi-step (use indirect)
  • Forgetting to specify cellular location with 'occurs in'
  • Creating activities without connecting them to biological processes
  • Missing evidence codes and references
  • Using generic terms when specific child terms are available
  • Incorrect causal relation directionality
  • Reusing one individual for both a 'has input' and an 'enabled by' role (create a distinct individual per role, even for the same molecular entity — see "Distinct Individuals for Distinct Roles")
  • Likewise for BPs: each MF should be connected to a distinct instance of a BP
  • Capturing chemicals that are not primary inputs or outputs
  • Choosing an evidence code for convenience rather than matching what the paper demonstrates (over-claiming IDA for functions that are actually known/inferred; double check what data the paper shows)
  • Leaving an activity (MF individual) with no enabled_by (Noctua validation error)
  • Adding a has output when the has input is a gene product (use directly regulates instead)
  • Using UniProtKB for a model-organism gene product (use the MOD id: MGI/RGD/ZFIN/...); human is the exception
  • Representing one compound with two different CHEBI ids across a handoff (breaks the chain)
  • Splitting a handoff into two individuals (the output of one MF and the input of the next are one individual)
  • Sharing one individual between the inputs (or the outputs) of two different reactions
  • Placing a reaction byproduct on the wrong activity (e.g. the fatty acid from a ceramidase on a neighbouring chaperone)
  • Over-claiming IDA for a function the paper does not demonstrate (use ISS with the right reference or IC)
  • Citing a bare DOI instead of a PMID

Getting Help

  • Check relevant guideline files in references/ directory
  • Search for similar examples using barista list-models
  • Export and examine well-annotated models for patterns
  • Consult the GO Consortium documentation
  • Review the noctua-py documentation at https://github.com/geneontology/noctua-py

Reference Files Summary

Load these files from the references/ directory as needed:

Cross-cutting references (apply to most models):

  • GO-CAM_annotation_guidelines_README.md
  • How_to_annotate_complexes_in_GO-CAM.md
  • Gene_product_identifiers.md
  • Relation_selection.md
  • Evidence_and_evidence_codes.md

Activity-type guidelines (load when working with that activity type):

  • DNA-binding_transcription_factor_activity_annotation_guidelines.md (also covers transcription coregulator activity)
  • E3_ubiquitin_ligases.md
  • Molecular_adaptor_activity.md
  • Molecular_carrier_activity.md
  • Sequestering_activity.md
  • Enzyme_regulator_activity.md
  • Signaling_receptor_activity_annotation_guidelines.md
  • Transporter_activity_annotation_annotation_guidelines.md

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.