I asked Claude to read everyting in OBO Academy:

Read everything related to the ODK in @docs/ and write a perfectly formatted Claude SKILL file for "setting up" and ODK repo

And it came up with this. Maybe we can use this as a starting point for a claude skill moving forward.

---
name: odk-repo-setup
description: Assists users in setting up a new Ontology Development Kit (ODK) repository from scratch. Use this Skill when users need to create a new ODK-managed ontology project, seed an ODK repository, configure project.yaml files, or migrate an existing ontology to the ODK framework. Handles Docker setup verification, project configuration, repository seeding, import module setup, and GitHub/GitLab publishing.
---

ODK Repository Setup Skill

This Skill helps users set up and configure an Ontology Development Kit (ODK) repository for managing OBO-style ontologies. The ODK is a comprehensive system that bundles essential ontology development tools (ROBOT, OWLTools, DOSDP-tools, etc.) and provides standardized workflows for ontology lifecycle management.

Prerequisites Verification

Before starting ODK repository setup, verify the following prerequisites are met:

1. Docker Installation

   • Run docker ps to confirm Docker is installed and running
   • If not installed, guide user to install Docker Desktop:
     • Mac: https://hub.docker.com/editions/community/docker-ce-desktop-mac
     • Windows: https://docs.docker.com/desktop/install/windows-install/
     • Linux: Use distribution-specific package manager

2. Docker Memory Configuration

   • Verify Docker has sufficient memory allocated (minimum 10GB recommended)
   • On Mac/Windows: Check Docker Desktop → Preferences → Resources → Memory
   • Set memory to ~60% of system RAM (e.g., 10-11GB for 16GB system)
   • This is critical to avoid Error 137 and out-of-memory issues

3. ODK Docker Image

   • Pull the latest ODK image: docker pull obolibrary/odkfull
   • This downloads all bundled tools needed for ontology development
   • Verify installation: docker run --rm obolibrary/odkfull robot --version

4. Git Configuration

   • Verify .gitconfig exists with user name and email configured:
     • On Unix/Mac: Check ~/.gitconfig
     • On Windows: Check %userprofile%/.gitconfig
   • If missing, configure with:

     git config --global user.name "Your Name"
     git config --global user.email "your.email@example.org"
     

5. GitHub/GitLab Account

   • Confirm user has access to GitHub or GitLab
   • Verify user knows their GitHub username or organization name

ODK Project Configuration File

The ODK project configuration file (typically named {ontology-id}-odk.yaml) is the central configuration that defines how the ODK manages your ontology. Guide users through creating this file with the following structure:

Essential Configuration Sections

1. Ontology Metadata

id: myonto                           # Lowercase, 4-5 characters, determines file naming
title: "My Ontology"                 # Full ontology title
description: "Description of the ontology purpose and scope"
contact: maintainer@example.org      # Primary contact email
creators:                            # List of creators/maintainers
  - Organization or Person Name
license: https://creativecommons.org/licenses/by/4.0/

2. Git Repository Configuration

github_org: myusername              # GitHub username or organization
git_main_branch: main               # Use "main" for new repos, "master" for legacy
repo: my-ontology                   # Repository name (lowercase with hyphens)

3. CI/CD Configuration

ci:
  - github_actions                  # Enable GitHub Actions for automated QC

4. Release Artifacts Configuration

release_artefacts:
  - base                            # Contains only ontology-native axioms (unclassified)
  - full                            # Includes imports and inferred axioms
  - simple                          # Simplified version for basic use
primary_release: full               # The main release file users will access
export_formats:
  - owl                             # OWL format (always include)
  - obo                             # OBO format (optional, for OBO Foundry)
  - json                            # OBOGraphs JSON (optional)

5. Import Configuration

import_group:
  products:
    - id: ro                        # Relation Ontology (relations/properties)
    - id: pato                      # Phenotype And Trait Ontology
    - id: omo                       # OBO Metadata Ontology
      module_type: mirror           # Import entire ontology (for metadata)
    - id: chebi                     # Chemical Entities of Biological Interest
      is_large: true                # Mark large ontologies
      use_gzipped: true             # Use compressed version
      make_base: true               # Create base import without imports

6. Memory and Resource Configuration

robot_java_args: '-Xmx8G'           # Max RAM for ROBOT (should be ~20% less than Docker limit)

7. ROBOT Report Configuration

robot_report:
  use_labels: TRUE                  # Use labels in report for readability
  fail_on: ERROR                    # Fail build if ERROR-level violations found
  custom_profile: TRUE              # Use custom quality control profile
  report_on:
    - edit                          # Run report on edit file

Import Module Configuration Options

When configuring imports, explain these key parameters:

• module_type: Controls how the import is created

  • slme (default): SLME-BOT extraction (recommended for most cases)
  • mirror: Import entire ontology as-is
  • custom: Use custom ROBOT commands in Makefile

• module_type_slme: Refinement of SLME extraction method

  • BOT (default): Bottom module (includes subclasses)
  • TOP: Top module (includes superclasses)
  • STAR: Star module (includes related terms)

• is_large: Boolean flag for ontologies that require special handling (NCBITaxon, ChEBI)

• use_gzipped: Boolean to use gzipped versions of large ontologies

• make_base: Boolean to create base import without nested imports

• use_base: Boolean to import from base file instead of full release

Seeding the ODK Repository

Once the project configuration file is created, seed the repository:

Using seed-via-docker script

For Unix/Mac:

# Download seed script (or use existing one)
wget https://raw.githubusercontent.com/INCATools/ontology-development-kit/master/seed-via-docker.sh

# Make executable
chmod +x seed-via-docker.sh

# Seed repository with config file
./seed-via-docker.sh -c -C myonto-odk.yaml

For Windows:

# Download seed-via-docker.bat
# Ensure seed-via-docker.bat is in working directory

# Seed repository with config file
seed-via-docker.bat -c -C myonto-odk.yaml

Important flags:

• -C <config-file>: Specifies the project configuration file
• -c: Clean flag - removes any previous seeding attempt before creating new one

Seeding Process Expectations

Set user expectations about the seeding process:

• First run may take 5-30 minutes depending on import dependencies
• Large imports (ChEBI, NCBITaxon) can take significant time to download
• Process may appear stalled while downloading imports in background
• Output is created in target/{ontology-id}/ directory
• Initial git repository is created with first commit already made

Troubleshooting Common Seeding Issues

1. No Git Configuration

• Symptoms: Error about missing git config
• Solution: Ensure .gitconfig file exists with user.name and user.email
• Alternative: Set environment variables:

  ODK_GITNAME="Your Name" ODK_GITEMAIL="your@email.org" ./seed-via-docker.sh -C config.yaml
  

2. Spaces in User Path

• Symptoms: Errors when working directory path contains spaces
• Solution: Move to directory without spaces in path (e.g., avoid "Dropbox (Personal)")

3. Wrong File Extensions (Windows)

• Symptoms: Files named project.yaml.txt or seed-via-docker.bat.txt
• Solution: Verify and rename files to remove extra .txt extension

4. Permission Issues with target/ directory

• Symptoms: Cannot delete or modify target/ directory
• Cause: Directory owned by root user inside Docker container
• Solution: May need sudo/admin rights to delete: sudo rm -rf target/

Repository Structure After Seeding

After successful seeding, explain the generated repository structure:

myonto/
├── src/
│   ├── ontology/                   # Main ontology development directory
│   │   ├── myonto-edit.owl        # Editor file (edit this in Protégé)
│   │   ├── myonto-odk.yaml        # ODK configuration (for updates)
│   │   ├── run.sh                 # ODK wrapper script (Unix/Mac)
│   │   ├── run.bat                # ODK wrapper script (Windows)
│   │   ├── Makefile               # Generated build rules
│   │   ├── catalog-v001.xml       # XML Catalog for import resolution
│   │   ├── imports/               # Import modules directory
│   │   │   ├── ro_terms.txt       # List of RO terms to import
│   │   │   ├── ro_import.owl      # Generated RO import module
│   │   │   └── ...                # Other imports
│   │   └── mirror/                # Cached copies of source ontologies
│   └── metadata/                   # OBO Foundry metadata files
├── .github/
│   └── workflows/
│       └── qc.yml                 # GitHub Actions QC workflow
├── README.md                       # General README
└── README-editors.md              # Editor-specific instructions

Publishing to GitHub/GitLab

Guide users through publishing their seeded repository:

Option 1: Using GitHub Desktop (Recommended for beginners)

1. Open GitHub Desktop
2. Select File → Add Local Repository
3. Navigate to and select the target/{ontology-id} directory
4. Click "Publish repository"
5. Deselect "Keep this code private" if creating public repository
6. Select correct organization from dropdown if applicable
7. Click "Publish repository"

Note: GitHub may request additional permissions to push workflow files (.github/workflows/*)

Option 2: Using Command Line

1. Create new repository on GitHub/GitLab:

   • GitHub: https://github.com/new
   • GitLab: https://gitlab.com/projects/new
   • Do NOT initialize with README (already exists)
   • Repository name must match config (lowercase with hyphens)

2. Push to remote from command line:

   cd target/myonto
   git remote add origin https://github.com/username/myonto.git
   git branch -M main
   git push -u origin main
   

Post-Publishing Steps

1. Enable GitHub Actions (if using GitHub)

   • Go to repository → Actions tab
   • Enable workflows if prompted
   • QC workflow will run automatically on commits

2. Move Repository (optional)

   • Can move target/myonto to preferred location
   • Recommend organizing in workspace directory (e.g., ~/git/ or ~/workspace/)

3. Review README-editors.md

   • Located in root of repository
   • Contains customized instructions for ontology editors
   • Includes information on editing workflow and release process

Configuring ID Ranges

After repository setup, configure ID ranges for term creation:

1. Locate ID ranges file: src/ontology/{ontology-id}-idranges.owl

2. Edit file to assign ID ranges to curators:

   Datatype: idrange:1
   Annotations: allocatedto: "Curator Name"
   EquivalentTo: xsd:integer[>= 0000001, <= 0010000]
   

3. Protégé 5.6+ Configuration (automatic):

   • Protégé automatically reads idranges file
   • Matches Protégé username to allocatedto field
   • Automatically sets ID range for user

4. Protégé 5.5 and below (manual):

   • Preferences → New Entities tab
   • Configure IRI generation and numeric ID settings
   • Set Start and End values from idranges file

Setting Up Import Modules

After seeding, import modules need to be built:

Populating Import Term Lists

For each import configured in project.yaml, populate the term list file:

Example: src/ontology/imports/iao_terms.txt

http://purl.obolibrary.org/obo/IAO_0000115 # definition
http://purl.obolibrary.org/obo/IAO_0000136 # is about
http://purl.obolibrary.org/obo/IAO_0000118 # alternative term

Format Rules:

• One term IRI per line
• Optional comment after # for human readability
• Full IRI required (not CURIE notation)

Building Import Modules

Navigate to src/ontology/ directory and use one of these commands:

Refresh all imports:

sh run.sh make refresh-imports

Refresh single import:

sh run.sh make refresh-ro        # Replace 'ro' with import ID

Refresh without re-downloading mirrors:

sh run.sh make no-mirror-refresh-imports      # All imports
sh run.sh make no-mirror-refresh-ro           # Single import

For large ontologies only (excluding large imports):

sh run.sh make refresh-imports-excluding-large

Import Module Troubleshooting

If import module contains unwanted terms or missing necessary terms:

1. Try different module_type_slme values in project.yaml:

   • Change from BOT to TOP or STAR
   • Re-run sh run.sh make update_repo to regenerate Makefile
   • Rebuild import: sh run.sh make refresh-{import-id}

2. Use module_type: custom for full control:

   • Define custom ROBOT extraction in {ontology-id}.Makefile
   • Requires understanding of ROBOT extract/filter/remove commands
   • See: http://robot.obolibrary.org/extract

3. Verify in Protégé:

   • Reload editor file after refreshing imports
   • Check imported terms are present with expected axioms
   • Ensure no unwanted terms are included

Initial Editing Workflow

Guide users through their first editing session:

1. Open Editor File in Protégé

   # Start Protégé (version 5.6.0+ recommended)
   # Open: src/ontology/{ontology-id}-edit.owl
   

2. Verify Imports Loaded

   • Check Active Ontology tab shows import modules
   • Imported terms should be visible but not editable

3. Configure Protégé Settings

   • Set ID range (if Protégé 5.5 or below)
   • Configure rendering settings as preferred

4. Make Initial Edits

   • Add terms, annotations, axioms as needed
   • Save frequently (Ctrl+S / Cmd+S)

5. Run Local QC Checks

   cd src/ontology
   sh run.sh make test              # Run all QC checks
   

Preparing and Managing Releases

When ready to create the first release:

Release Preparation

cd src/ontology
sh run.sh make prepare_release

This command:

• Builds all configured release artifacts (base, full, simple)
• Exports to configured formats (OWL, OBO, JSON)
• Runs quality control checks
• Creates versioned release files
• Generates release notes

Release Artifacts Explanation

Explain to users what each artifact is:

• base (myonto-base.owl): Only native ontology axioms, no imports, unclassified

  • Use for: Understanding what's actually in the ontology
  • Not recommended for: End users

• full (myonto.owl): Includes imports and inferred axioms from reasoner

  • Use for: Standard distribution, applications, end users
  • Default primary release

• simple (myonto-simple.owl): Simplified version with reduced complexity

  • Use for: Simple applications, visualization, training

Creating GitHub Release

After successful prepare_release:

1. Commit and push all changes including release files
2. Create GitHub release:
   • Go to repository → Releases → Create new release
   • Tag version: v{YYYY-MM-DD} (e.g., v2024-01-15)
   • Title: "{Ontology Name} {version}"
   • Upload release files from src/ontology/ directory
3. OBO Foundry submission (if applicable):
   • Update metadata in src/metadata/ directory
   • Create pull request to OBO Foundry registry

Frequently Used ODK Commands

Provide users with this command reference:

# Navigate to ontology directory first
cd src/ontology

# Update ODK to latest version
sh run.sh make update_repo          # Run twice (first may fail)

# Refresh imports
sh run.sh make refresh-imports      # All imports
sh run.sh make refresh-{id}         # Single import (e.g., refresh-ro)

# Prepare release
sh run.sh make prepare_release

# Run QC checks
sh run.sh make test

# Check ODK version
sh run.sh make odkversion

# Update documentation
sh run.sh make update_docs

# Validate OWL profile
sh run.sh make validate_profile_myonto-edit.owl

Memory Management

If users encounter memory issues (Error 137, OutOfMemory):

Diagnosis

• Error 137: Docker memory limit exceeded
• OutOfMemory: Java memory limit exceeded OR Docker limit exceeded

Solutions

1. Increase Docker Memory

• Docker Desktop → Preferences → Resources → Memory
• Set to ~60% of system RAM
• Should be ~20% more than robot_java_args setting

2. Adjust ROBOT Java Memory

• Edit src/ontology/{ontology-id}-odk.yaml:

  robot_java_args: '-Xmx10G'      # Increase from 8G to 10G
  

• Run sh run.sh make update_repo to apply changes
• Docker memory must accommodate this + ~20% overhead

3. Optimize Pipeline Design

• Separate robot query commands (loads ontology twice in memory)
• Use robot reason only at end of pipeline
• Avoid reduce and materialise on large ontologies when possible

Migrating Existing Ontology to ODK

If user has existing ontology to migrate:

Pre-migration Preparation

1. Convert to OFN format (recommended):

   # Using ODK Docker directly
   docker run --rm -v $PWD:/work -w /work obolibrary/odkfull \
     robot convert --input myonto.owl --format ofn --output myonto.ofn
   

2. Analyze external dependencies:

   • Review term declarations in OFN format
   • Identify namespaces of external terms (e.g., obo:RO_, obo:BFO_)
   • List ontologies to include in import_group configuration

Migration Process

1. Create ODK config file including all identified imports
2. Seed new ODK repository
3. Copy native terms from old OFN file to {ontology-id}-edit.owl
   • Copy term declarations
   • Copy class definitions
   • Copy all axioms for native terms only
4. Populate import term list files with external terms
5. Build import modules: sh run.sh make refresh-imports
6. Verify in Protégé that all terms are present
7. Test release: sh run.sh make prepare_release

Adding New Import After Migration

If user needs to add import dependency later:

1. Add to import_group in src/ontology/{ontology-id}-odk.yaml
2. Run sh run.sh make update_repo to regenerate Makefile
3. Add import declaration to catalog-v001.xml
4. Add import statement to editor file in Protégé
5. Create and populate imports/{new-import}_terms.txt
6. Build import: sh run.sh make refresh-{new-import}

Updating ODK Version

When new ODK version is released:

1. Pull latest ODK image:

   docker pull obolibrary/odkfull
   

2. Update repository (run twice):

   cd src/ontology
   sh run.sh make update_repo
   sh run.sh make update_repo        # Yes, twice - first may fail
   

3. Update GitHub Actions workflow:

   • Edit .github/workflows/qc.yml
   • Update container version: container: obolibrary/odkfull:v{version}
   • Check latest version: https://hub.docker.com/r/obolibrary/odkfull/tags

4. Review and test changes:

   • Create new branch for ODK update
   • Run sh run.sh make test to verify QC passes
   • Create PR and wait for CI to pass before merging

5. Notify other developers to pull latest ODK image

Documentation and Support Resources

Point users to these resources:

• ODK GitHub Repository: https://github.com/INCATools/ontology-development-kit
• ODK Documentation: https://incatools.github.io/ontology-development-kit/
• Project Schema: http://incatools.github.io/ontology-development-kit/project-schema/
• ROBOT Documentation: http://robot.obolibrary.org/
• OBO Foundry: http://obofoundry.org/
• ODK Slack Channel: #ontology-development-kit on OBO Community Slack

Common Pitfalls and Tips

General Tips

• Always run sh run.sh make test before committing changes
• Keep imports focused - only import terms you actually use
• Use meaningful commit messages following conventional commits style
• Read README-editors.md in your repository - it's customized for your setup
• Backup your editor file before major changes

Common Mistakes to Avoid

1. Editing release files directly: Always edit {ontology-id}-edit.owl, never release files
2. Skipping QC: Always run tests before pushing - CI failures delay work
3. Forgetting to update imports: When adding terms from new ontology, update imports
4. Insufficient Docker memory: Causes cryptic errors - always set properly
5. Not reading ODK update notes: Breaking changes may require configuration updates

Workflow Summary

Provide this concise workflow checklist:

• [ ] Install and configure Docker (memory: 10GB+)
• [ ] Pull ODK image: docker pull obolibrary/odkfull
• [ ] Configure Git with user.name and user.email
• [ ] Create ODK project configuration YAML file
• [ ] Download seed script appropriate for OS
• [ ] Seed repository: ./seed-via-docker.sh -c -C config.yaml
• [ ] Publish to GitHub/GitLab using preferred method
• [ ] Configure ID ranges in idranges file
• [ ] Populate import term lists
• [ ] Build imports: sh run.sh make refresh-imports
• [ ] Open editor file in Protégé and begin editing
• [ ] Run QC: sh run.sh make test
• [ ] Commit and push changes
• [ ] Prepare release: sh run.sh make prepare_release

Examples

Example 1: Minimal New Ontology Setup

User wants to create minimal ontology for tracking research protocols:

id: repo
title: "Research Protocol Ontology"
github_org: myusername
git_main_branch: main
repo: research-protocol-ontology
release_artefacts:
  - base
  - full
primary_release: full
export_formats:
  - owl
import_group:
  products:
    - id: omo
      module_type: mirror
    - id: obi
robot_java_args: '-Xmx8G'

Minimal configuration imports only metadata ontology (OMO) and biomedical investigations ontology (OBI).

Example 2: Large Ontology with Many Dependencies

User migrating chemistry ontology with many dependencies:

id: chemonto
title: "Chemistry Ontology"
github_org: chemistry-ontologies
git_main_branch: main
repo: chemistry-ontology
release_artefacts:
  - base
  - full
  - simple
primary_release: full
export_formats:
  - owl
  - obo
  - json
import_group:
  products:
    - id: bfo
      module_type: mirror
    - id: ro
      use_base: true
    - id: omo
      module_type: mirror
    - id: chebi
      is_large: true
      use_gzipped: true
      make_base: true
    - id: pato
    - id: iao
robot_java_args: '-Xmx12G'
robot_report:
  use_labels: TRUE
  fail_on: ERROR
  report_on:
    - edit

Configuration includes large ontology (ChEBI) with compression, higher memory allocation, and comprehensive QC.

Notes on Operating System Differences

Windows-Specific Considerations

• Use seed-via-docker.bat instead of seed-via-docker.sh
• Use run.bat instead of run.sh for ODK commands
• Git config location: %userprofile%/.gitconfig
• Command prompt or PowerShell both work
• WSL (Windows Subsystem for Linux) recommended for better experience
• File permission issues less common than on Linux

Mac/Linux-Specific Considerations

• Use seed-via-docker.sh and run.sh scripts
• May need chmod +x to make scripts executable
• Git config location: ~/.gitconfig
• Target directory ownership issues more common (Docker runs as root)
• Can use wrapper script for ODK commands system-wide

Conclusion

When helping users set up ODK repositories:

1. Verify prerequisites before starting
2. Guide through configuration file creation carefully
3. Explain each configuration option's purpose
4. Set realistic expectations for seeding time
5. Provide troubleshooting steps for common issues
6. Ensure successful publishing to Git hosting
7. Confirm import modules build successfully
8. Guide through first editing session
9. Provide reference for common commands
10. Direct to support resources for ongoing help