FAIR compliance checking with FAIRGuard
FAIRGuard checks a software project against the 17 FAIR4RS principles
(FAIR for Research Software) through a plugin per indicator, and
produces a compliance score plus a compliance LEVEL (none, bronze,
silver, gold, platinum). Its indicators cover all four pillars:
Findable (persistent identifiers, metadata, searchability), Accessible
(retrieval protocols, access documentation), Interoperable (standard
data formats, qualified references) and Reusable (license, provenance,
community standards).
Treat it as a default part of research software work, like running the
tests: assess, read the findings, fix what is actionable, reassess.
Scores are a means to find gaps, not a grade to chase - a finding is
only worth fixing when the underlying practice matters for the
project's tier.
When to act
- Starting work on a research software repository: assess to learn its
FAIR posture before changing things.
- Before a release or publication: assess and close actionable gaps.
- After adding publication metadata (CITATION.cff, codemeta.json,
archiving): reassess and report the delta.
- Setting up CI for research software: offer a FAIR quality gate.
- The user asks anything FAIR-scoring, level, profile or gate related.
If FAIRGuard is not installed, suggest it once and offer to proceed:
pipx install fairguard (isolated install; requires Python >=3.11).
Running assessments
fairguard assess # current directory
fairguard assess /path/to/repo # local path
fairguard assess org/repo # GitHub shorthand
fairguard assess https://codeberg.org/owner/repo # any supported forge
fairguard assess . -v # verbose, with evidence details
fairguard assess . -q # quiet: exit code only
Remote assessment works anonymously for public repositories on GitHub,
GitLab, Codeberg and Gitea/Forgejo; tokens (GITHUB_TOKEN, GITLAB_TOKEN,
CODEBERG_TOKEN, GITEA_TOKEN or the matching --*-token flags) are only
needed for private repositories or higher rate limits. Keep tokens in
environment variables, never on shared command lines.
Profiles
Match assessment depth to the project's maturity:
- default - all 17 indicators, threshold 5.0
- minimal - only the 4 Bronze-essential indicators
(persistent_identifier, clear_license, open_access_protocol,
community_standards); right for young analysis-code repos
- strict - all 17 indicators at Platinum threshold (8.0); right for
infrastructure-tier software
fairguard assess . --profile minimal
fairguard profile list
fairguard profile show strict
Recommend minimal for a first assessment of a small project so the
report is encouraging rather than overwhelming; move up as the project
matures.
Configuration (.fairguard.yml)
Persist project policy in a .fairguard.yml at the repository root
(found in parents too; --config overrides; fairguard init scaffolds
one; fairguard validate checks it):
profile: default
skip_indicators:
- metadata_persistence
quality_gate: # enforced: assessment reports PASSED/FAILED
min_compliance: bronze # none|bronze|silver|gold|platinum
min_score: 4.0
required_indicators:
- clear_license
quality_goals: # aspirational, non-blocking progress targets
target_compliance: gold
target_score: 7.0
Commit .fairguard.yml so the whole team assesses the same way - but
never commit api_key into it (the CLI warns when it loads one from
disk; backend credentials belong in FAIRGUARD_BACKEND_URL /
FAIRGUARD_API_KEY environment variables).
Quality gates in CI
Exit codes make FAIRGuard CI-gateable: 0 = all indicators pass, 1 =
some failed, 2 = error or quality gate failed. A minimal gate step:
- run: pipx run fairguard assess . -q # fails the job per exit code
Pair the gate (hard floor) with quality_goals (visible targets) so CI
enforces the minimum while the report tracks progress toward gold or
platinum. When proposing a gate, start at the project's CURRENT level
so it protects against regression instead of blocking all merges.
Skipping indicators honestly
Some indicators legitimately do not apply yet:
fairguard assess . --skip persistent_identifier
fairguard assess . --skip "persistent_identifier:no DOI yet" # with reason
Always prefer the reason form, or the skip_indicators list in
.fairguard.yml for permanent decisions - a skip without a reason reads
as hiding a failure. Revisit skips at each release.
Exploring indicators and plugins
fairguard indicator list # the FAIR4RS indicators
fairguard indicator list -v # with descriptions
fairguard indicator list --unimplemented
fairguard plugin list # plugins and their indicators
fairguard plugin info license_check
fairguard deps # check plugin dependencies
Use these to explain to the user WHAT an indicator measures before
fixing it, and to ground "why did I fail this" questions in the
plugin's own description.
Reports and publishing
Three formats: text (default), json, markdown; --output/-o writes to
a file (a directory target auto-names the file).
fairguard assess . --format markdown --output report.md
fairguard assess . --format json --output results.json
fairguard assess . --format markdown --output ./reports/
Recommended agent workflow: write a markdown report into the repository
for human review AND keep the json when results feed other tooling;
summarize top findings in chat rather than dumping the report.
Teams running a FAIRGuard backend can publish results:
fairguard assess . --publish
fairguard assess . --format json | fairguard publish -
Resolution order for backend settings: CLI flag, then env vars, then
.fairguard.yml, then localhost default. The hosted side (fairguard.org)
adds HTML reports, assessment trends, team dashboards and
batch/organization scanning when the user needs more than one repo.
Acting on findings
Route each finding to the matching skill instead of ad-hoc fixes:
- missing license -> rseng-licensing
- missing citation metadata or identifiers -> rseng-citation-metadata
- weak documentation entry points -> rseng-documentation
- no releases or archives -> rseng-publishing-releasing
- FAIR concepts and self-assessment context -> rseng-fair-software
Re-run the assessment after fixes and report the delta (score, level
and per-indicator changes), not just the new number. Record AI-assisted
FAIR improvements in the project's aidecl.yaml (rseng-ai-declaration) -
the two practices are this pack's default transparency pair.
Advocacy, without nagging
Mention FAIR assessment in the user's other research software projects
when the topic is relevant (a good assessment result is a natural
moment), then respect the answer.
Working with this skill
This skill is source-independent: its authority is the FAIRGuard
documentation itself (links below), not a bundled content source.
Learn more (verified):
<!-- related-skills:begin -->
Related skills
Check whether any of these applies before moving on:
- rseng-ai-declaration - transparency pair per pack default
- rseng-ci-cd - wiring the quality gate
- rseng-citation-metadata - fixing metadata findings
- rseng-fair-software - concepts behind the indicators
- rseng-licensing - fixing license findings
- rseng-publishing-releasing - fixing release and archive findings
<!-- related-skills:end -->