ecological-agent-skills 3.1.0

package/README.md

@@ -0,0 +1,347 @@
+# ecological-agent-skills
+
+[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
+
+A curated, agent-agnostic skill library for **quantitative ecology** workflows, designed for use with any AI coding agent.
+
+**17 modular skills** | **13 multi-step workflows** | **58 R/Python scripts** | **14 worked examples across 6 continents**
+
+---
+
+## Table of Contents
+
+- [New Here? Start Here!](#new-here-start-here)
+- [Installation](#installation)
+- [Core Concepts](#core-concepts)
+- [Skills (17)](#skills-17)
+- [Workflows (13)](#workflows-13)
+- [How to Use Skills](#how-to-use-skills)
+- [For AI Agents](#for-ai-agents)
+- [Examples (14)](#examples-14)
+- [Documentation](#documentation)
+- [Implementation Roadmap](#implementation-roadmap)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
+## New Here? Start Here!
+
+**What is this?** A collection of structured Markdown instructions (skills) that teach AI agents how to perform quantitative ecology analyses — from cleaning GBIF data to running species distribution models, occupancy analysis, PVA, and conservation prioritization.
+
+**Who is it for?** Ecologists, conservation biologists, and environmental scientists who use AI coding agents to assist with data analysis in R or Python.
+
+**1-minute quick start:**
+
+```bash
+# 1. Clone the repository
+git clone https://github.com/baratadiego/ecological-agent-skills.git
+
+# 2. Tell your agent about it (example for Claude Code)
+cd ecological-agent-skills
+# The agent reads AGENT_CONTEXT.md and skills/SKILL_INDEX.json automatically
+
+# 3. Ask your agent to run an analysis
+```
+
+```
+Use the species-distribution-modeling skill to build a MaxEnt model
+for Panthera onca in the Amazon biome using WorldClim v2.1 predictors.
+```
+
+**That's it.** The agent reads the skill instructions, follows the decision points, runs the R/Python scripts, and produces validated outputs with full reproducibility tracking.
+
+**Pick a starting workflow:**
+
+| Your goal | Workflow to run |
+|-----------|----------------|
+| Model where a species occurs | `run-sdm-study` |
+| Estimate occupancy from camera traps | `run-camera-trap-occupancy` |
+| Assess impact of a disturbance | `assess-ecological-impact` |
+| Compare community composition | `analyze-community-structure` |
+| Identify conservation priority areas | `run-conservation-prioritization` |
+
+---
+
+## Installation
+
+### Option A: npx (recommended)
+
+```bash
+npx ecological-agent-skills --claude
+```
+
+One command. Clones the repository, copies skills to the right location for your agent, and prints next steps.
+
+### Option B: Git clone
+
+```bash
+git clone https://github.com/baratadiego/ecological-agent-skills.git
+```
+
+### Option C: Download ZIP
+
+Download from [Releases](https://github.com/baratadiego/ecological-agent-skills/releases) and extract to your preferred location.
+
+---
+
+### Choose Your Tool
+
+| Tool | Install command |
+|------|----------------|
+| **Claude Code** | `npx ecological-agent-skills --claude` |
+| **Gemini CLI / Antigravity** | `npx ecological-agent-skills --gemini` |
+| **Cursor** | `npx ecological-agent-skills --cursor` |
+| **GitHub Copilot** | `npx ecological-agent-skills --copilot` |
+| **Codex CLI** | `npx ecological-agent-skills --codex` |
+| **Custom path** | `npx ecological-agent-skills --path ./my-skills` |
+
+**What each flag does:**
+
+| Flag | Install path | Notes |
+|------|-------------|-------|
+| `--claude` | `.claude/skills/ecological-agent-skills/` | Project-local. Add reference to `CLAUDE.md` |
+| `--gemini` | `~/.gemini/ecological-agent-skills/skills/` | Global. Auto-discovered by Gemini CLI |
+| `--cursor` | `.cursor/skills/ecological-agent-skills/` | Project-local. Add reference to `.cursor/rules/` |
+| `--copilot` | `.github/skills/ecological-agent-skills/` | Project-local. Reference in `copilot-instructions.md` |
+| `--codex` | `.codex/skills/ecological-agent-skills/` | Project-local |
+| `--path <dir>` | Custom directory | For any agent or manual setup |
+
+### Manual setup per agent
+
+If you prefer to clone manually, here's how to wire it up for each tool:
+
+| Agent Framework | Setup after cloning |
+|----------------|---------------------|
+| **Claude Code** | Add to `CLAUDE.md`: `Read AGENT_CONTEXT.md from ecological-agent-skills/ before any ecology task` |
+| **Gemini CLI** | Move to `~/.gemini/ecological-agent-skills/skills/` — auto-discovered |
+| **Cursor** | Add to `.cursor/rules/`: `Read AGENT_CONTEXT.md from ecological-agent-skills/ before any ecology task` |
+| **GitHub Copilot** | Reference in `.github/copilot-instructions.md` |
+| **Windsurf** | Reference in `.windsurfrules` |
+| **Any agent** | Point the agent to `AGENT_CONTEXT.md` directly |
+
+### Environment setup (for running R/Python scripts)
+
+```bash
+# Python + R environment via conda
+conda env create -f environment.yaml
+conda activate eco-skills
+
+# R packages via renv (inside R session)
+renv::restore()
+```
+
+---
+
+## Core Concepts
+
+**Skills** are self-contained analysis modules. Each skill lives in its own directory with:
+- `SKILL.md` — instructions the agent reads before executing
+- `resources/` — reference guides, checklists, decision tables
+- `scripts/` — R and Python scripts the agent can run
+- `examples/` — worked examples and prompt templates
+
+**Workflows** chain multiple skills into end-to-end pipelines (e.g., data cleaning → modeling → validation → reporting).
+
+**Decision Points** are built into every skill and workflow — conditional logic that tells the agent what to do when AUC is too low, sample size is insufficient, or assumptions are violated.
+
+---
+
+## Skills (17)
+
+### Foundation (Phase 1)
+
+| # | Skill | Domain |
+|---|-------|--------|
+| 1 | `ecological-data-foundation` | Data ingestion, QA, schema |
+| 2 | `geoprocessing-for-ecology` | CRS, raster, vector, spatial ops |
+| 3 | `biostatistics-workbench` | Tests, GLM/GLMM, effect sizes |
+| 4 | `predictive-modeling-best-practices` | CV, tuning, leakage, collinearity |
+| 12 | `reproducible-ecology-pipeline` | Traceability, audit, checklist |
+
+### Modeling (Phase 2)
+
+| # | Skill | Domain |
+|---|-------|--------|
+| 5 | `model-validation-and-uncertainty` | Metrics, calibration, sensitivity |
+| 6 | `species-distribution-modeling` | SDM/ENM full pipeline |
+| 9 | `ecological-impact-assessment` | BACI, fragmentation, pressure |
+| 10 | `environmental-time-series` | Trend, seasonality, breakpoint |
+
+### Specialist (Phase 3)
+
+| # | Skill | Domain |
+|---|-------|--------|
+| 7 | `occupancy-and-detection` | Occupancy models, detectability |
+| 8 | `community-ecology-ordination` | NMDS, PCA, diversity, clustering |
+| 11 | `ecosystem-services-assessment` | ES indicators, valuation |
+
+### Advanced (Phase 4)
+
+| # | Skill | Domain |
+|---|-------|--------|
+| 13 | `camera-trap-processing` | Detection events, RAI, diel activity, Dhat4 overlap |
+| 14 | `acoustic-monitoring` | ACI/NDSI indices, BirdNET detection, soundscape ecology |
+| 15 | `landscape-connectivity` | IIC, PC, dPC, Circuitscape, resistance surfaces |
+| 16 | `population-viability-analysis` | Leslie/Lefkovitch lambda, stochastic PVA, IUCN Criterion E |
+| 17 | `spatial-prioritization` | prioritizr ILP, 30x30 targets, BLM calibration, irreplaceability |
+
+See [CATALOG.md](CATALOG.md) for full metadata, inputs, outputs, and workflow linkages.
+
+---
+
+## Workflows (13)
+
+| Workflow | Skills Used | Purpose |
+|----------|-------------|---------|
+| `run-sdm-study` | 1 → 2 → 4 → 6 → 5 → 12 | Species distribution modeling |
+| `assess-ecological-impact` | 1 → 2 → 9 → 3 → 5 → 12 | BACI impact analysis |
+| `analyze-community-structure` | 1 → 3 → 8 → 5 → 12 | Community ordination |
+| `build-fire-risk-map` | 1 → 2 → 10 → 4 → 5 → 9 | Fire risk spatial model |
+| `run-occupancy-analysis` | 1 → 3 → 7 → 5 → 12 | Occupancy with imperfect detection |
+| `analyze-environmental-change` | 1 → 2 → 10 → 9 → 12 | Environmental time series |
+| `assess-ecosystem-services` | 1 → 2 → 11 → 3 → 12 | ES valuation |
+| `produce-technical-report` | 12 → template → synthesis | Report generation |
+| `run-multispecies-screening` | 1 → 2 → 4 → 6 → 5 | Rapid multi-species SDM |
+| `run-camera-trap-occupancy` | 1 → 13 → 7 → 5 → 12 | Camera trap to occupancy |
+| `assess-landscape-connectivity` | 1 → 2 → 15 → 5 → 12 | Corridor and patch importance |
+| `run-population-viability` | 1 → 3 → 16 → 5 → 12 | PVA and extinction risk |
+| `run-conservation-prioritization` | 1 → 2 → 6 → 17 → 12 | Reserve network design |
+
+---
+
+## How to Use Skills
+
+### Natural invocation
+```
+Use the species-distribution-modeling skill to build a MaxEnt model for Chrysocyon brachyurus.
+```
+
+### Explicit skill reference
+```
+Load skill: ecological-data-foundation
+Task: validate and clean the occurrence dataset at data/raw/occurrences.csv
+```
+
+### Chaining via workflow
+```
+Run workflow: run-sdm-study
+Species: Panthera onca
+Study area: Amazon biome
+Predictors: WorldClim v2.1 + MapBiomas land cover
+```
+
+---
+
+## For AI Agents
+
+If you are an AI agent operating in this repository, **read these two files first**:
+
+| File | Purpose |
+|---|---|
+| [`AGENT_CONTEXT.md`](AGENT_CONTEXT.md) | Canonical rules for skill invocation, disambiguation, minimum sample sizes, project scaling, and file conventions |
+| [`skills/SKILL_INDEX.json`](skills/SKILL_INDEX.json) | Machine-readable index of all skills with trigger keywords, required inputs, outputs, dependencies, and decision thresholds |
+
+**Quick start for agents:**
+1. Read `AGENT_CONTEXT.md` in full before any task.
+2. Search `skills/SKILL_INDEX.json` by `trigger_keywords` to select the correct skill.
+3. Read the full `SKILL.md` of the selected skill before executing any step.
+4. Check `min_inputs` and `decision_points` before running scripts.
+5. Write decisions to `decision_log.md` after each skill completes.
+
+---
+
+## Examples (14)
+
+| Region | Example | Analysis |
+|--------|---------|----------|
+| Amazon, Brazil | Jaguar | SDM |
+| Cerrado, Brazil | Giant Anteater | SDM |
+| Atlantic Forest, Brazil | Bird community | Community ordination |
+| Atlantic Forest, Brazil | Puma | Occupancy |
+| Atlantic Forest, Brazil | Road construction | BACI impact |
+| Atlantic Forest, Brazil | Ecosystem services | ES valuation |
+| Amazon reservoirs | Phytoplankton | Community shift |
+| Western Europe | Grey Wolf | SDM + recolonization + conflict |
+| Eastern Australia | Koala | SDM + climate change + MOP |
+| Indo-Pacific | Reef fish (987 spp.) | Beta diversity + PERMANOVA |
+| Central Himalayas | Snow Leopard | Occupancy + camera trap |
+| Borneo | Tropical forest | BFAST + MESH + BACI |
+| Arctic (Greenland/Canada) | Tundra vegetation | NDVI greening |
+| Holarctic (global) | Red Fox | Fully reproducible SDM |
+
+See [`docs/global-examples-index.md`](docs/global-examples-index.md) for full details with data sources and DOIs.
+
+---
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [`docs/theoretical-foundations.md`](docs/theoretical-foundations.md) | Citable justifications for 10 methodological decisions with primary references |
+| [`docs/global-examples-index.md`](docs/global-examples-index.md) | Inventory of all 14 examples with geographic and taxonomic coverage |
+| [`docs/comparison-with-alternatives.md`](docs/comparison-with-alternatives.md) | Comparison vs. Wallace, biomod2, kuenm, ENMTML, SDMtoolbox, Zonation, Vortex |
+| [`CATALOG.md`](CATALOG.md) | Skill-level metadata: inputs, outputs, trigger keywords, workflow linkages |
+
+---
+
+## Repository Structure
+
+```
+ecological-agent-skills/
+├── AGENT_CONTEXT.md              ← rules for AI agents (read first)
+├── CATALOG.md                    ← skill index with metadata
+├── CITATION.cff                  ← citation metadata
+├── CHANGELOG.md                  ← version history
+├── CONTRIBUTING.md               ← contributor guidelines
+├── KNOWN_ISSUES.md               ← documented issues with workarounds
+├── RELEASE_CHECKLIST.md          ← release process
+├── environment.yaml              ← conda environment (Python + R)
+├── renv.lock                     ← R package lock file
+├── skills/                       ← 17 modular skills
+│   ├── SKILL_INDEX.json          ← machine-readable skill registry
+│   └── <skill-name>/
+│       ├── SKILL.md              ← main instructions
+│       ├── resources/            ← checklists, glossaries, templates
+│       ├── examples/             ← usage prompt examples
+│       └── scripts/              ← R/Python helpers
+├── workflows/                    ← 13 multi-step playbooks
+│   └── <workflow-name>/
+│       └── WORKFLOW.md
+├── templates/                    ← reusable prompts, reports, checklists
+├── examples/                     ← 14 worked examples (6 continents)
+├── docs/                         ← theoretical foundations, comparisons
+├── tests/                        ← pytest + testthat + 585 CI checks
+│   ├── ci_check.sh               ← structural integrity checker
+│   ├── python/                   ← 19 pytest test files
+│   ├── r/                        ← 18 testthat test files
+│   ├── data/                     ← 11 test CSVs
+│   ├── regression/               ← reference-based regression tests
+│   └── agent_smoke/              ← 15 agent routing validation cases
+└── .github/workflows/ci.yml      ← GitHub Actions CI
+```
+
+---
+
+## Implementation Roadmap
+
+| Phase | Skills | Status |
+|-------|--------|--------|
+| **Phase 1** — Foundation | ecological-data-foundation, geoprocessing-for-ecology, biostatistics-workbench, predictive-modeling-best-practices, reproducible-ecology-pipeline | Complete |
+| **Phase 2** — Modeling | model-validation-and-uncertainty, species-distribution-modeling, ecological-impact-assessment, environmental-time-series | Complete |
+| **Phase 3** — Specialist | occupancy-and-detection, community-ecology-ordination, ecosystem-services-assessment | Complete |
+| **Phase 4** — Advanced | camera-trap-processing, acoustic-monitoring, landscape-connectivity, population-viability-analysis, spatial-prioritization | Complete |
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for full guidelines.
+
+Follow the standard skill packaging pattern: one directory per skill, `SKILL.md` as the entry point, with optional `resources/`, `examples/`, and `scripts/` subdirectories.
+
+---
+
+## License
+
+This project is licensed under the [GNU General Public License v3.0](LICENSE) or later. See [`CITATION.cff`](CITATION.cff) for citation metadata.

package/bin/install.mjs

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+
+// ecological-agent-skills installer
+// Usage: npx ecological-agent-skills [--claude | --gemini | --cursor | --copilot | --codex | --path <dir>]
+
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, cpSync } from "node:fs";
+import { resolve, join } from "node:path";
+import { homedir } from "node:os";
+
+const REPO_URL = "https://github.com/baratadiego/ecological-agent-skills.git";
+const PACKAGE_NAME = "ecological-agent-skills";
+
+const TARGETS = {
+  "--claude": {
+    path: () => join(process.cwd(), ".claude", "skills", PACKAGE_NAME),
+    label: "Claude Code",
+    postInstall: `Add to your CLAUDE.md:\n  Read AGENT_CONTEXT.md from .claude/skills/${PACKAGE_NAME}/ before any ecology task.`,
+  },
+  "--gemini": {
+    path: () => join(homedir(), ".gemini", PACKAGE_NAME, "skills"),
+    label: "Gemini CLI / Antigravity",
+    postInstall: "Skills will be auto-discovered by Gemini CLI.",
+  },
+  "--cursor": {
+    path: () => join(process.cwd(), ".cursor", "skills", PACKAGE_NAME),
+    label: "Cursor",
+    postInstall: `Add to .cursor/rules/:\n  Read AGENT_CONTEXT.md from .cursor/skills/${PACKAGE_NAME}/ before any ecology task.`,
+  },
+  "--copilot": {
+    path: () => join(process.cwd(), ".github", "skills", PACKAGE_NAME),
+    label: "GitHub Copilot",
+    postInstall: `Reference in .github/copilot-instructions.md:\n  Read AGENT_CONTEXT.md from .github/skills/${PACKAGE_NAME}/ before any ecology task.`,
+  },
+  "--codex": {
+    path: () => join(process.cwd(), ".codex", "skills", PACKAGE_NAME),
+    label: "Codex CLI",
+    postInstall: "Skills installed for Codex CLI.",
+  },
+};
+
+function printUsage() {
+  console.log(`
+ecological-agent-skills — installer for quantitative ecology AI skills
+
+Usage:
+  npx ecological-agent-skills --claude       Install for Claude Code (project-local)
+  npx ecological-agent-skills --gemini       Install for Gemini CLI (~/.gemini/)
+  npx ecological-agent-skills --cursor       Install for Cursor (project-local)
+  npx ecological-agent-skills --copilot      Install for GitHub Copilot (project-local)
+  npx ecological-agent-skills --codex        Install for Codex CLI (project-local)
+  npx ecological-agent-skills --path <dir>   Install to a custom directory
+
+Options:
+  --help       Show this help message
+  --version    Show version
+`);
+}
+
+function getVersion() {
+  return "3.1.0";
+}
+
+function main() {
+  const args = process.argv.slice(2);
+
+  if (args.includes("--help") || args.length === 0) {
+    printUsage();
+    process.exit(0);
+  }
+
+  if (args.includes("--version")) {
+    console.log(getVersion());
+    process.exit(0);
+  }
+
+  let targetPath;
+  let label;
+  let postInstall;
+
+  if (args.includes("--path")) {
+    const idx = args.indexOf("--path");
+    const customPath = args[idx + 1];
+    if (!customPath) {
+      console.error("Error: --path requires a directory argument.");
+      process.exit(1);
+    }
+    targetPath = resolve(customPath);
+    label = "Custom path";
+    postInstall = `Skills installed to ${targetPath}`;
+  } else {
+    const flag = args.find((a) => TARGETS[a]);
+    if (!flag) {
+      console.error(`Unknown option: ${args[0]}`);
+      printUsage();
+      process.exit(1);
+    }
+    const target = TARGETS[flag];
+    targetPath = target.path();
+    label = target.label;
+    postInstall = target.postInstall;
+  }
+
+  console.log(`\nInstalling ecological-agent-skills for ${label}...`);
+  console.log(`Target: ${targetPath}\n`);
+
+  const tmpDir = join(
+    homedir(),
+    ".cache",
+    "ecological-agent-skills-tmp-" + Date.now()
+  );
+
+  try {
+    console.log("Cloning repository...");
+    execFileSync("git", ["clone", "--depth", "1", REPO_URL, tmpDir], {
+      stdio: "pipe",
+    });
+
+    mkdirSync(targetPath, { recursive: true });
+
+    const filesToCopy = [
+      "skills",
+      "workflows",
+      "templates",
+      "examples",
+      "docs",
+      "AGENT_CONTEXT.md",
+      "CATALOG.md",
+      "environment.yaml",
+      "renv.lock",
+    ];
+
+    for (const item of filesToCopy) {
+      const src = join(tmpDir, item);
+      const dest = join(targetPath, item);
+      if (existsSync(src)) {
+        cpSync(src, dest, { recursive: true });
+      }
+    }
+
+    console.log("\nInstalled successfully!\n");
+    console.log(`  17 skills, 13 workflows, 58 scripts\n`);
+    console.log(`Next steps:`);
+    console.log(`  ${postInstall}\n`);
+    console.log(
+      `Environment setup (optional, for running R/Python scripts):`
+    );
+    console.log(`  conda env create -f ${join(targetPath, "environment.yaml")}`);
+    console.log(`  conda activate eco-skills\n`);
+  } catch (err) {
+    console.error("Installation failed:", err.message);
+    process.exit(1);
+  } finally {
+    try {
+      if (process.platform === "win32") {
+        execFileSync("cmd", ["/c", "rmdir", "/s", "/q", tmpDir], {
+          stdio: "pipe",
+        });
+      } else {
+        execFileSync("rm", ["-rf", tmpDir], { stdio: "pipe" });
+      }
+    } catch {
+      // Ignore cleanup errors
+    }
+  }
+}
+
+main();

package/docs/comparison-with-alternatives.md

@@ -0,0 +1,38 @@
+# Comparison with Alternative Tools
+
+This document provides an objective comparison of **ecological-agent-skills** against established software tools used in quantitative ecology, species distribution modeling, population viability analysis, and spatial conservation planning.
+
+## Comparison Table
+
+| Criterion | ecological-agent-skills | Wallace | SDMtoolbox | biomod2 | kuenm | ENMTML | Zonation | Vortex |
+|---|---|---|---|---|---|---|---|---|
+| **Type** | Skill repository (R + Python) | R/Shiny GUI | ArcGIS plugin (Python) | R package | R package | R package | Standalone (C++) | Standalone (Windows) |
+| **SDM algorithms** | MaxEnt, GLM, GAM, BRT, RF via biomod2/maxnet wrappers | MaxEnt, GLM, GAM, BRT, RF, BIOCLIM | MaxEnt (with background selection tools) | MaxEnt, GLM, GAM, GBM, RF, SRE, FDA, MARS, ANN, CTA (10+) | MaxEnt only (calibration-focused) | MaxEnt, GLM, GAM, GBM, RF, SVM, BIOCLIM, Domain (10+) | None (consumes SDM outputs) | None (not an SDM tool) |
+| **PVA included** | Yes (matrix-based, stochastic demographic) | No | No | No | No | No | No | Yes (individual-based, genetics, catastrophes) |
+| **Prioritization included** | Yes (via prioritizr wrapper) | No | No | No | No | No | Yes (core functionality) | No |
+| **Connectivity included** | Yes (resistance surfaces, least-cost paths, circuit theory via gdistance/Circuitscape) | No | Partial (corridor tools in ArcGIS) | No | No | No | Partial (connectivity penalty in planning) | No |
+| **Reproducibility** | 4/5 -- scripted pipelines with config files, but depends on user discipline to version inputs | 3/5 -- session-based, exports R scripts but GUI steps not fully logged | 2/5 -- ArcGIS model builder possible but manual steps common | 4/5 -- fully scripted R workflows | 4/5 -- scripted calibration with CSV logs | 4/5 -- scripted with HTML output reports | 2/5 -- GUI-driven parameter files, batch mode possible | 2/5 -- GUI with project files, XML scenarios exportable |
+| **Learning curve** | 3/5 -- requires comfort with CLI/agents and R/Python, but SKILL.md docs guide each step | 2/5 -- GUI with step-by-step tabs, beginner-friendly | 3/5 -- requires ArcGIS expertise | 3/5 -- R programming required, good vignettes | 3/5 -- R programming, MaxEnt-specific knowledge | 3/5 -- R programming, similar interface to biomod2 | 4/5 -- complex parameter tuning, sparse documentation | 4/5 -- many parameters, population biology expertise needed |
+| **AI agent support** | Yes (designed for agents: trigger keywords, SKILL.md index, AGENT_CONTEXT.md) | No | No | No | No | No | No | No |
+| **Methodological decision docs** | Yes (theoretical-foundations linking choices to primary literature) | Partial (guidance text in GUI panels) | No | Partial (vignettes explain options) | Yes (calibration rationale in publications) | Partial (vignettes) | No (user must consult external literature) | No (user must consult external literature) |
+| **Global scope** | Yes (GBIF/BIEN download, WorldClim/CHELSA layers, any region) | Yes (GBIF integration, WorldClim) | Partial (requires user-supplied layers, no built-in download) | Yes (user supplies data, no built-in download, but global in principle) | Partial (user supplies data, designed for any region) | Yes (built-in GBIF and WorldClim download) | Yes (user supplies layers, any region) | Yes (user defines parameters, any species) |
+| **Last update / maintenance** | 2025 (active development) | 2024 (active, v2.x) | 2021 (maintenance mode, ArcGIS Pro migration unclear) | 2024 (active, CRAN) | 2023 (maintained, GitHub) | 2022 (low activity) | 2022 (Zonation 5 released, limited updates) | 2024 (active, v10.x) |
+| **Licence** | MIT | GPL-3 | GPL-3 | GPL-2+ | GPL-3 | GPL-3 | Proprietary (free for academic use) | Proprietary (free for non-commercial use) |
+
+## Positioning
+
+ecological-agent-skills is the only repository designed specifically for use with AI agents, integrating 17 skills in reproducible pipelines with documented methodological decisions. It does not replace biomod2 or prioritizr -- it uses them as dependencies. It is distinguished by: (1) agent-native design with trigger keywords and skill index, (2) integrated coverage from data download through SDM, community ecology, impact assessment, PVA, connectivity, and spatial prioritization, (3) dual R+Python implementation for every script, and (4) theoretical-foundations document linking every methodological choice to primary literature.
+
+Where Wallace and ENMTML excel at providing accessible, self-contained SDM workflows, and Vortex and Zonation offer deep functionality in PVA and spatial planning respectively, ecological-agent-skills occupies a distinct niche: it is a coordination layer that connects these analytical domains into end-to-end pipelines that an AI agent can discover, parameterize, and execute without manual GUI interaction. The repository is most valuable when an analyst needs to chain multiple analytical steps -- for example, downloading occurrence data, fitting an ensemble SDM, running a PVA on predicted suitable habitat, and feeding both outputs into a spatial prioritization -- in a single reproducible session guided by an AI assistant.
+
+## Limitations of ecological-agent-skills
+
+The following limitations should be considered when evaluating whether this repository is appropriate for a given use case:
+
+- **No GUI** -- requires command-line or agent interface. Users who prefer point-and-click workflows should consider Wallace or Vortex instead.
+- **Not a standalone software package** -- a skill library that wraps existing packages. It adds orchestration and documentation, not novel algorithms.
+- **SDM algorithms depend on external packages** (maxnet, dismo, biomod2). If upstream packages introduce breaking changes, scripts may require updates.
+- **PVA implementation is simpler than Vortex** -- no genetics module, no individual-based modeling, no catastrophe scheduling. For species requiring detailed genetic or demographic complexity, Vortex remains the better tool.
+- **Prioritization is a wrapper around prioritizr** -- does not add novel optimization solvers or planning unit generation beyond what prioritizr already provides.
+- **Test suite does not cover all edge cases** for scripts that require live API calls (GBIF, WorldClim). Tests use stored fixtures; failures against live APIs may not be caught until runtime.
+- **Documentation is in English only**. Non-English-speaking users may face accessibility barriers, particularly for the methodological decision documents.

package/docs/global-examples-index.md

@@ -0,0 +1,103 @@
+# Global Examples Index
+
+Complete inventory of all worked examples in the ecological-agent-skills repository, with geographic and thematic coverage analysis.
+
+---
+
+## Example Inventory
+
+| # | Example | Species / System | Region | Continent | Biome | Skill / Workflow | Analysis Type | Data Source | DOI / URL |
+|---|---------|-----------------|--------|-----------|-------|-----------------|---------------|-------------|-----------|
+| 1 | [Jaguar SDM](../examples/sdm/jaguar_amazon_example.md) | *Panthera onca* | Brazilian Amazon | South America | Tropical moist forest | run-sdm-study | SDM | GBIF, SpeciesLink, WorldClim | doi:10.15468/dl.xxxxx |
+| 2 | [Giant Anteater SDM](../examples/sdm/anteater_cerrado_example.md) | *Myrmecophaga tridactyla* | Cerrado, Brazil | South America | Tropical savanna | run-sdm-study | SDM | GBIF, WorldClim, MapBiomas | doi:10.15468/dl.xxxxx |
+| 3 | [Grey Wolf Recolonization](../examples/sdm/wolf_recolonization_europe_example.md) | *Canis lupus* | Western Europe | Europe | Temperate forest / Mediterranean | run-sdm-study | SDM + conflict analysis | GBIF, EuroLargeCarnivores, WorldClim, Corine LC | doi:10.15468/dl.xxxxx |
+| 4 | [Koala Climate Change](../examples/sdm/koala_climate_change_example.md) | *Phascolarctos cinereus* | Eastern Australia | Oceania | Temperate woodland | run-sdm-study | SDM + future projection + MOP | GBIF, ALA, WorldClim, CMIP6 | doi:10.15468/dl.xxxxx |
+| 5 | [Red Fox Reproducible](../examples/reproducible/whittaker_biome_sdm_example.md) | *Vulpes vulpes* | Holarctic (global) | Multi-continent | Multiple | run-sdm-study | SDM (fully reproducible) | GBIF, WorldClim | doi:10.15468/dl.example |
+| 6 | [Bird Community — Atlantic Forest](../examples/community/bird_landuse_example.md) | 127 bird species | Atlantic Forest, Brazil | South America | Tropical moist forest | analyze-community-structure | Community ecology | Field surveys | — |
+| 7 | [Phytoplankton — Amazon Reservoirs](../examples/community/phytoplankton_reservoir_example.md) | Phytoplankton assemblages | Amazon basin reservoirs | South America | Tropical moist forest (aquatic) | analyze-community-structure | Community ecology | Field surveys | — |
+| 8 | [Reef Fish — Indo-Pacific](../examples/community/reef_fish_indopacific_example.md) | 987 reef fish species | Indo-Pacific coral reefs | Asia / Oceania | Marine coral reef | analyze-community-structure | Community ecology (beta diversity) | Reef Life Survey | doi:10.1038/sdata.2014.7 |
+| 9 | [Arctic Tundra Vegetation](../examples/community/arctic_tundra_vegetation_example.md) | Tundra vegetation | Greenland, northern Canada | North America / Europe | Arctic tundra | analyze-community-structure + environmental-time-series | Time series + community shift | MODIS, ERA5-Land, AVA | — |
+| 10 | [BACI Road Impact — Birds](../examples/impact/baci_road_example.md) | Birds (Atlantic Forest) | Atlantic Forest, Brazil | South America | Tropical moist forest | assess-ecological-impact | BACI impact assessment | Field surveys | — |
+| 11 | [Ecosystem Services — Atlantic Forest](../examples/impact/ecosystem_services_atlantic_forest.md) | Atlantic Forest remnants | São Paulo, Brazil | South America | Tropical moist forest | assess-ecosystem-services | Ecosystem services | MapBiomas | — |
+| 12 | [Forest Loss — Borneo](../examples/impact/forest_loss_borneo_timeseries_example.md) | Tropical rainforest | Borneo (Malaysia, Indonesia) | Asia | Tropical moist forest | assess-ecological-impact | BFAST + fragmentation + BACI | Hansen GFC, MODIS | doi:10.1126/science.1244693 |
+| 13 | [Puma Occupancy — Camera Traps](../examples/occupancy/puma_camera_example.md) | *Puma concolor* | Atlantic Forest, Brazil | South America | Tropical moist forest | run-occupancy-analysis | Occupancy modeling | Camera traps | — |
+| 14 | [Snow Leopard Occupancy — Himalayas](../examples/occupancy/snow_leopard_himalayas_example.md) | *Panthera uncia* | Central Himalayas (Nepal/India) | Asia | Alpine / montane | run-occupancy-analysis | Occupancy modeling | Camera traps, literature | doi:10.2193/0091-7648 |
+
+---
+
+## Coverage Summary
+
+### Continents Represented
+
+| Continent | Examples | Example IDs |
+|-----------|---------|-------------|
+| South America | 6 | 1, 2, 6, 7, 10, 11 |
+| Europe | 2 | 3, 9 (Greenland) |
+| Asia | 3 | 8, 12, 14 |
+| Oceania | 2 | 4, 8 (Indo-Pacific overlap) |
+| North America | 2 | 5 (Holarctic), 9 (Canada) |
+| Africa | 1 | 5 (Holarctic — includes N. Africa margin) |
+
+All 6 inhabited continents are covered. Africa has minimal direct representation (only via the Holarctic red fox range), but the repository's skills and workflows are globally applicable.
+
+### Biomes Represented
+
+| Biome | Examples | n |
+|-------|---------|---|
+| Tropical moist forest | 1, 2, 6, 7, 10, 11, 12, 13 | 8 |
+| Tropical savanna (Cerrado) | 2 | 1 |
+| Temperate forest | 3 | 1 |
+| Temperate woodland | 4 | 1 |
+| Mediterranean | 3 | 1 |
+| Marine coral reef | 8 | 1 |
+| Arctic tundra | 9 | 1 |
+| Alpine / montane | 14 | 1 |
+| Multiple (Holarctic) | 5 | 1 |
+
+### Taxonomic Groups
+
+| Group | Species / System | Examples |
+|-------|-----------------|---------|
+| Mammals | Jaguar, anteater, wolf, koala, fox, puma, snow leopard | 1, 2, 3, 4, 5, 13, 14 |
+| Birds | Atlantic Forest bird community | 6, 10 |
+| Fish | Indo-Pacific reef fish (987 spp.) | 8 |
+| Plants | Arctic tundra vegetation | 9 |
+| Phytoplankton | Amazon reservoir assemblages | 7 |
+| Ecosystem (forest) | Borneo tropical forest, Atlantic Forest remnants | 11, 12 |
+
+### Analysis Types
+
+| Analysis | Examples | n |
+|----------|---------|---|
+| SDM (species distribution modeling) | 1, 2, 3, 4, 5 | 5 |
+| Community ecology (ordination, diversity) | 6, 7, 8 | 3 |
+| Occupancy modeling | 13, 14 | 2 |
+| BACI impact assessment | 10, 12 | 2 |
+| Ecosystem services | 11 | 1 |
+| Time series (NDVI, BFAST) | 9, 12 | 2 |
+| Climate change projection | 4 | 1 |
+| Conflict / land-use overlay | 3 | 1 |
+| Fragmentation (MESH) | 12 | 1 |
+
+### Workflows Used
+
+| Workflow | Examples |
+|----------|---------|
+| run-sdm-study | 1, 2, 3, 4, 5 |
+| analyze-community-structure | 6, 7, 8, 9 |
+| run-occupancy-analysis | 13, 14 |
+| assess-ecological-impact | 10, 12 |
+| assess-ecosystem-services | 11 |
+| analyze-environmental-change | 9 |
+
+---
+
+## Coverage Gaps and Notes
+
+- **Africa**: Represented only through the Holarctic red fox example. All skills and workflows are applicable to African taxa and ecosystems — users are encouraged to contribute African case studies.
+- **Acoustic monitoring / eDNA**: No worked example yet. The `acoustic-monitoring` skill includes decision tables and scripts but awaits a full example.
+- **PVA**: No worked example yet. The `population-viability-analysis` skill includes Leslie matrix scripts and IUCN Criterion E guidance.
+- **Spatial prioritization**: No worked example yet. The `spatial-prioritization` skill includes prioritizr scripts and 30x30 target guidance.
+- **Connectivity**: No worked example yet. The `landscape-connectivity` skill includes IIC/PC/Circuitscape scripts.
+
+These gaps represent opportunities for future examples. The skill documentation and scripts are complete and functional — examples provide illustration, not implementation.