# Rseng Fairguard > Covers assessing research software against the 17 FAIR4RS principles with FAIRGuard (https://www.fairguard.org): compliance scores and levels (bronze to platinum), assessment profiles, quality gates for CI, .fairguard.yml configuration, per-indicator skips, and acting on findings. Use PROACTIVELY on research software projects - at repo intake, before releases, after adding publication metadata - and act on its findings. Also use when the user asks to check FAIR compliance, wants a FAIR score, report or badge level, wants a FAIR quality gate in CI, or mentions fairguard, FAIR4RS or .fairguard.yml. (FAIR concepts, principles and hand-guided improvement are rseng-fair-software; ML artifacts are rseng-fair-ml.) - Skill: `fdiblen/rseng-fairguard` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add fdiblen/rseng-fairguard` - Raw SKILL.md: https://api.skillmd.com/api/skills/fdiblen/rseng-fairguard/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - License: CC-BY-4.0 - Author: fdiblen (https://skillmd.com/u/fdiblen) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/fdiblen/rseng-fairguard --- # 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 ```bash 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 ```bash 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): ```yaml 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: ```yaml - 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: ```bash 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 ```bash 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). ```bash 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: ```bash 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): - https://www.fairguard.org - project site, hosted reports/dashboards - https://pypi.org/project/fairguard/ - CLI package and usage docs (the package metadata's source-repository link is currently dead; use the site and PyPI page as canonical) ## 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