ecological-agent-skills 3.1.0

package/templates/SKILL_TEMPLATE.md

@@ -0,0 +1,225 @@
+---
+skill_version: 1.0.0
+<!-- [OBRIGATÓRIO] Increment this version (semver) whenever the skill content changes significantly. -->
+---
+
+# Skill: [OBRIGATÓRIO — skill-id in kebab-case, must match directory name and SKILL_INDEX.json]
+
+<!-- INSTRUCTIONS FOR SKILL AUTHORS
+     Fill in every [OBRIGATÓRIO] field. Delete all HTML comments before submitting.
+     Run the validation checklist at the bottom before opening a pull request.
+     All content must be in English.
+     No location-specific geographic references in global files.
+-->
+
+---
+
+## Purpose
+
+<!-- [OBRIGATÓRIO]
+     Write 2–4 sentences describing exactly what this skill does.
+     Start with "Guides the agent through..."
+     Be specific: name the methods, models, or operations covered.
+     Do NOT describe when to use it (that goes in "When to Invoke").
+-->
+
+[OBRIGATÓRIO — describe the skill's analytical scope]
+
+---
+
+## When to Invoke
+
+<!-- [OBRIGATÓRIO]
+     List the situations that should trigger this skill as bullet points.
+     Each bullet is a concrete scenario, not a keyword.
+     These scenarios must be consistent with the trigger_keywords in SKILL_INDEX.json.
+     Use plain language that matches how users phrase requests.
+-->
+
+Invoke this skill when:
+
+- [OBRIGATÓRIO — scenario 1]
+- [OBRIGATÓRIO — scenario 2]
+- [OBRIGATÓRIO — scenario 3]
+- [add more as needed]
+
+**trigger_keywords** (must match `skills/SKILL_INDEX.json`):
+`[keyword1]`, `[keyword2]`, `[keyword3]`
+
+<!-- List all trigger_keywords from SKILL_INDEX.json here so they stay in sync. -->
+
+---
+
+## Inputs
+
+<!-- [OBRIGATÓRIO]
+     List every input the skill needs.
+     "Required" = skill cannot run without it.
+     "Conditional" = required only under specific conditions (explain in Notes).
+     "Recommended" = skill produces lower-quality output without it.
+     "Optional" = enhances output but not needed.
+-->
+
+| Input | Format | Required |
+|---|---|---|
+| [OBRIGATÓRIO — input name] | [format: CSV, GeoTIFF, SHP, GPKG, RData, etc.] | Required / Conditional / Recommended / Optional |
+| [input name] | [format] | Required |
+| [input name] | [format] | Optional |
+
+---
+
+## Outputs
+
+<!-- [OBRIGATÓRIO]
+     List every file this skill produces.
+     Use snake_case filenames with extensions.
+     The primary outputs must match primary_outputs in SKILL_INDEX.json.
+-->
+
+| Output | Description |
+|---|---|
+| `[OBRIGATÓRIO — filename.ext]` | [what this file contains] |
+| `[filename.ext]` | [description] |
+| `[report_name.md]` | [full narrative report] |
+
+---
+
+## Steps
+
+<!-- [OBRIGATÓRIO]
+     Numbered, sequential steps the agent must follow.
+     Each step should be a complete, unambiguous instruction.
+     Reference specific script names where applicable.
+     Include the exact command or function call when precision matters.
+     Minimum 4 steps.
+-->
+
+1. **[OBRIGATÓRIO — step title]**
+   [Detailed instruction. Name the script, function, or tool to use. Specify parameters.]
+
+2. **[step title]**
+   [Instruction]
+
+3. **[step title]**
+   [Instruction]
+
+4. **Validate outputs**
+   Confirm that all files listed in the Outputs table were created and are non-empty.
+   Check file sizes are above 100 bytes. Record any anomalies in `decision_log.md`.
+
+5. **Record decisions**
+   Append to `decision_log.md` following the format defined in `AGENT_CONTEXT.md § 7`.
+
+<!-- Add more steps as needed. Do not omit the validation and decision-logging steps. -->
+
+---
+
+## Decision Points
+
+<!-- [OBRIGATÓRIO]
+     List every condition that requires a non-default decision.
+     "Condition" = a measurable or observable state.
+     "Diagnosis" = what the condition means.
+     "Recommended Action" = what the agent should do.
+     Minimum 3 rows.
+     Must be consistent with decision_points in SKILL_INDEX.json.
+-->
+
+| Condition | Diagnosis | Recommended Action |
+|---|---|---|
+| [OBRIGATÓRIO — e.g., n < 10] | [e.g., insufficient data for reliable modelling] | [e.g., do not fit model; communicate limitation to user] |
+| [condition] | [diagnosis] | [action] |
+| [condition] | [diagnosis] | [action] |
+
+---
+
+## Key Decisions to Document
+
+<!-- [OBRIGATÓRIO]
+     List the decisions that MUST be recorded in decision_log.md.
+     These are choices that affect reproducibility or interpretation.
+     Phrase as questions the agent answered during analysis.
+-->
+
+Record the following in `decision_log.md` after running this skill:
+
+- [OBRIGATÓRIO — e.g., Which predictor variables were retained and why?]
+- [e.g., Which model family was selected and what diagnostic justified it?]
+- [e.g., Were any records excluded? How many and for what reason?]
+- [add more as needed]
+
+---
+
+## Tools and Libraries
+
+<!-- [OBRIGATÓRIO — fill in at least one language block]
+     List packages, not functions.
+     Separate R and Python. Add CLI tools if applicable.
+     Keep version constraints only when a specific version is required.
+-->
+
+**R**
+```r
+# [OBRIGATÓRIO — list R packages]
+library(package1)   # purpose
+library(package2)   # purpose
+```
+
+**Python**
+```python
+# [OBRIGATÓRIO — list Python packages]
+import package1     # purpose
+import package2     # purpose
+```
+
+**CLI** *(if applicable)*
+```bash
+# [optional — list CLI tools, e.g., GDAL, csvkit]
+```
+
+---
+
+## Resources
+
+<!-- [OBRIGATÓRIO]
+     Link to every file in this skill's resources/ directory.
+     Minimum 2 resources.
+     Use relative paths from the repository root.
+-->
+
+- [`skills/[skill-id]/resources/[filename].md`](resources/[filename].md) — [one-line description]
+- [`skills/[skill-id]/resources/[filename].md`](resources/[filename].md) — [one-line description]
+
+<!-- Add more resource links as needed. -->
+
+---
+
+## Notes
+
+<!-- [OBRIGATÓRIO]
+     List caveats, common pitfalls, and edge cases.
+     Be specific. Vague warnings are not useful.
+     Minimum 3 bullet points.
+-->
+
+- **[OBRIGATÓRIO — pitfall or caveat]**: [specific explanation of the problem and how to avoid it]
+- **[pitfall]**: [explanation]
+- **[pitfall]**: [explanation]
+
+---
+
+## Validation Checklist
+
+Before submitting this skill, verify:
+
+- [ ] `trigger_keywords` added to `skills/SKILL_INDEX.json`
+- [ ] At least 2 files in `resources/`
+- [ ] At least 1 script in `scripts/` (R or Python)
+- [ ] At least 3 examples in `examples/example-prompts.md`
+- [ ] Skill added to `CATALOG.md`
+- [ ] Skill added to `README.md`
+- [ ] `skill_version` field present in YAML header
+- [ ] `decision_points` in `SKILL_INDEX.json` match the Decision Points table above
+- [ ] All `[OBRIGATÓRIO]` placeholders replaced
+- [ ] All HTML comments deleted
+- [ ] `bash tests/ci_check.sh` exits with code 0

package/templates/checklists/data-submission-checklist.md

@@ -0,0 +1,38 @@
+# Data Submission Checklist (for Zenodo / OSF / figshare)
+
+## Before Uploading
+
+- [ ] All raw data files in standard open formats (CSV, GeoTIFF, GPKG — not proprietary)
+- [ ] All files named meaningfully (no "data_final_v2_USE_THIS.csv")
+- [ ] README.md describes every file: what it contains, what each column means, units
+- [ ] Taxonomy validated against a standard backbone (version stated)
+- [ ] Darwin Core fields used for biodiversity occurrence data
+- [ ] Sensitive species data: coordinate uncertainty added or location generalised per GBIF policy
+- [ ] Coordinate reference system stated for all spatial files
+- [ ] File checksums computed (MD5 or SHA256) and listed in README
+
+## Metadata
+
+- [ ] Title: descriptive, includes taxon, region, and type of data
+- [ ] Authors and ORCIDs: complete and correct
+- [ ] DOI of associated publication (if available): linked
+- [ ] License: explicitly stated (CC BY 4.0 recommended for open science)
+- [ ] Keywords: 5–10 relevant terms
+- [ ] Temporal coverage: start date – end date
+- [ ] Spatial coverage: bounding box coordinates
+
+## For Occurrence Data Specifically
+
+- [ ] All Darwin Core terms documented
+- [ ] basisOfRecord populated
+- [ ] coordinateUncertaintyInMeters populated where known
+- [ ] geodeticDatum = "WGS84" confirmed
+- [ ] License per record populated if records from multiple sources
+
+## After Uploading
+
+- [ ] DOI resolved and landing page accessible
+- [ ] All files download correctly
+- [ ] README renders correctly on the platform
+- [ ] DOI included in manuscript data availability statement
+- [ ] Zenodo/OSF record linked in the code repository README

package/templates/checklists/post-analysis-checklist.md

@@ -0,0 +1,55 @@
+# Post-Analysis Checklist
+
+Complete before finalising any report or publication.
+
+## Statistical Reporting
+
+- [ ] All p-values accompanied by effect sizes and CIs
+- [ ] Sample sizes (n) reported for all comparisons
+- [ ] Test statistics reported (F, t, χ², H, Z)
+- [ ] Model performance reported for train, CV, AND test (never only training)
+- [ ] Multiple comparisons: correction applied and method stated (Bonferroni, FDR)
+- [ ] Confidence intervals: method stated (Wald, profile likelihood, bootstrap)
+
+## Model Reporting
+
+- [ ] Algorithm(s) and version(s) stated
+- [ ] All hyperparameters reported (not just "default settings")
+- [ ] CV strategy reported (k, block size for spatial CV)
+- [ ] Threshold selection method and value reported
+- [ ] Uncertainty quantification described and reported
+- [ ] Variable importance reported for all predictors
+
+## Spatial Outputs
+
+- [ ] CRS and resolution stated for all rasters
+- [ ] Spatial extent (bounding box or description) stated
+- [ ] Area estimates in appropriate units (ha, km²)
+- [ ] MESS / ExDet applied if predicting outside training range
+- [ ] All maps include scale bar, north arrow, and legend
+
+## Figures
+
+- [ ] All figures have informative captions (not just "Figure 1")
+- [ ] NMDS plots include stress value
+- [ ] ROC curves include AUC
+- [ ] Calibration plots include calibration slope
+- [ ] Colour palettes are colourblind-friendly (avoid red-green alone)
+- [ ] Figure resolution ≥ 300 dpi for publication
+
+## Data and Code Availability
+
+- [ ] Raw data archived with DOI (Zenodo, OSF, figshare)
+- [ ] Code archived with DOI and linked to specific commit
+- [ ] Data availability statement written
+- [ ] Code availability statement written
+- [ ] License specified for both data and code
+- [ ] README in data/code archive explains how to reproduce the analysis
+
+## Reporting Standards Compliance
+
+- [ ] SDM: ODMAP checklist completed (Zurell et al. 2020)
+- [ ] Occupancy: MacKenzie-Bailey GoF reported
+- [ ] Impact assessment: BACI design requirements verified
+- [ ] Community ecology: PERMDISP run before interpreting PERMANOVA
+- [ ] ES assessment: method and data source per service documented

package/templates/checklists/pre-analysis-checklist.md

@@ -0,0 +1,31 @@
+# Pre-Analysis Checklist
+
+Complete before starting any quantitative ecology analysis.
+
+## Data
+
+- [ ] Raw data archived in `data/raw/` and not modified
+- [ ] Data provenance documented (source, version, DOI, access date, license)
+- [ ] `ecological-data-foundation` skill applied; `qa_report.md` reviewed
+- [ ] Final cleaned dataset confirmed and saved
+
+## Spatial
+
+- [ ] Project CRS defined and documented in `params.yaml`
+- [ ] All layers reprojected to project CRS
+- [ ] Raster stack aligned (same extent, resolution, CRS)
+- [ ] Study area polygon finalised
+
+## Modeling
+
+- [ ] Collinearity assessed; final predictor set documented
+- [ ] CV strategy defined (spatial or temporal if applicable)
+- [ ] Candidate model set justified (not purely data-driven)
+- [ ] Primary evaluation metric pre-specified
+
+## Reproducibility
+
+- [ ] `params.yaml` complete (no hard-coded values remain in scripts)
+- [ ] Random seeds set in `params.yaml`
+- [ ] `git init` and initial commit done
+- [ ] `decision_log.md` opened and dated

package/templates/prompts/debug-skill.md

@@ -0,0 +1,47 @@
+# Prompt Template: Debug or Review Skill Output
+
+Use when the output from a skill step needs to be reviewed, corrected, or improved.
+
+```
+Review the output of the <skill-name> step.
+
+Output file(s):
+  - <path to output>
+
+Issues observed:
+  - <describe what looks wrong or unexpected>
+
+Expected behaviour:
+  - <describe what the output should look like>
+
+Please:
+  1. Diagnose the issue
+  2. Propose a fix
+  3. Apply the fix and regenerate the affected output
+  4. Add an entry to decision_log.md explaining what was wrong and how it was fixed
+```
+
+## Example
+
+```
+Review the output of the ecological-data-foundation step.
+
+Output file: data/processed/data_clean.csv (n = 1,240)
+Output file: data/processed/flagged_records.csv (n = 2)
+
+Issues observed:
+  - Only 2 records were flagged, but I can see at least 50 records with
+    latitude values that look like they may be DMS format (e.g., "-15766"
+    instead of "-15.766").
+  - The QA_status column contains only "OK" and "COORD_ZERO".
+
+Expected behaviour:
+  - DMS-format coordinates should be detected and flagged as COORD_FORMAT_ERROR
+    or converted to decimal degrees if the conversion is unambiguous.
+
+Please:
+  1. Diagnose why these records passed the coordinate range check
+  2. Add a DMS detection step
+  3. Re-run cleaning and update data_clean.csv and qa_report.md
+  4. Add entry to decision_log.md
+```

package/templates/prompts/invoke-skill.md

@@ -0,0 +1,34 @@
+# Prompt Template: Invoke a Single Skill
+
+```
+Load skill: <skill-name>
+Task: <describe the specific task>
+
+Inputs:
+  - <file or data description>
+  - <file or data description>
+
+Requirements:
+  - <specific requirement or constraint>
+  - <specific requirement or constraint>
+
+Output: <list expected output files or formats>
+```
+
+## Example
+
+```
+Load skill: ecological-data-foundation
+Task: Clean and validate mammal occurrence data for the Pantanal.
+
+Inputs:
+  - data/raw/mammals_raw.csv  (GBIF download, Darwin Core format)
+  - data/spatial/pantanal_boundary.shp  (study area)
+
+Requirements:
+  - Use CoordinateCleaner flags: capitals, centroids, zeros, validity
+  - Taxonomy: GBIF Backbone 2023
+  - Remove records with coordinate uncertainty > 10 km
+
+Output: data/processed/data_clean.csv, data/processed/qa_report.md
+```

package/templates/prompts/invoke-workflow.md

@@ -0,0 +1,45 @@
+# Prompt Template: Invoke a Workflow
+
+```
+Run workflow: <workflow-name>
+
+Species / System: <target species or ecological system>
+Study area: <geographic scope>
+Temporal scope: <date range or time points>
+
+Inputs:
+  - <primary data file>
+  - <spatial layer>
+  - <additional data>
+
+Key parameters:
+  - <parameter name>: <value>
+  - <parameter name>: <value>
+
+Output directory: <path>
+Report format: <markdown / PDF / DOCX>
+```
+
+## Example
+
+```
+Run workflow: run-sdm-study
+
+Species: Giant anteater (Myrmecophaga tridactyla)
+Study area: Cerrado biome + 200 km buffer
+Temporal scope: Current (WorldClim 1970–2000) + SSP2-4.5 2050
+
+Inputs:
+  - data/processed/data_clean.csv   (n = 412 occurrences after cleaning)
+  - data/predictors/cerrado_stack.tif  (bio1, bio4, bio12, bio15, NDVI, slope)
+  - data/spatial/cerrado_buffer.shp
+
+Key parameters:
+  - Spatial thinning: 10 km
+  - CV blocks: 5, size 400 km
+  - Algorithms: MaxEnt, BRT, Random Forest
+  - Threshold: MaxTSS
+
+Output directory: outputs/anteater_sdm/
+Report format: markdown
+```

package/templates/reports/technical-report-template.md

@@ -0,0 +1,80 @@
+# Technical Report — [Study Title]
+
+**Authors:** [Names]  
+**Date:** [YYYY-MM-DD]  
+**Version:** [1.0]  
+**Repository:** [URL]
+
+---
+
+## 1. Introduction
+
+[Context, study objectives, and research questions.]
+
+---
+
+## 2. Methods
+
+### 2.1 Study Area
+[Description of the study area, geographic extent, and key environmental characteristics.]
+
+### 2.2 Data Sources
+| Dataset | Source | Resolution / Scale | Date | DOI |
+|---------|--------|-------------------|------|-----|
+| | | | | |
+
+### 2.3 Data Preparation
+[Describe cleaning steps, QA procedures, and key decisions. Reference qa_report.md.]
+
+### 2.4 [Analysis Approach — e.g., Species Distribution Modeling]
+[Full methods description following relevant reporting standard (ODMAP, etc.).]
+
+### 2.5 Model Validation and Uncertainty
+[Describe validation strategy, metrics, and uncertainty quantification.]
+
+---
+
+## 3. Results
+
+### 3.1 Data Summary
+[Number of records after cleaning, spatial extent covered, etc.]
+
+### 3.2 Model Performance
+| Metric | Training | CV | Test |
+|--------|---------|-----|------|
+| AUC-ROC | | | |
+| TSS | | | |
+
+### 3.3 Main Findings
+[Primary results with full statistical reporting: estimate (95% CI), test statistic, p-value, effect size.]
+
+### 3.4 Uncertainty
+[Description of uncertainty sources and their magnitude.]
+
+---
+
+## 4. Discussion
+
+[Interpretation, comparison with literature, limitations, management implications.]
+
+---
+
+## 5. Conclusions
+
+[Concise summary of main findings and recommendations.]
+
+---
+
+## 6. References
+
+[Full citations in standard format.]
+
+---
+
+## Appendix A: Reproducibility Package
+
+- **params.yaml:** [link or path]
+- **Code repository:** [URL with commit hash or tag]
+- **Raw data archive:** [Zenodo DOI or institutional repository URL]
+- **Software environment:** See `logs/software_environment.txt`
+- **Reproducibility checklist:** See `logs/reproducibility_checklist.md`

package/templates/scripts/logger_setup.R

@@ -0,0 +1,79 @@
+# logger_setup.R — Structured logging template for ecological-agent-skills
+# Usage: source("../../templates/scripts/logger_setup.R"); setup_logger("skill-name")
+# Requires: futile.logger (install.packages("futile.logger"))
+
+suppressPackageStartupMessages(library(futile.logger))
+
+#' Initialise logger for a skill script
+#'
+#' Sets up simultaneous console + file handlers.
+#' Log file: logs/skill_{name}_{timestamp}.log (relative to working directory)
+#'
+#' @param skill_name  Short identifier, e.g. "sdm", "occupancy"
+#' @param log_dir     Directory for log files (created if absent)
+#' @param level       Futile.logger threshold: INFO, WARN, ERROR
+setup_logger <- function(skill_name = "eco-skill",
+                         log_dir    = "logs",
+                         level      = INFO) {
+  dir.create(log_dir, recursive = TRUE, showWarnings = FALSE)
+  ts       <- format(Sys.time(), "%Y%m%d_%H%M%S")
+  log_file <- file.path(log_dir, paste0("skill_", skill_name, "_", ts, ".log"))
+
+  # Console layout: coloured, compact
+  flog.layout(layout.format("[~t] [~l] ~m"), name = ROOT)
+
+  # File appender: full timestamp, same format
+  flog.appender(appender.tee(log_file), name = ROOT)
+
+  flog.threshold(level, name = ROOT)
+
+  flog.info("Logger initialised | skill=%s | log_file=%s", skill_name, log_file)
+  invisible(log_file)
+}
+
+# ── Wrapper functions ────────────────────────────────────────────────────────
+
+#' Log an informational message
+log_info <- function(...) flog.info(...)
+
+#' Log a warning
+log_warn <- function(...) flog.warn(...)
+
+#' Log an error (does NOT stop execution — call stop() afterwards if needed)
+log_error <- function(...) flog.error(...)
+
+#' Mark the start of a numbered processing step
+#'
+#' @param step_number  Integer step counter
+#' @param description  Short description of the step
+log_step <- function(step_number, description) {
+  flog.info("── STEP %d: %s", step_number, description)
+}
+
+#' Record an analytical decision with justification
+#'
+#' @param variable   Name of the parameter / variable
+#' @param value      Value chosen
+#' @param rationale  One-sentence justification
+log_decision <- function(variable, value, rationale) {
+  flog.info("DECISION | %s = %s | rationale: %s", variable, value, rationale)
+}
+
+#' Standard actionable error message
+#'
+#' @param step          Name of the failing step
+#' @param error_msg     The error message (from conditionMessage(e))
+#' @param probable_cause One-sentence explanation of likely cause
+#' @param check_this    What the user should check
+#' @param prior_skill   Which upstream skill should have produced the input
+log_actionable_error <- function(step, error_msg, probable_cause,
+                                 check_this, prior_skill = NULL) {
+  prior_line <- if (!is.null(prior_skill))
+    paste0("\n  Skill anterior que deveria ter produzido este input: ", prior_skill)
+  else ""
+
+  flog.error(
+    "[ERROR] Falha em %s: %s\n  Causa provável: %s\n  Verifique: %s%s",
+    step, error_msg, probable_cause, check_this, prior_line
+  )
+}