Getting Started

This guide will walk you through setting up Goldsmith and creating your first GO-CAM annotation.

Prerequisites

Before you begin, make sure you have:

• Python 3.10 or newer — Download Python
• A terminal — Terminal.app (Mac), Windows Terminal, or any terminal emulator
• A service account key — Ask your team lead (see setup/README.md for details)

Setup

1. Clone the Repository

git clone https://github.com/geneontology/goldsmith.git
cd goldsmith

2. Run Setup

bash setup.sh

The setup script will:

1. Check your Python version
2. Create a virtual environment and install dependencies
3. Check for the GitHub CLI (optional, needed for /go-pr)
4. Configure your Vertex AI credentials
5. Launch Claude Code

Future Sessions

After the first setup, start future sessions with:

source goldsmith.env
claude

Your First Annotation

Once Claude is running, try creating an annotation:

/go-try annotate that human TP53 has protein kinase binding activity from PMID:20154695

Claude will:

1. Identify the gene product (TP53), organism (human), GO term (protein kinase binding), and evidence
2. Look up the correct ontology identifiers
3. Build a GO-CAM model using gocam-py
4. Save the annotation to output/
5. Explain what each field means

Validate Your Annotation

Check that your annotation is structurally correct:

/go-validate

This runs dual validation — LinkML schema validation and Pydantic model checking — and explains any issues in plain language.

Quality Checks

Run deeper quality checks:

/go-check

This verifies GO term existence, evidence code appropriateness, taxon consistency, and flags overly generic terms.

Submit for Review

When you're happy with your annotation:

/go-pr

This walks you through creating a Pull Request, using simple language (no git jargon required).

Workflow Summary

/go-try   →   /go-validate   →   /go-check   →   /go-pr
 Create        Validate            QC              Submit

Each skill is independent — you can use them in any order or skip steps as needed.