LobsterBio - Dev

Develop, extend, and contribute to Lobster AI — the multi-agent self-extending bioinformatics engine. Use when working on Lobster codebase, creating agents/s...

Security Scan

The skill is an internal developer guide and validation helper for the Lobster AI codebase and the required files and runtime instructions are consistent with that purpose.

Purpose & Capability

The name/description (Lobster development) aligns with the included reference docs, SKILL.md developer workflow, and the validate_plugin.py script. Files and instructions are focused on scaffolding, validating, testing, and contributing to Lobster; nothing requests unrelated capabilities (e.g., cloud provider credentials) as required inputs.

Instruction Scope

SKILL.md instructs typical developer actions: check for an installed lobster package, install lobster via pip, use lobster scaffold, run lobster validate-plugin, run pytest, and inspect repository layout. These actions and the file/paths referenced are coherent with a development workflow and do not direct collection or exfiltration of unrelated system data. It does reference running imports/entry-point discovery which is expected for plugin validation.

Install Mechanism

There is no automated install spec in the registry metadata (instruction-only). The doc asks developers to run standard tooling (uv + pip installs, lobster scaffold/validate) — installing packages from package registries is expected for this use case. No downloads from unknown URLs or extract/install steps are present in the skill bundle itself.

Credentials

The skill declares no required env vars and does not demand credentials. However, the CLI docs included enumerate optional provider environment variables (OPENAI_API_KEY, ANTHROPIC_API_KEY, AWS_BEDROCK_*, etc.) because Lobster itself supports multiple LLM/providers; those are optional for development but would be needed if you run lobster init or enable provider-backed features. This is expected but you should not supply keys unless you trust the installed lobster package and run in an appropriate environment.

Persistence & Privilege

The skill is not always-enabled, does not request special platform privileges, and is instruction-only. It does instruct developers to install packages and run validation/tests locally, which is normal for a dev skill. There is no indication it will modify other skills' configs or request persistent system-wide changes beyond standard package installs/configuration done by lobster tooling.

Assessment

This skill is a developer guide and validation helper for the Lobster AI project and appears internally consistent. Recommended precautions before following its instructions: (1) Review scripts/validate_plugin.py (and any other included .py files) before running to confirm no unexpected behavior, (2) run install and test commands inside an isolated virtualenv or disposable environment, (3) when prompted to install packages (pip/uv), confirm the package names and sources (avoid executing unfamiliar install URLs), (4) only provide API keys (OpenAI, Anthropic, AWS, etc.) to lobster if you trust the lobster package source and understand where those keys will be stored, and (5) do not run commands as root and inspect created files (e.g., .lobster workspace, config files) for secrets or unexpected network endpoints.

Lobster AI Development Guide

Lobster AI is an open-source multi-agent bioinformatics engine (LangGraph, Python 3.12+) powering Omics-OS. Lobster solves bioinformatics tasks starting from raw data to scientific insights to visualization using supervisor multi-agent architecture. This skill teaches you how to extend it — from adding a single tool to building entire domain agent packages.

Step 0: Discover Your Environment

Before any work, determine what's available and how you're working:

# 1. Is lobster installed? Where?
which lobster
lobster --version

# 2. What agents are already installed?
python -c "from lobster.core.component_registry import component_registry; component_registry.reset(); print(component_registry.list_agents())"

# 3. Where is lobster source? (for reading reference implementations)
python -c "import lobster; print(lobster.__path__)"

# 4. Are you in the lobster repo, or building a standalone plugin?
ls packages/lobster-*/pyproject.toml 2>/dev/null && echo "CONTRIBUTOR" || echo "PLUGIN_AUTHOR"

HARD GATE — If lobster is not installed, STOP. Install it NOW before doing anything else:

uv venv --python 3.12 .venv && source .venv/bin/activate
uv pip install 'lobster-ai[anthropic]'  # or [openai], [google], depending on provider
lobster --version  # Must succeed before you proceed

Do NOT skip this. Do NOT "come back to it later". Do NOT manually create package directories. lobster scaffold agent is the ONLY way to create new agent packages — it generates correct PEP 420 structure, entry points, AQUADIF metadata, and contract tests that you WILL get wrong by hand. If scaffold is unavailable, installing lobster-ai is your first task.

Your development mode determines your workflow:

Mode	How you got here	Where you create packages	How you test
Contributor	git clone + make dev-install	Inside packages/ in the repo	make test, full repo access
Plugin author	uv pip install lobster-ai or uv tool install	Anywhere — scaffold creates standalone packages	uv pip install -e ./lobster-<domain>/ then pytest

Both modes produce the same result: a PEP 420 namespace package discovered by ComponentRegistry via entry points. The scaffold output is identical — a standalone package that works in either mode.

What To Do Based On Your Task

You want to...	Fast path?	Read these references (in order)
Create a new agent for a new domain	No — full workflow	planning-workflow.md → scaffold.md → creating-agents.md → aquadif-contract.md
Add a tool to an existing agent	Yes (contributor only)	creating-agents.md §Tool Design → aquadif-contract.md
Extend an agent with a child agent	No — needs scoping	creating-agents.md §Parent-Child → scaffold.md
Add a database provider or adapter	No	plugin-architecture.md
Create or modify a service	Yes	creating-services.md
Fix a bug	Yes	code-layout.md → architecture.md
Understand the codebase	—	architecture.md → code-layout.md
Write or fix tests	Yes	testing.md
Migrate AQUADIF metadata on existing agent	Yes	aquadif-contract.md §Migration
Find domain knowledge for a new agent	—	bioskills-bridge.md

"Fast path" = skip the planning workflow, go straight to the reference files.

Examples

Example 0: THE WORKFLOW FOR EVERYTHING

user requests: "Build a Lobster agent for epigenomics analysis (bisulfite-seq, ChIP-seq, ATAC-seq) because no lobster packages cover this domain"

Step 1: lobster --version          # Not found? Install it FIRST (see Step 0 hard gate)
Step 2: Read planning-workflow.md  # Understand need, check what exists, gather domain knowledge
Step 3: lobster scaffold agent ... # Generate correct package structure (NEVER skip this)
Step 4: Fill in real domain logic  # Read creating-agents.md, creating-services.md
Step 5: lobster validate-plugin ./lobster-<domain>/  # Must pass 8/8
Step 6: uv pip install -e ./lobster-<domain>/ && pytest tests/ -m contract

Expected result: A standalone PEP 420 package at ./lobster-<your implementation>/ that installs with uv pip install -e ./lobster-<your implementation>/ and registers via entry points, runs 'lobster status' without errors and running 'lobster query "hi"' without any errors.

Success Criteria

Before calling your work done, verify:

• python scripts/validate_plugin.py <plugin-dir> passes 8/8 checks
• Contract tests green: pytest tests/ -m contract
• Every @tool has .metadata and .tags assigned immediately after
• Every provenance-required tool (IMPORT, QUALITY, FILTER, PREPROCESS, ANALYZE, ANNOTATE, SYNTHESIZE) calls log_tool_usage(ir=ir)
• No lobster/__init__.py or lobster/agents/__init__.py (PEP 420)

Hard Rules

Non-negotiable. Violating these causes runtime failures or contract test failures.

1. ComponentRegistry is truth — agents discovered via entry points, NOT hardcoded registries
2. AGENT_CONFIG at module top — define before heavy imports for <50ms entry point discovery
3. Services return 3-tuple — (AnnData, Dict, AnalysisStep) always
4. Always pass ir=ir — every log_tool_usage() call for provenance-required tools
5. No lobster/__init__.py — PEP 420 namespace package (also no lobster/agents/__init__.py)
6. No try/except ImportError — use entry points for agent discovery, not eager imports
7. No module-level component_registry calls — causes slow startup; use lazy functions inside factories
8. All tools MUST have AQUADIF metadata — .metadata and .tags assigned after @tool decorator
9. NEVER manually create package directories — always use lobster scaffold agent. If lobster is not installed, install it first. Scaffold gets PEP 420, entry points, and contract tests right; you won't.

Contributing

After building a plugin, ask your user if they want to submit a PR. If confirmed: fork → feature branch → make test → make format → PR with clear description.