GeoSkills

English | 简体中文

A local, model-provider-independent Agent Skill for geology and geochemistry.

Turn local tables into editable scientific figures. Review column mappings, units, and scientific parameters first, then generate SVG, PDF, TIFF, PNG, and quality-assurance reports in one workflow.

Stable release: GeoSkills v0.8.0. This branch contains the unreleased v0.9 development candidate.

Quick start · Supported diagrams · Installation · Workflow · Troubleshooting · Changelog

All gallery figures use public synthetic examples bundled with the repository, without real sample records or unpublished measurements.

1. Ask your assistant to use GeoSkills and provide the location of a local CSV, TXT, or XLSX file.
2. Specify the diagram you need. For an XY plot, identify the X/Y variables and whether each axis should be linear or logarithmic.
3. Review the proposed mappings, units, reference values, and output plan, then approve plotting.

Example request:

Use GeoSkills to inspect my local geochemical table and prepare a chondrite-normalized REE plot. Show me the column mappings and normalization reference before plotting.

The default shareable profile omits plotted-data CSV files and suppresses sample identifiers in REE, spider, and XY figures. Group names remain visible in legends and should be reviewed before sharing. Numerical processing runs locally; plotting requires no model API or network service.

The publication-single-column preset is 89 × 75 mm at 600 dpi. Long reference notes are retained in JSON/QA reports instead of crowding the figure. The unified workflow uses full plot borders and automatically positions legends to reduce overlap.

Generic XY plots support independent linear or log10 axes. They do not supply isotope, tectonic-discrimination, or unreviewed classification boundaries.

Download the v0.8.0 source ZIP, extract it, and locate skills/geoskills.

For a manual Codex installation, copy that folder into your personal skills directory:

Start a new task after installation. Ask the assistant to check the local environment and explain any missing dependencies before installing them.

The portable skill entry point is SKILL.md. Its instructions and UI metadata are written in English. Some supporting references, diagnostics, and generated QA summaries are currently in Chinese; this release does not provide complete runtime localization.

Run the following from the repository root using Python 3.11 or 3.12.

Windows PowerShell:

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements-dev.txt

If Python is available through the Windows launcher, use py -3.12 -m venv .venv for the first command.

Linux/macOS:

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-dev.txt

The examples below use Windows paths. On Linux/macOS, use .venv/bin/python and forward slashes.

A recipe records the input file, mappings, units, scientific choices, tasks, output profile, and human confirmations. A plan is the reviewable check of that recipe before plotting.

Local table + recipe → plan → human review → run → complete output bundle

Check the environment:

.\.venv\Scripts\python.exe skills\geoskills\scripts\geoskills.py self-check

The examples directory includes:

Prepare a plan for the synthetic major-element example:

.\.venv\Scripts\python.exe skills\geoskills\scripts\geoskills.py plan skills\geoskills\examples\geoskills_major_workflow.yaml --output outputs\major-plan.json

Review outputs/major-plan.json, including its tasks, mapped variables, units, references, dimensions, output profile, and plan ID. When it is ready and approved, run:

.\.venv\Scripts\python.exe skills\geoskills\scripts\geoskills.py run skills\geoskills\examples\geoskills_major_workflow.yaml --plan outputs\major-plan.json

The --plan option selects the plan file, not the figure directory. The recipe's output.directory is resolved relative to the recipe file. This example writes figures to skills/geoskills/examples/generated/geoskills-major-workflow/.

Do not copy the example confirmations to your own data. They apply only to the bundled synthetic examples. Begin with user_recipe_template.yaml and review every confirmation.

Changes to the recipe, input, software version, style, or scientific assets invalidate old plans. Generate and review a new plan before continuing.

• Read CSV, comma- or tab-delimited TXT, and XLSX tables. Require an explicit worksheet when a workbook contains several sheets.
• Support one sample per row and conservatively transpose unambiguous tables with samples in columns.
• Summarize missing values, below-detection-limit entries, duplicate/blank sample IDs, non-numeric values, infinities, and nonpositive values as counts in shareable reports.
• Apply optional oxide-total checks only with a user-specified oxide list, range, and composition basis.
• Normalize an explicitly reviewed oxide list to an anhydrous 100% basis in a working copy. Original columns remain unchanged.
• Calculate deterministic ratios such as Nb/Y and K2O/Na2O only when the declared units match.
• Enforce table, raster, point, group, and drawing-object budgets before plotting. Oversized tasks are rejected without silently sampling data or merging groups.
• Commit multi-task results as one complete directory. A failed task does not replace the previous complete bundle.

The unified workflow exports editable SVG/PDF and high-resolution PNG/TIFF. TIFF uses RGB with LZW compression. Figure dimensions and resolution remain subject to the selected preset and validation limits.

Shareable plans and reports omit absolute paths, sample identifiers, exact source values, source filenames, worksheet names, and source-column labels. Selected-group values are represented by counts and a digest in reports; group names remain visible in figures. Figures still disclose scientific measurements and patterns, so shareable is not a substitute for permission to publish research data.

The plotted_data_export_reviewed confirmation acknowledges the selected export consequences. It does not authorize uploading data to a model or third-party service. Formula-like sample/group labels block local-reproducible CSV export.

In the v0.9 candidate, duplicate source headers stop input processing with E110. Overwriting an existing run verifies its inventory, file sizes, SHA-256 hashes, and root QA summary. Added, missing, or edited files stop replacement with E826; choose a new output directory to preserve your changes.

• REE and spider references: use the versioned Sun & McDonough (1989) tables. Reference assets record provenance, units, element order, and review information.
• Primitive mantle: keep the printed Table 1 values (pm-sm89) distinct from the footnote-modified variant (pm-sm89-modified). nmorb-sm89 is also available. Never select a reference from the shape of a curve.
• Units and conversions: direct elemental concentrations require explicit ppm units. Only explicitly declared wt% K2O, P2O5, and TiO2 may be converted to elemental K, P, and Ti ppm using the reviewed conversion.
• Missing data: preserve missing and below-detection-limit values as gaps. Do not replace them with zero or invented detection limits. Nonpositive values cannot be plotted on logarithmic axes.
• Harker: show covariation without automatically fitting regressions or inferring a unique petrogenetic process.
• TAS: require explicit volcanic applicability and composition basis. Boundary cases require review. Results on an as-reported basis are provisional and require provisional_classification_accepted: true.
• K2O–SiO2: use the Peccerillo–Taylor (1976) boundaries with Rickwood's (1989) correction, without extrapolation. Require an explicitly confirmed anhydrous basis and volcanic applicability. Complete four-field classification is limited to SiO2 48–63 wt%.
• Additional classification diagrams: Zr/TiO2–Nb/Y coordinate calculations have been tested, but no classification model is registered for that diagram. New boundaries require source verification and separate scientific review.
• Interpretation: enrichment, depletion, slopes, clusters, and correlations alone do not uniquely establish source, melting, fractionation, alteration, or tectonic setting.

Inspect figures at their intended final size and check the target journal's requirements. Automated tests do not replace scientific review or visual approval.

Additional references (currently in Chinese):

• Beginner troubleshooting
• Recipes and safe execution
• Data QA, composition basis, and derived variables
• K2O–SiO2 scientific contract
• v0.9 candidate audit and roadmap
• Historical v0.8 audit

.\.venv\Scripts\python.exe skills\geoskills\scripts\inspect_data.py skills\geoskills\examples\synthetic_ree_data.csv
.\.venv\Scripts\python.exe skills\geoskills\scripts\normalize_ree.py skills\geoskills\examples\synthetic_ree_data.csv --output outputs\synthetic_ree_normalized.csv

.\.venv\Scripts\python.exe skills\geoskills\scripts\plot_ree.py skills\geoskills\examples\synthetic_ree_data.csv --output-dir outputs\ree_figure --axes-frame full --legend-layout inside-auto

.\.venv\Scripts\python.exe skills\geoskills\scripts\inspect_spider_data.py skills\geoskills\examples\synthetic_spider_data.csv
.\.venv\Scripts\python.exe skills\geoskills\scripts\plot_spider.py skills\geoskills\examples\synthetic_spider_data.csv --reference pm-sm89-modified --output-dir outputs\spider_figure

.\.venv\Scripts\python.exe skills\geoskills\scripts\inspect_major_data.py skills\geoskills\examples\synthetic_major_element_data.csv
.\.venv\Scripts\python.exe skills\geoskills\scripts\plot_harker.py skills\geoskills\examples\synthetic_major_element_data.csv --x SiO2 --y TiO2,Al2O3,Fe2O3T,MgO,CaO,Na2O,K2O,P2O5 --output-dir outputs\harker_figure

.\.venv\Scripts\python.exe skills\geoskills\scripts\plot_tas.py skills\geoskills\examples\synthetic_major_element_data.csv --confirm-volcanic --composition-basis anhydrous-normalized --output-dir outputs\tas_figure

GeoSkills/
├── README.md                 English project entry point
├── README.zh-CN.md           Chinese README
├── CHANGELOG.md
├── SECURITY.md
├── AGENTS.md
├── requirements-dev.txt
├── docs/
├── skills/geoskills/
│   ├── SKILL.md
│   ├── agents/openai.yaml
│   ├── assets/
│   ├── examples/
│   ├── references/
│   └── scripts/
│       ├── geoskills.py
│       └── geoskills_core/
└── tests/

v0.8.0 was released on 2026-08-31 with six diagram types, single-column output, input budgets, and CSV export protection. Its release regression recorded 283 passing tests and 1 skip. The v0.9 candidate has separate validation evidence in its audit report.

GeoSkills is a local Skill and command-line tool; it currently has no standalone web application. Main project documentation is maintained in English, with README.zh-CN.md as the Chinese entry point.

Local research directories (local_data/, localdata/), generated output, and local environment secrets are excluded from Git in this candidate. Never commit private research data or credentials.

Report security issues through the private process in SECURITY.md. Do not put real data or vulnerability details in public issues.

The code is available under the MIT License.