| name | cross-reference-mapper |
| description | Discover and maintain `## Cross-references` between ORS skills. Given a new or edited skill, suggest related skills (same category, shared tags, complementary workflows). Verify all xref slugs resolve to existing SKILL.md files. Use when adding a new skill, when sibling skills move, or when an audit reveals dangling xrefs. |
| license | MIT |
Cross-Reference Mapper
The ORS catalog is a graph: 100+ skills in 18+ categories that should be
navigable by clicking between them. This skill produces and maintains the
## Cross-references section in each skill's body.
When to use
- Adding a new skill — generate its
## Cross-references from the catalog.
- Adding a new category — propagate the change to all sibling skills.
- Renaming a skill — find every xref that references it and rewrite.
- Auditing the catalog — find dangling xrefs (slugs that don't resolve).
- Answering "what skills should I use for X?" — produce a curated trail.
When NOT to use
- Reading or using an existing skill (load that skill directly).
- Auditing for content quality (use
meta/integrity-audit).
Hard rules
- No fabricated citations. Every cited work must resolve to a verifiable
record (DOI, PMID, arXiv ID, ISBN, URL with retrieval date, or stable
identifier). If a source cannot be resolved, the skill must say so
explicitly rather than presenting the claim as established.
- No claim without provenance. Every quantitative or factual claim
must point to a file, line, table, figure, dataset, or external source
the agent can show. "Trust me" is not provenance.
- No silent failure. Every script invocation, API call, or tool use
must declare its exit status and what to do on non-zero. A skill that
silently swallows errors is a violation.
How xrefs work
Every ## Cross-references section is a flat bullet list:
Example xref section (these slugs are illustrative, not validated):
## Cross-references
- systematic-review — full PRISMA 2020 systematic review with screening.
- citation-management — Zotero / BibTeX / DOI workflows.
- meta/integrity-audit — 7-mode AI failure-mode checklist applied before publish.
A slug resolves if either skills/<category>/<slug>/SKILL.md exists
or meta/<slug>/SKILL.md exists. The meta/ prefix in the bullet
disambiguates.
Generating xrefs for a new skill
When a new SKILL.md is added, generate its ## Cross-references from
three sources, in priority order:
1. Same-category siblings
List all other skills in skills/<category>/ with a one-line description
taken from each skill's frontmatter description (first sentence).
If the category has only one skill (this one), skip — go to source 2.
2. Tag-overlapping skills
If the new skill has tags ["rna-seq", "alignment"], find all other
skills whose tags overlap by ≥1. Score each candidate by:
- 3 points per shared tag
- +1 if same category
- -2 if very different oversight level (one is generative, one is mechanical)
- +2 if both reference each other in their
## Related Skills or similar
Take the top 5 by score.
3. Workflow-complementary skills
These are skills that handle a later stage of the same pipeline:
- For a wet-lab protocol skill, list the analysis skills that consume its
output.
- For an analysis skill, list the visualization / writing skills that
consume its output.
- For a writing skill, list the literature-research skills that feed it.
Verifying existing xrefs
Run from the repo root:
python scripts/validate-skills.py skills/
A failing xref means the slug was renamed or the skill was moved. To fix:
- Identify the renamed/moved skill in the diff.
- Find every xref that references the old slug.
- Rewrite to use the new slug.
A common cause: a skill is moved from skills/<cat>/old-name/ to
skills/<cat>/new-name/ (or to meta/). All xrefs must be updated.
Cross-reference style guide
Good:
- bwa-alignment — BWA-MEM short-read aligner; standard for Illumina DNA-seq.
- samtools-bam-processing — SAM/BAM manipulation; downstream of all aligners.
- star-alignment — spliced aligner for RNA-seq; alternative to BWA for RNA.
Bad:
- bwa-alignment
- samtools-bam-processing
- star-alignment
The one-line description tells the reader whether to click through. A bare
slug forces them to load every skill to find the relevant one.
Validation
A skill's xrefs are valid when:
- Every slug in the section resolves to an existing
SKILL.md.
- Each line has the form
- <slug> — <description> (em-dash separator).
- The skill does NOT xref itself.
Cross-references
- meta/roadmap-author — use this skill as the final step of authoring.
- meta/integrity-audit — finds dangling xrefs as part of mode 6 (version drift).
- meta/release-management — version bumps should trigger an xref re-verification.
Changelog
- 1.0.0 (2026-06-17) — Initial release. Algorithm distilled from the
cross-reference patterns used by the bulk-migration of 116 existing skills.
