Agent skill

Unfairgaps

by AyanbekDos in AyanbekDos/unfairgaps-os

Find documented UNFAIRGAPS - systemic regulatory holes where a product can plug the leak - using court filings, regulatory fines, and enforcement data.

MITAuto-check passedMarketing & SEO

Install Unfairgaps

skills CLI
$ npx skills add AyanbekDos/unfairgaps-os --skill unfairgaps -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install AyanbekDos/unfairgaps-os unfairgaps --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/AyanbekDos/unfairgaps-os.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/unfairgaps .claude/skills/unfairgaps && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
unfairgaps
GitHub stars
112
Token cost
~3.4k tokens
SKILL.md length
1,510 words
Files
6 (incl. references)
Skills in repo
1
Repo updated
First seen
Licence
MIT

At a glance

Find documented UNFAIRGAPS - systemic regulatory holes where a product can plug the leak - using court filings, regulatory fines, and enforcement data.

  • Works in 5 steps: Research plan (≤400 tokens) → Candidate pool (10-14 WebSearch queries) → Evidence ledger (the critical step) → …
  • Tasks that involve SEO audit
  • SKILL.md covers Phase 1 - Research plan (≤400…, Phase 2 - Candidate pool…, Phase 3 - Evidence ledger (the… and Phase 3.5 - Unfairgap pattern…, plus 1 more section
  • Calls python; needs PERPLEXITY_API_KEY

What it does

Unfairgaps is an agent skill from AyanbekDos/unfairgaps-os. Find documented UNFAIRGAPS - systemic regulatory holes where a product can plug the leak - using court filings, regulatory fines, and enforcement data. Five operations in one methodology - industry-scan, validate-idea, site-audit, customer-pains, profession-scan. Dual mode - native Claude Code (WebSearch+WebFetch) or delegates to run.py if PERPLEXITYAPIKEY is set. profession-scan is native-only and country-aware (any country).

Its SKILL.md is about 3.4k tokens, which your agent loads only when the skill is triggered. The skill folder holds 6 other files, including reference files (for example `references/customer-pains.md`, `references/industry-scan.md` and `references/profession-scan.md`).

It sits in Marketing & SEO, covering SEO audit. It works with Perplexity. The repository describes itself as: Find real business pain points from court filings, regulatory fines, and enforcement data. 4 pipelines. Works in any country. One API key. The licence is MIT.

When your agent uses it

  • Tasks that involve SEO audit

Example prompts

  • “/unfairgaps”

Requirements

  • Python 3
  • A credential in PERPLEXITY_API_KEY

Workflow steps

5 steps, taken from the step headings in SKILL.md.

  1. Research plan (≤400 tokens)
  2. Candidate pool (10-14 WebSearch queries)
  3. Evidence ledger (the critical step)
  4. 5 - Unfairgap pattern detection (THE PRODUCT)
  5. Final report

What it can do on your machine

Read from SKILL.md and the folder at commit a922bbc. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • python

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names these keys or tokens, usually read from environment variables:

    • PERPLEXITY_API_KEY

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Unfairgaps loads about 3.4k tokens when it runs, and up to ~10k if it reads all its reference files. Until then it costs about 111 tokens; SKILL.md has 1,510 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~111
When it runs · the whole SKILL.md, loaded when a task matches
~3.4k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~10k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from AyanbekDos/unfairgaps-os at commit a922bbc, republished under its MIT licence (© AyanbekDos). 1,510 words, ~3,393 tokens.

Download SKILL.mdSave it as .claude/skills/unfairgaps/SKILL.md (or your agent's skills folder). This skill also uses 5 other files; get the full folder from GitHub.
name
unfairgaps
description
Find documented UNFAIRGAPS - systemic regulatory holes where a product can plug the leak - using court filings, regulatory fines, and enforcement data. Five operations in one methodology - industry-scan, validate-idea, site-audit, customer-pains, profession-scan. Dual mode - native Claude Code (WebSearch+WebFetch) or delegates to run.py if PERPLEXITY_API_KEY is set. profession-scan is native-only and country-aware (any country).
version
0.7.0

THE ONE THING TO REMEMBER

We are not finding customers to sell to. We are finding UNFAIRGAPS - systemic holes in a regulatory regime where a good product can plug the leak for EVERYONE who hasn't been caught yet.

A $72M jury verdict is interesting only if it exposes a systemic gap (e.g., "no evidence chain for training compliance"), not because one company got hit.

A good event corroborates a SYSTEMIC PATTERN. A great report groups events into 3-5 confirmed systemic patterns, each with a clear answer to:

  • Who will pay to avoid ending up in this data?
  • What product could plug this hole?
  • Why now - what's changing in enforcement/technology/market that makes this urgent?

An event with no corroboration in the ledger is anecdotal - report it separately, do not pretend it's a wedge.


One methodology, five operations

Four operations share the same 4-phase event-collection protocol (below). The fifth operation, profession-scan, uses a different 3-phase regulatory-profile protocol described in its own reference. Parse the user's intent into one of these operations, then load the matching op-specific reference from references/ for that operation's details.

OperationInputOutputReference
industry-scanindustry + countryPain report: 3-5 CONFIRMED unfairgaps in that industry × country, each with product sketchindustry-scan.md
validate-ideabusiness idea + countryVALIDATED / PROMISING / WEAK / NO_EVIDENCE / SATURATED verdict grounded in enforcement datavalidate-idea.md
site-auditURLClaims-vs-reality audit: per-claim verdicts + missed unfairgaps the site ignoressite-audit.md
customer-painsURLB2B2C unfairgaps affecting YOUR customers' customers, with pitch templates for outboundcustomer-pains.md
profession-scanprofession + country (any country; auto-localizes regulators, language, currency)Pain bundle for a profession: 8-15 pains with skill_specs (calculator / checklist / template / reference / advisor)profession-scan.md

How to pick the operation from user input:

  • "scan X in Y" / "find pains in <industry> <country>" -> industry-scan
  • "validate <idea>" / "is <idea> real pain" / "should I build <X>" -> validate-idea
  • "audit <url>" / "check claims on <url>" / "is <url> real or fluff" -> site-audit
  • "find pains for <url>'s customers" / "customer pains <url>" / "outbound angles for <url>" -> customer-pains
  • "profession-scan <X>" / "find pains for <profession>" / "scan <profession> in US" / "what pains does a <profession> have" -> profession-scan

If the user's request is ambiguous, ask which operation they want. Do not guess.


Execution mode selection (shared)

Before running any operation:

  • If the operation is profession-scan: always run the native 3-phase protocol described in references/profession-scan.md. No CLI path. run.py does not implement this operation. Skip the rest of this section and load the profession-scan reference.
  • If PERPLEXITY_API_KEY is set in env AND user didn't explicitly say "use claude code" / "no api" / "native":
    • Delegate to python run.py <operation> <args> (the CLI path; faster, deterministic, scriptable). Stop here.
  • Otherwise: run the native flow below using Claude Code's WebSearch + WebFetch.

The native flow uses 0 API keys - entirely free via your Claude Code / Cursor / Codex subscription.


Native flow - shared 4-phase protocol

This protocol is mandatory for all four operations. Skip or reorder phases and the output becomes untrustworthy. Every phase produces a visible artifact. Do not synthesize the final report before Phase 4.

Phase 1 - Research plan (≤400 tokens)

Produce a compact plan BEFORE searching. See the op-specific reference for its exact schema. Generally includes:

  • The input interpreted into a structured form
  • Primary languages for retrieval (e.g., [en] for US, [ru, kk] for KZ, [de, en] for DE)
  • Regulatory bodies, court systems, jurisdictions in scope
  • 3-5 pain hypotheses BEFORE searching (to be tested)
  • Stop condition (minimum evidence threshold for a valid result)
  • Fetch budget (hard cap)

Phase 2 - Candidate pool (10-14 WebSearch queries)

Compose queries across these categories (expanded in v0.3 after empirical gap-analysis vs Perplexity):

  • 2 REGULATORY FINES (agency + specific pain + year)
  • 2 LEGAL CASES (lawsuits, settlements, class actions)
  • 2 JURY VERDICTS (8-figure + jury awards, "verdict million {industry} 2024 2025")
  • 2 REPEAT VIOLATOR / SVEP (for US: "SVEP {industry}", "repeat violator"; other countries: equivalent)
  • 1 BANKRUPTCY / CHAPTER 7 ("{industry} contractor Chapter 7 bankruptcy 2024 2025")
  • 1 AGGREGATOR HUNT ("biggest OSHA fines {year}", "top {industry} lawsuits {year}" - aggregator sites pre-curate primary-source lists)
  • 1 INDUSTRY COST (reports, losses, financial impact)
  • 1 SPECIFIC INCIDENT (single high-$ event with known name)
  • 0-2 EVENT-MARKER FOLLOW-UPS (if >30% of first-pass results are norms/penalty-tables, compose follow-ups with action verbs: "fined", "sentenced", "settled", "оштрафована", "приговор", etc.)

Query rules:

  • Include the target noun verbatim (industry / segment / pain / whatever the op focuses on)
  • Include at least one financial keyword (lawsuit, fine, penalty, settlement, million, cost, loss, verdict, Chapter 7 - or native-language equivalent)
  • Include year range 2024 2025 2026
  • Native-language queries are mandatory for non-English countries. English-only = fake "no evidence".
  • At least 2 queries target .gov / regulator / court-system sources explicitly
  • v0.3 lesson: if the first pass returns penalty tables / code articles rather than named-party events, that's a diagnostic signal - immediately compose follow-ups with action-verb markers.

Emit candidate pool as a table, scored by domain_class:

  • primary_gov (+4) - .gov, federal/state regulator, court docket
  • primary_court (+4) - court opinion databases, official dockets
  • aggregator_primary (+3.5) - curated lists of primary-source events (Taproot OSHA fines, JDSupra, CourtListener top verdicts - one fetch yields 10-15 named events)
  • quasi_primary (+3) - regulator press releases, enforcement DB mirrors
  • secondary_trade (+2) - industry trade press with named case/$ (Insurance Journal, Construction Dive, ENR, law-firm analyses naming defendants)
  • secondary_news (+1) - major news outlets with named case/$
  • tertiary_blog (0) - law-firm marketing blogs, consulting opinion, LinkedIn
  • drop junk - SEO content, vendor marketing, norm/penalty tables without events

Pool should be 20-60 candidates. Dedupe by URL before scoring.

Show full SKILL.md (636 more words)Show less

Phase 3 - Evidence ledger (the critical step)

Fetch the top 8-12 candidates by global score (NOT top-N per query). Budget caps at 14 total fetches including follow-ups.

For each fetched page, IMMEDIATELY write a compact evidence card (≤150 tokens) and append to the ledger. Do not keep raw page text in context - compress then discard.

Card schema (shared; op-specific references may add fields):

yaml
- id: ev_XXX
  event_key: "<authority>|<action_type>|<date>|<actor>|<docket_or_id>"   # event-level canonical key for dedup
  pain: "<1-2 sentences, what went wrong and who lost money>"
  actor: "<company/role sanctioned or suffering>"
  jurisdiction: "<federal | state name | country | EU-level>"
  evidence_type: "court_record | regulatory_fine | industry_report | news"
  source_class: "primary_gov | primary_court | aggregator_primary | quasi_primary | secondary_trade | secondary_news"
  financial_impact: "<exact amount + currency, or null>"
  date: "<YYYY-MM or YYYY>"
  language: "<en | ru | de | ...>"
  pinpoint_citation:
    url: "<full URL>"
    locator: "<page N, section X, paragraph P - or quoted selector>"
    quote: "<≤200 char verbatim excerpt proving the claim>"
  evidence_quality: "hard | soft"
  notes: "<optional - contradicts ev_XXX, corroborates, or coverage_gap>"

Event-level dedup: before appending, check if event_key matches an existing card. If yes, merge pinpoint_citation into corroborating_urls: [] on the existing card. Don't create duplicates.

Follow-up fetches (max 4 of the 14 cap): after initial 8-10 fetches, if the ledger has <6 hard events OR a pain-hypothesis from Phase 1 has zero evidence, do up to 4 targeted follow-up fetches.

Hard stop at 14 fetches. If still thin, emit coverage_gap notes and proceed to Phase 4 - do NOT fabricate breadth.

Phase 3.5 - Unfairgap pattern detection (THE PRODUCT)

Read through the Evidence Ledger and group events into candidate unfairgap hypotheses - systemic regulatory holes that recur across multiple cases.

For each candidate pattern, emit an UNFAIRGAP entry:

yaml
- unfairgap_id: ug_XXX
  hypothesis: "<1 sentence: the systemic hole in plain language>"
  status: "CONFIRMED_SYSTEMIC | EMERGING_PATTERN | ANECDOTAL"
  corroborating_events: [ev_XXX, ev_YYY, ev_ZZZ]
  event_count: N
  scale_signal: "<$ range across events; sum if meaningful>"
  regulatory_source: "<which regulator(s); which statutes>"
  product_sketch:
    what: "<concrete product, 1-2 sentences>"
    who_pays: "<specific buyer persona - NOT the sanctioned companies, their NOT-YET-SANCTIONED peers>"
    why_now: "<what makes this urgent in 2024-2026 specifically>"
    what_kills_it: "<biggest risk to the wedge>"
  coverage_caveats: "<what we don't know that would change the call>"

Status rules (non-negotiable):

  • CONFIRMED_SYSTEMIC - 3+ events corroborate the same gap, AND at least 1 is primary / quasi-primary / aggregator-primary source, AND events span 2+ companies or 2+ jurisdictions (or 1 company 3+ times = pattern of regulator behavior)
  • EMERGING_PATTERN - 2 events corroborating, or 3+ events but all tertiary/blog/single-source
  • ANECDOTAL - 1 event only, OR a big-$ event that cannot generalize

Do not promote ANECDOTAL to CONFIRMED with clever arguments. If the data isn't there, say so.

Drop-rule: events that don't slot into any unfairgap pattern don't appear in Phase 4 main topics. They go to an "Anecdotal signals" appendix only.

Target: 3-5 CONFIRMED_SYSTEMIC unfairgaps per run. If you have 0-2, the run didn't find a pattern - say so in the report, don't pad.

Phase 4 - Final report

Op-specific (see reference). General shape:

  • Summary (data-grounded, 2-3 sentences - NOT a catalog of fines)
  • Unfairgaps found (CONFIRMED + EMERGING, each with product sketch)
  • Anecdotal signals (single-event appendix, honest)
  • Evidence ledger reference
  • Coverage caveats (what you don't know)
  • Run manifest (queries, fetches, dedup decisions, counts)

Save under an op-specific filename (see reference).


Hard rules (apply to all operations)

  1. Do not write the final report before Phase 3.5 is complete. The ledger and unfairgap entries are persistent artifacts.
  2. Do not fabricate source quotas. If a jurisdiction genuinely has 1 primary source, report 1 primary source and flag coverage_gap. Padding with unrelated cases = failure.
  3. Native-language queries mandatory for non-English countries.
  4. Do not exceed 14 fetches. If exhausted and ledger thin, ship with caveats.
  5. Do not synthesize from raw fetched page text. Compress each fetch into a card immediately; drop raw text.
  6. Every finding needs pinpoint_citation with url + locator + quote. URL-only is not a citation.
  7. PDF handling: If WebFetch on a .gov/court PDF returns "cannot parse binary content," the PDF is cached to the tool-results path returned. Use Read tool on that cache path - it extracts full document content. Treat as canonical PDF workflow.
  8. Blocked primary sources: Some regulator domains (osha.gov, dir.ca.gov) return HTTP 403 or timeout on direct WebFetch. When this happens: (a) search for aggregator_primary sites that cite the same release verbatim; (b) preserve the canonical event_key so evidence from the aggregator merges with the primary when reachable later. Do NOT drop the event.
  9. CONFIRMED_SYSTEMIC requires ≥3 events + ≥2 companies. Non-negotiable. 1-event "opportunity" in the main section = skill failure.

Then - load the op-specific reference

Once you've determined which of the 5 operations the user wants and you've briefed yourself on the relevant protocol above, read the matching reference for input-parsing, query-category specifics, reference-card-schema additions, and the final-report format:

  • references/industry-scan.md
  • references/validate-idea.md
  • references/site-audit.md
  • references/customer-pains.md
  • references/profession-scan.md (uses its own 3-phase protocol - SCOPE -> Pains -> Bundle; ignore the shared 4-phase rules)

Each reference is small (<150 lines) - read the one that applies, then execute.

© AyanbekDos, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 5 other files (references) in skills/unfairgaps of AyanbekDos/unfairgaps-os.

  • SKILL.md
  • references/customer-pains.md
  • references/industry-scan.md
  • references/profession-scan.md
  • references/site-audit.md
  • references/validate-idea.md

Open the folder on GitHubat commit a922bbc

Compare with similar skills

Unfairgaps next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Unfairgaps compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Unfairgaps this skillAyanbekDos/unfairgaps-os112—~3.4kAutomated safety check: PassMIT
GEO-First SEO Audit Toolzubair-trabzada/geo-seo-claude11k—~2.8kAutomated safety check: NotesMIT
GEO Platform Optimizerzubair-trabzada/geo-seo-claude11k2 repos~4.7kAutomated safety check: NotesMIT
AI Discoverability AuditBrianRWagner/ai-marketing-claude-code-skills440—~2.3kAutomated safety check: PassNone
SEO Auditshadcn-labs/agentcn490—~598Automated safety check: PassMIT
Global SEO Growthminhnv0807/ai-business-skills610—~5kAutomated safety check: PassMIT

Similar skills

  • GEO-First SEO Audit Tool

    zubair-trabzada/geo-seo-claude

    Audits a website for AI search visibility across ChatGPT, Claude, Perplexity and Google AI Overviews while checking traditional SEO, schema and E-E-A-T content quality.

    11k GitHub stars~2.8k tokensUpdated today
    Marketing & SEOAuto-check: notes
  • GEO Platform Optimizer

    zubair-trabzada/geo-seo-claude

    Audits a site for AI search visibility one platform at a time, scoring Google AI Overviews, ChatGPT, Perplexity, Gemini and Bing Copilot and listing gaps to fix.

    11k GitHub starsUsed in 2 repos~4.7k tokens
    Marketing & SEOAuto-check: notes
  • AI Discoverability Audit

    BrianRWagner/ai-marketing-claude-code-skills

    Audits how a brand is described by AI search tools such as ChatGPT, Perplexity and Gemini, then produces a scored report, action plan and re-audit schedule.

    440 GitHub stars~2.3k tokensUpdated 6 mo ago
    Marketing & SEOAuto-check passed
  • SEO Audit

    shadcn-labs/agentcn

    How to present the deterministic AI-SEO audit returned by auditpage.

    490 GitHub stars~598 tokensUpdated 2 days ago
    Marketing & SEOAuto-check passed
  • Global SEO Growth

    minhnv0807/ai-business-skills

    Covers six SEO layers for a website: crawl and index audit, local SEO, search-intent content, AI search visibility, schema markup and backlink or directory distribution.

    610 GitHub stars~5k tokensUpdated 27 days ago
    Marketing & SEOAuto-check passed
  • SEO

    Nexus-JPF/note-companion

    Use and read this skill immediately if the user request is in any way related to SEO or a site's organic search or AI search presence.

    870 GitHub stars~2.2k tokensUpdated 2 days ago
    Marketing & SEOAuto-check passed

Works with

Categories

Questions about Unfairgaps

What does Unfairgaps do?

Find documented UNFAIRGAPS - systemic regulatory holes where a product can plug the leak - using court filings, regulatory fines, and enforcement data. Unfairgaps is an agent skill from AyanbekDos/unfairgaps-os. Find documented UNFAIRGAPS - systemic regulatory holes where a product can plug the leak - using court filings, regulatory fines, and enforcement data.

When should I use Unfairgaps?

Unfairgaps fits situations like: tasks that involve SEO audit.

How do I install Unfairgaps in Claude Code?

Run `npx skills add AyanbekDos/unfairgaps-os --skill unfairgaps -a claude-code`. Or copy the skill folder (skills/unfairgaps in AyanbekDos/unfairgaps-os) into .claude/skills/unfairgaps in your project. Claude Code loads it when a task matches its description.

How do I install Unfairgaps in Codex?

Run `npx skills add AyanbekDos/unfairgaps-os --skill unfairgaps -a codex`. Or copy the skill folder (skills/unfairgaps in AyanbekDos/unfairgaps-os) into .agents/skills/unfairgaps in your project. Codex loads it when a task matches its description.

Can I use Unfairgaps in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add AyanbekDos/unfairgaps-os --skill unfairgaps -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/unfairgaps, .gemini/skills/unfairgaps, .github/skills/unfairgaps and .opencode/skills/unfairgaps in your project.

What does Unfairgaps need to run?

Going by SKILL.md and its folder, Unfairgaps needs the command-line tools its instructions call (python) and credentials named PERPLEXITY_API_KEY. Our summary lists: Python 3; A credential in PERPLEXITY_API_KEY.

Does Unfairgaps access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Unfairgaps safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Unfairgaps use?

Unfairgaps is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Unfairgaps use?

About 3.4k tokens (SKILL.md is roughly 14k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 6.7k tokens, read only when the agent opens those files.

What are the alternatives to Unfairgaps?

Skills that share tags, products or a category with Unfairgaps: GEO-First SEO Audit Tool (zubair-trabzada/geo-seo-claude, 11k stars), GEO Platform Optimizer (zubair-trabzada/geo-seo-claude, 11k stars), AI Discoverability Audit (BrianRWagner/ai-marketing-claude-code-skills, 440 stars) and SEO Audit (shadcn-labs/agentcn, 490 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Unfairgaps?

AyanbekDos (a GitHub user) maintains it in AyanbekDos/unfairgaps-os, which has 112 GitHub stars. The repository was last updated on May 20, 2026.

Source: AyanbekDos/unfairgaps-os on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.