Map materials science terms, crystal structures, and sample descriptions to standardized ontology classes and properties — resolve natural-language concepts to ontology entries with confidence scores, translate Bravais lattice types, space groups, and lattice constants into ontology-compliant annotations, and produce full sample metadata from structured descriptions. Supports any ontology in ontology_registry.json (CMSO, ASMO, etc.). Use when annotating simulation inputs with FAIR metadata, translating "BCC iron" or "FCC copper" into formal ontology terms, preparing machine- readable sample descriptions, or bridging between lab vocabulary and ontology vocabulary, even if the user only says "what CMSO terms describe my material" or "annotate this sample for me."
Translate real-world materials science descriptions into standardized ontology annotations. Given terms like "FCC copper" or structured data like {"material": "iron", "structure": "BCC", "lattice_a": 2.87}, produce the corresponding ontology classes and properties for any registered ontology.
Requirements
Python 3.10+
No external dependencies (Python standard library only)
Requires ontology-explorer's summary JSON and ontology_registry.json
Per-ontology mapping config (<name>_mappings.json) for ontology-specific synonyms and labels
Inputs to Gather
Input
Description
Example
Ontology
Ontology name from registry
cmso, asmo
Term(s)
Natural-language materials concept(s)
"unit cell", "FCC,copper,lattice"
Crystal system
One of the 7 crystal systems
cubic, hexagonal
Bravais lattice
Lattice type (symbol or common name)
FCC, cF, BCC
Space group
Space group number (1-230)
225
Lattice parameters
a, b, c in angstroms; alpha, beta, gamma in degrees
a=3.615
Sample description
JSON dict with material properties
{"material":"copper","structure":"FCC"}
Decision Guidance
What do you need to map?
├── A concept or term to find its ontology class
│ └── concept_mapper.py --ontology <name> --term "<term>"
├── Crystal structure parameters to ontology terms
│ └── crystal_mapper.py --ontology <name> --bravais <type> --space-group <N> --a <val>
├── A full sample description to ontology annotations
│ └── sample_annotator.py --ontology <name> --sample '<json>'
└── Multiple terms at once
└── concept_mapper.py --ontology <name> --terms "term1,term2,term3"
Ontology scope — crystal/sample annotation is CMSO-only.crystal_mapper.py
and sample_annotator.py emit crystal-structure vocabulary (Crystalline Material,
Crystal Structure, Unit Cell, Space Group, lattice properties). This vocabulary is
defined by CMSO. ASMO is a simulation-methods ontology and does not define any
crystal/sample classes — so for ASMO use the concept-mapping path
(concept_mapper.py, which resolves terms like DFT, NPT, timestep, PBE to real ASMO
classes) only. If sample_annotator.py/crystal_mapper.py is run with an ontology
whose summary lacks the required classes (e.g. --ontology asmo), each unresolvable
term is flagged in results.validation_warnings and given confidence: 0.0 rather
than silently emitting an invalid term.
If the user provides natural-language terms, use concept_mapper.py to find matching ontology classes.
If the user describes crystal structure parameters, use crystal_mapper.py to map them and validate constraints.
For a complete sample description, use sample_annotator.py to produce full ontology annotations.
Review any validation warnings (e.g., lattice parameter mismatches for the crystal system).
Check unmapped_fields and suggested_properties for completeness.
Conversational Workflow Example
User: I'm setting up an MD simulation of BCC iron with lattice parameter 2.87 angstroms.
What CMSO terms should I use?
Agent: Let me map your iron sample to CMSO ontology terms.
[Runs: sample_annotator.py --ontology cmso --sample '{"material":"iron","structure":"BCC","lattice_a":2.87,"space_group":229}' --json]
Your BCC iron simulation maps to these CMSO annotations:
- **Sample**: Atomic Scale Sample (subclass of Computational Sample)
- **Material**: Crystalline Material
- **Unit Cell**: Bravais lattice = "cI" (body-centered cubic)
- **Space Group**: number = 229 (Im-3m)
- **Lattice**: a = 2.87 Å
- **Element**: Fe
Suggested additions:
- Number of atoms in the simulation cell
- Simulation cell vectors and angles
Then add "mappings_file": "myonto_mappings.json" to the ontology's entry in ontology_registry.json. No code changes needed.
Only include the sample_schema, crystal_output, material_type_rules and
annotation_routing blocks if every class/property they name actually exists in that
ontology's summary.sample_annotator.py validates emitted terms against the loaded
summary and flags any that are undefined (results.validation_warnings, confidence: 0.0).
For example, asmo_mappings.json deliberately ships onlysynonyms and
property_synonyms because ASMO is a simulation-methods ontology with no crystal/sample
vocabulary — its concept terms (DFT, NPT, timestep, PBE) all resolve, but a crystal/sample
config would emit unresolvable terms.
Error Handling
Error
Cause
Resolution
space_group must be between 1 and 230
Invalid space group number
Use a valid space group number
a must be positive
Non-positive lattice parameter
Provide positive values in angstroms
Unrecognized Bravais lattice '<x>'
Bravais symbol/name not in the recognized set
Use a common name (FCC, BCC, HCP) or a Pearson symbol (cF, cI, hP, ...)
Term exceeds maximum length of 200 characters
A --term/--terms entry is too long
Shorten the term
Too many terms (max 100)
More than 100 terms supplied
Split into smaller batches
Sample must be a non-empty dict
Empty or missing sample data
Provide a valid JSON sample dict
Sample has too many keys (max 100)
Oversized sample dict
Reduce the number of sample keys
Validation warnings (lattice)
Lattice parameters inconsistent with crystal system
Check that a=b=c for cubic, etc.
results.validation_warnings (terms)
Emitted class/property not defined in the chosen ontology (e.g. crystal terms for ASMO)
Use CMSO for crystal/sample annotation; use ASMO only for concept mapping
Interpretation Guidance
Confidence scores: 1.0 = exact label match, 0.9 = synonym-table match, 0.7 = substring match, 0.5 = description match. Note: the per-ontology synonym table is consulted before exact-label matching, so a term that is both a synonym key and a class label (e.g. space group, unit cell, atom) is reported as a 0.9 synonym match even though it coincides exactly with a class label — the matched class and IRI are still correct.
sample_annotator.py validation warnings: every emitted class/property is checked against the loaded ontology summary. Terms not defined in that ontology are flagged in results.validation_warnings (and the corresponding annotation gets a validation_warning field with confidence: 0.0). This is how the annotator signals that a crystal/sample term cannot resolve to an IRI in the chosen ontology (e.g. running --ontology asmo on a crystalline sample — see below).
Validation warnings: indicate potential mistakes (e.g., specifying a!=b for cubic). These are warnings, not errors — the mapping still proceeds.
Unmapped fields: input keys that the annotator doesn't recognize. These may need manual mapping.
Suggested properties: additional ontology properties that would make the annotation more complete.
Verification checklist
Confirmed results.validation_warnings is empty (or every entry is explained) — a non-empty list means an emitted class/property is not defined in the chosen ontology and was given confidence: 0.0; do not report such terms as valid annotations.
Recorded the match_type and confidence for each concept match and confirmed the chosen term is acceptable for its tier (1.0 exact, 0.9 synonym, 0.7 substring, 0.5 description); for any substring_* or description_class match, verified the matched class is actually the intended concept and not an incidental string hit.
For crystal mappings, recorded results.effective_system and results.bravais_lattice (the resolved Pearson symbol, e.g. cF/cI), and confirmed the input Bravais/space-group/system are mutually consistent (no "space group N implies X but Y was specified" warning in validation_warnings).
Checked lattice-parameter constraints against effective_system — confirmed no warnings such as "Cubic requires a=b" / angle-90 violations, or explicitly justified each one (warnings are advisory, the mapping still proceeds).
Listed results.unmatched (concept) and results.unmapped_fields (sample) and confirmed nothing materially important was silently dropped; ran the emitted class_browser.py suggestion for any unmatched term that should have resolved.
Reviewed results.suggested_properties and recorded which missing fields (elements, space_group, lattice_a, ...) are intentionally omitted vs. should be added before the annotation is considered complete.
Common pitfalls & rationalizations
Tempting shortcut
Why it's wrong / what to do
"The script printed annotations, so the sample is correctly annotated."
Emission is not validation. sample_annotator.py will emit a term and then flag it with validation_warning / confidence: 0.0 if it is not in the ontology — always read results.validation_warnings before trusting the output.
"I'll annotate this crystalline sample with --ontology asmo."
ASMO is a simulation-methods ontology with no crystal/sample vocabulary; every crystal term comes back at confidence: 0.0. Use CMSO for crystal/sample annotation; use ASMO only via the concept-mapping path.
"It matched the term, so the mapping is high-confidence."
A match can be a 0.7 substring or 0.5 description hit (e.g. an incidental substring inside an unrelated label). Check confidence/match_type; treat anything below an exact/synonym match as a candidate to verify, not a fact.
"space group matched a class label, so that's a 1.0 exact match."
The per-ontology synonym table is consulted before exact-label matching, so synonym-key terms (space group, unit cell, atom) report as 0.9 synonym matches even when they equal a class label. The matched class/IRI is still correct — do not "correct" the confidence.
"The space group is valid (1–230), so my crystal system is fine."
A valid space group can still contradict an explicitly given --system or Bravais lattice. Read effective_system and check for a "space group N implies X but Y was specified" entry in validation_warnings.
"My sample has a structure field, so the Bravais lattice resolved."
In the sample path strict_bravais=False: free-text structures (e.g. rocksalt, perovskite) are passed through unmapped with a warning, leaving bravais_lattice null. Verify results.bravais_lattice is the expected Pearson symbol, or supply FCC/BCC/HCP/a Pearson code.
Security
Input Validation
--ontology is validated against registered ontology names in ontology_registry.json (fixed allowlist)
--term and --terms are length-limited and used only for substring matching against pre-processed synonym tables (never interpolated into code)
--bravais is validated against a fixed set of recognized lattice type symbols
--space-group is validated as an integer between 1 and 230
Lattice parameters (--a, --b, --c, --alpha, --beta, --gamma) are validated as finite positive numbers
--sample JSON is parsed with json.loads() and validated as a non-empty dict; keys and values are type-checked
File Access
Scripts read pre-processed JSON files from the references/ directory: ontology_registry.json, *_mappings.json, *_summary.json, crystal_systems.json, element_data.json (all read-only)
No scripts write to the filesystem; all output goes to stdout
No network access is required
Tool Restrictions
Read: Used to inspect script source, reference files, and ontology data
Grep: Used to search reference files for mapping patterns or ontology terms
Glob: Used to locate reference files and ontology data
Notably, this skill has no Bash or Write access, giving it the lowest attack surface of all skills
Safety Measures
No eval(), exec(), or dynamic code generation
No subprocess calls of any kind; all logic runs within Python scripts invoked by the agent
No file writes; the skill is purely read-only and analytical
Minimal tool surface (Read, Grep, Glob only) means the agent cannot execute arbitrary commands or modify the filesystem
Limitations
Concept mapping uses string matching and a per-ontology synonym table; it does not understand arbitrary natural language
Crystal system validation checks basic constraints only (not all crystallographic rules)
The element resolver recognizes common element names and symbols but may miss unusual spellings
Bravais lattice aliases cover common usage (FCC, BCC, HCP) but not all crystallographic notation variants
References
Mapping Patterns — common mapping examples
Crystal Systems — crystal system definitions and Bravais lattices
Element Data — periodic table data
CMSO Mappings — CMSO-specific synonym tables and annotation config
Ontology Explorer — sibling skill; scripts/class_browser.py --ontology <name> --search <term> browses classes when a concept is unmatched
Version History
Date
Version
Changes
2026-06-23
1.2
Validate emitted terms against the loaded ontology (ASMO crystal/sample terms now flagged, not silently emitted); document ASMO is concept-mapping only; clarify synonym-vs-exact confidence precedence; self-contained class_browser suggestion; harden input validation (term/sample size caps, Bravais allowlist)
2026-02-25
1.1
Refactored for multi-ontology support: externalized CMSO-specific knowledge to config
2026-02-25
1.0
Initial release with CMSO mapping support
1---2name: ontology-mapper3description: >4 Map materials science terms, crystal structures, and sample descriptions to5 standardized ontology classes and properties — resolve natural-language6 concepts to ontology entries with confidence scores, translate Bravais7 lattice types, space groups, and lattice constants into ontology-compliant8 annotations, and produce full sample metadata from structured descriptions.9 Supports any ontology in ontology_registry.json (CMSO, ASMO, etc.). Use10 when annotating simulation inputs with FAIR metadata, translating "BCC11 iron" or "FCC copper" into formal ontology terms, preparing machine-12 readable sample descriptions, or bridging between lab vocabulary and13 ontology vocabulary, even if the user only says "what CMSO terms describe14 my material" or "annotate this sample for me."15allowed-tools: Read, Grep, Glob16metadata:17 source: https://skillmd.com/skills/heshamfs/ontology-mapper18 author: HeshamFS19 version: "1.2.2"20 security_tier: low21 security_reviewed: true22 tested_with:23 - claude-code24 last_evaluated: "2026-06-24"25 eval_cases: 626 last_reviewed: "2026-06-23"27 standards:28 - "CMSO (Computational Material Sample Ontology)"29 - "ASMO (Atomistic Simulation Methods Ontology)"30 - "International Tables for Crystallography (7 crystal systems, 14 Bravais lattices via Pearson symbols, 230 space groups)"31 - "FAIR data principles (Wilkinson et al. 2016)"32---3334# Ontology Mapper3536## Goal3738Translate real-world materials science descriptions into standardized ontology annotations. Given terms like "FCC copper" or structured data like `{"material": "iron", "structure": "BCC", "lattice_a": 2.87}`, produce the corresponding ontology classes and properties for any registered ontology.3940## Requirements4142- Python 3.10+43- No external dependencies (Python standard library only)44- Requires ontology-explorer's summary JSON and `ontology_registry.json`45- Per-ontology mapping config (`<name>_mappings.json`) for ontology-specific synonyms and labels4647## Inputs to Gather4849| Input | Description | Example |50|-------|-------------|---------|51| Ontology | Ontology name from registry | `cmso`, `asmo` |52| Term(s) | Natural-language materials concept(s) | `"unit cell"`, `"FCC,copper,lattice"` |53| Crystal system | One of the 7 crystal systems | `cubic`, `hexagonal` |54| Bravais lattice | Lattice type (symbol or common name) | `FCC`, `cF`, `BCC` |55| Space group | Space group number (1-230) | `225` |56| Lattice parameters | a, b, c in angstroms; alpha, beta, gamma in degrees | `a=3.615` |57| Sample description | JSON dict with material properties | `{"material":"copper","structure":"FCC"}` |5859## Decision Guidance6061```62What do you need to map?63├── A concept or term to find its ontology class64│ └── concept_mapper.py --ontology <name> --term "<term>"65├── Crystal structure parameters to ontology terms66│ └── crystal_mapper.py --ontology <name> --bravais <type> --space-group <N> --a <val>67├── A full sample description to ontology annotations68│ └── sample_annotator.py --ontology <name> --sample '<json>'69└── Multiple terms at once70 └── concept_mapper.py --ontology <name> --terms "term1,term2,term3"71```7273> **Ontology scope — crystal/sample annotation is CMSO-only.** `crystal_mapper.py`74> and `sample_annotator.py` emit crystal-structure vocabulary (Crystalline Material,75> Crystal Structure, Unit Cell, Space Group, lattice properties). This vocabulary is76> defined by **CMSO**. **ASMO is a simulation-methods ontology and does not define any77> crystal/sample classes** — so for ASMO use the concept-mapping path78> (`concept_mapper.py`, which resolves terms like DFT, NPT, timestep, PBE to real ASMO79> classes) only. If `sample_annotator.py`/`crystal_mapper.py` is run with an ontology80> whose summary lacks the required classes (e.g. `--ontology asmo`), each unresolvable81> term is flagged in `results.validation_warnings` and given `confidence: 0.0` rather82> than silently emitting an invalid term.8384## Script Outputs (JSON Fields)8586| Script | Key Outputs |87|--------|-------------|88| `scripts/concept_mapper.py` | `results.matches`, `results.unmatched`, `results.suggestions` |89| `scripts/crystal_mapper.py` | `results.ontology_classes`, `results.ontology_properties`, `results.effective_system`, `results.bravais_lattice`, `results.validation_warnings` |90| `scripts/sample_annotator.py` | `results.annotations`, `results.sample_type`, `results.material_type`, `results.unmapped_fields`, `results.suggested_properties`, `results.validation_warnings` |9192## Workflow93941. If the user provides natural-language terms, use `concept_mapper.py` to find matching ontology classes.952. If the user describes crystal structure parameters, use `crystal_mapper.py` to map them and validate constraints.963. For a complete sample description, use `sample_annotator.py` to produce full ontology annotations.974. Review any validation warnings (e.g., lattice parameter mismatches for the crystal system).985. Check `unmapped_fields` and `suggested_properties` for completeness.99100## Conversational Workflow Example101102```103User: I'm setting up an MD simulation of BCC iron with lattice parameter 2.87 angstroms.104 What CMSO terms should I use?105106Agent: Let me map your iron sample to CMSO ontology terms.107108[Runs: sample_annotator.py --ontology cmso --sample '{"material":"iron","structure":"BCC","lattice_a":2.87,"space_group":229}' --json]109110Your BCC iron simulation maps to these CMSO annotations:111112- **Sample**: Atomic Scale Sample (subclass of Computational Sample)113- **Material**: Crystalline Material114- **Unit Cell**: Bravais lattice = "cI" (body-centered cubic)115- **Space Group**: number = 229 (Im-3m)116- **Lattice**: a = 2.87 Å117- **Element**: Fe118119Suggested additions:120- Number of atoms in the simulation cell121- Simulation cell vectors and angles122```123124## CLI Examples125126```bash127# Map a single concept128python3 skills/ontology/ontology-mapper/scripts/concept_mapper.py \129 --ontology cmso --term "space group" --json130131# Map multiple terms132python3 skills/ontology/ontology-mapper/scripts/concept_mapper.py \133 --ontology cmso --terms "FCC,copper,lattice constant" --json134135# Map crystal parameters (with ontology-specific labels)136python3 skills/ontology/ontology-mapper/scripts/crystal_mapper.py \137 --ontology cmso --bravais FCC --space-group 225 --a 3.615 --json138139# Map crystal parameters (generic labels, no ontology specified)140python3 skills/ontology/ontology-mapper/scripts/crystal_mapper.py \141 --bravais FCC --space-group 225 --a 3.615 --json142143# Annotate a full sample144python3 skills/ontology/ontology-mapper/scripts/sample_annotator.py \145 --ontology cmso \146 --sample '{"material":"copper","structure":"FCC","space_group":225,"lattice_a":3.615}' \147 --json148```149150## Adding a New Ontology151152To support a new ontology, create a `<name>_mappings.json` in `references/`:153154```json155{156 "ontology": "myonto",157 "synonyms": { "simulation method": "Simulation Method", ... },158 "property_synonyms": { "timestep": "has timestep", ... },159 "material_type_rules": { "keyword_rules": [...], "default": "Material" },160 "sample_schema": { "sample_class": "Simulation", ... },161 "crystal_output": { "base_classes": [...], "property_map": {...} },162 "annotation_routing": { "unit_cell_indicators": [...], ... }163}164```165166Then add `"mappings_file": "myonto_mappings.json"` to the ontology's entry in `ontology_registry.json`. No code changes needed.167168**Only include the `sample_schema`, `crystal_output`, `material_type_rules` and169`annotation_routing` blocks if every class/property they name actually exists in that170ontology's summary.** `sample_annotator.py` validates emitted terms against the loaded171summary and flags any that are undefined (`results.validation_warnings`, `confidence: 0.0`).172For example, `asmo_mappings.json` deliberately ships **only** `synonyms` and173`property_synonyms` because ASMO is a simulation-methods ontology with no crystal/sample174vocabulary — its concept terms (DFT, NPT, timestep, PBE) all resolve, but a crystal/sample175config would emit unresolvable terms.176177## Error Handling178179| Error | Cause | Resolution |180|-------|-------|------------|181| `space_group must be between 1 and 230` | Invalid space group number | Use a valid space group number |182| `a must be positive` | Non-positive lattice parameter | Provide positive values in angstroms |183| `Unrecognized Bravais lattice '<x>'` | Bravais symbol/name not in the recognized set | Use a common name (FCC, BCC, HCP) or a Pearson symbol (cF, cI, hP, ...) |184| `Term exceeds maximum length of 200 characters` | A `--term`/`--terms` entry is too long | Shorten the term |185| `Too many terms (max 100)` | More than 100 terms supplied | Split into smaller batches |186| `Sample must be a non-empty dict` | Empty or missing sample data | Provide a valid JSON sample dict |187| `Sample has too many keys (max 100)` | Oversized sample dict | Reduce the number of sample keys |188| Validation warnings (lattice) | Lattice parameters inconsistent with crystal system | Check that a=b=c for cubic, etc. |189| `results.validation_warnings` (terms) | Emitted class/property not defined in the chosen ontology (e.g. crystal terms for ASMO) | Use CMSO for crystal/sample annotation; use ASMO only for concept mapping |190191## Interpretation Guidance192193- **Confidence scores**: 1.0 = exact label match, 0.9 = synonym-table match, 0.7 = substring match, 0.5 = description match. Note: the per-ontology synonym table is consulted *before* exact-label matching, so a term that is both a synonym key and a class label (e.g. `space group`, `unit cell`, `atom`) is reported as a 0.9 synonym match even though it coincides exactly with a class label — the matched class and IRI are still correct.194- **`sample_annotator.py` validation warnings**: every emitted class/property is checked against the loaded ontology summary. Terms not defined in that ontology are flagged in `results.validation_warnings` (and the corresponding annotation gets a `validation_warning` field with `confidence: 0.0`). This is how the annotator signals that a crystal/sample term cannot resolve to an IRI in the chosen ontology (e.g. running `--ontology asmo` on a crystalline sample — see below).195- **Validation warnings**: indicate potential mistakes (e.g., specifying a!=b for cubic). These are warnings, not errors — the mapping still proceeds.196- **Unmapped fields**: input keys that the annotator doesn't recognize. These may need manual mapping.197- **Suggested properties**: additional ontology properties that would make the annotation more complete.198199## Verification checklist200201- [ ] Confirmed `results.validation_warnings` is empty (or every entry is explained) — a non-empty list means an emitted class/property is **not defined in the chosen ontology** and was given `confidence: 0.0`; do not report such terms as valid annotations.202- [ ] Recorded the `match_type` and `confidence` for each concept match and confirmed the chosen term is acceptable for its tier (1.0 exact, 0.9 synonym, 0.7 substring, 0.5 description); for any `substring_*` or `description_class` match, verified the matched class is actually the intended concept and not an incidental string hit.203- [ ] For crystal mappings, recorded `results.effective_system` and `results.bravais_lattice` (the resolved Pearson symbol, e.g. `cF`/`cI`), and confirmed the input Bravais/space-group/system are mutually consistent (no "space group N implies X but Y was specified" warning in `validation_warnings`).204- [ ] Checked lattice-parameter constraints against `effective_system` — confirmed no warnings such as "Cubic requires a=b" / angle-90 violations, or explicitly justified each one (warnings are advisory, the mapping still proceeds).205- [ ] Listed `results.unmatched` (concept) and `results.unmapped_fields` (sample) and confirmed nothing materially important was silently dropped; ran the emitted `class_browser.py` suggestion for any unmatched term that should have resolved.206- [ ] Reviewed `results.suggested_properties` and recorded which missing fields (elements, space_group, lattice_a, ...) are intentionally omitted vs. should be added before the annotation is considered complete.207208## Common pitfalls & rationalizations209210| Tempting shortcut | Why it's wrong / what to do |211|-------------------|-----------------------------|212| "The script printed annotations, so the sample is correctly annotated." | Emission is not validation. `sample_annotator.py` will emit a term and then flag it with `validation_warning` / `confidence: 0.0` if it is not in the ontology — always read `results.validation_warnings` before trusting the output. |213| "I'll annotate this crystalline sample with `--ontology asmo`." | ASMO is a simulation-methods ontology with **no crystal/sample vocabulary**; every crystal term comes back at `confidence: 0.0`. Use CMSO for crystal/sample annotation; use ASMO only via the concept-mapping path. |214| "It matched the term, so the mapping is high-confidence." | A match can be a 0.7 substring or 0.5 description hit (e.g. an incidental substring inside an unrelated label). Check `confidence`/`match_type`; treat anything below an exact/synonym match as a candidate to verify, not a fact. |215| "`space group` matched a class label, so that's a 1.0 exact match." | The per-ontology synonym table is consulted **before** exact-label matching, so synonym-key terms (`space group`, `unit cell`, `atom`) report as 0.9 synonym matches even when they equal a class label. The matched class/IRI is still correct — do not "correct" the confidence. |216| "The space group is valid (1–230), so my crystal system is fine." | A valid space group can still contradict an explicitly given `--system` or Bravais lattice. Read `effective_system` and check for a "space group N implies X but Y was specified" entry in `validation_warnings`. |217| "My sample has a `structure` field, so the Bravais lattice resolved." | In the sample path `strict_bravais=False`: free-text structures (e.g. `rocksalt`, `perovskite`) are passed through unmapped with a warning, leaving `bravais_lattice` null. Verify `results.bravais_lattice` is the expected Pearson symbol, or supply FCC/BCC/HCP/a Pearson code. |218219## Security220221### Input Validation222- `--ontology` is validated against registered ontology names in `ontology_registry.json` (fixed allowlist)223- `--term` and `--terms` are length-limited and used only for substring matching against pre-processed synonym tables (never interpolated into code)224- `--bravais` is validated against a fixed set of recognized lattice type symbols225- `--space-group` is validated as an integer between 1 and 230226- Lattice parameters (`--a`, `--b`, `--c`, `--alpha`, `--beta`, `--gamma`) are validated as finite positive numbers227- `--sample` JSON is parsed with `json.loads()` and validated as a non-empty dict; keys and values are type-checked228229### File Access230- Scripts read pre-processed JSON files from the `references/` directory: `ontology_registry.json`, `*_mappings.json`, `*_summary.json`, `crystal_systems.json`, `element_data.json` (all read-only)231- No scripts write to the filesystem; all output goes to stdout232- No network access is required233234### Tool Restrictions235- **Read**: Used to inspect script source, reference files, and ontology data236- **Grep**: Used to search reference files for mapping patterns or ontology terms237- **Glob**: Used to locate reference files and ontology data238- Notably, this skill has **no Bash or Write access**, giving it the lowest attack surface of all skills239240### Safety Measures241- No `eval()`, `exec()`, or dynamic code generation242- No subprocess calls of any kind; all logic runs within Python scripts invoked by the agent243- No file writes; the skill is purely read-only and analytical244- Minimal tool surface (Read, Grep, Glob only) means the agent cannot execute arbitrary commands or modify the filesystem245246## Limitations247248- Concept mapping uses string matching and a per-ontology synonym table; it does not understand arbitrary natural language249- Crystal system validation checks basic constraints only (not all crystallographic rules)250- The element resolver recognizes common element names and symbols but may miss unusual spellings251- Bravais lattice aliases cover common usage (FCC, BCC, HCP) but not all crystallographic notation variants252253## References254255- [Mapping Patterns](references/mapping_patterns.md) — common mapping examples256- [Crystal Systems](references/crystal_systems.json) — crystal system definitions and Bravais lattices257- [Element Data](references/element_data.json) — periodic table data258- [CMSO Mappings](references/cmso_mappings.json) — CMSO-specific synonym tables and annotation config259- [CMSO Guide](../ontology-explorer/references/cmso_guide.md) — CMSO ontology overview260- [Ontology Explorer](../ontology-explorer/) — sibling skill; `scripts/class_browser.py --ontology <name> --search <term>` browses classes when a concept is unmatched261262## Version History263264| Date | Version | Changes |265|------|---------|---------|266| 2026-06-23 | 1.2 | Validate emitted terms against the loaded ontology (ASMO crystal/sample terms now flagged, not silently emitted); document ASMO is concept-mapping only; clarify synonym-vs-exact confidence precedence; self-contained class_browser suggestion; harden input validation (term/sample size caps, Bravais allowlist) |267| 2026-02-25 | 1.1 | Refactored for multi-ontology support: externalized CMSO-specific knowledge to config |268| 2026-02-25 | 1.0 | Initial release with CMSO mapping support |
Run npx get-skill add heshamfs/ontology-mapper in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
Map materials science terms, crystal structures, and sample descriptions to standardized ontology classes and properties — resolve natural-language concepts to ontology entries with confidence scores, translate Bravais lattice types, space groups, and lattice constants into ontology-compliant annotations, and produce full sample metadata from structured descriptions. Supports any ontology in ontology_registry.json (CMSO, ASMO, etc.). Use when annotating simulation inputs with FAIR metadata, translating "BCC iron" or "FCC copper" into formal ontology terms, preparing machine- readable sample descriptions, or bridging between lab vocabulary and ontology vocabulary, even if the user only says "what CMSO terms describe my material" or "annotate this sample for me." It is listed under Coding & Dev Tools on SkillMD.
This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: CAUTION, Skill Scanner: PASS. Capability flags: executes scripts. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.
HeshamFS (@heshamfs) published this skill. Their other Agent Skills are listed on their SkillMD profile.