This is the public, open-source repository that ships to all customers and the community.
NotFair is a host-agnostic plugin providing SEO, Google Ads, and Meta Ads skills for AI coding agents. It is distributed via the nowork-studio Claude Code marketplace and via direct agent install on Codex and Hermes. Every change here is user-facing.
Surgical, verified, minimum-change engineering. Make the smallest scoped change that solves the real problem, verify it, and do not disturb anything else.
- Understand before changing. Inspect the relevant code, current state, and failure mode before editing.
- State material assumptions. If ambiguity changes the implementation, risk, or user-visible behavior, clarify before acting.
- Prefer the smallest correct change. No speculative features, premature abstractions, or unrelated "while I'm here" refactors.
- Scope cleanup tightly. Match existing style. Clean up only mess introduced by the change. Mention unrelated issues; do not silently fix them.
- Make success verifiable. For bugs, reproduce when practical. For features, define expected behavior. Run the narrowest meaningful validation, then broader checks if risk warrants.
- Protect high-risk boundaries. Before destructive, public, production, billing, credential, or communication side effects: verify actor, target, scope, approval, blast radius, and resulting state.
- Leave the system easier to operate. If the workflow recurs or the bug pattern is reusable, encode it as a test, guardrail, skill, or automation.
AGENTS.md— the universal skill resolver. Every host reads this to route user intents to the right skill. Update it whenever a skill is added, removed, or its purpose changes.INSTALL_FOR_AGENTS.md— the single paste-URL target that walks an AI agent through host detection and install.skills/— Codex's portable wrapper index into the canonicalWORKFLOW.mdfiles in category directories. Each wrapper preserves the canonical frontmatter and forwards to the full workflow; keep both in parity with.claude-plugin/plugin.json.install/README.md— convention for adding per-host install adapters (Codex, Hermes, etc.) without duplicating skills.
This code ships to real users. Sycophancy and rubber-stamping cost us credibility every time a bad skill lands in someone's Claude. Hold the line:
- Be brutally honest. If a request is a bad idea, say so with reasoning — don't soften it, don't bury it in caveats, don't implement it anyway because the user asked. "This won't work because X" is more useful than a polite attempt that fails in production.
- Critically think about every request. Before implementing, challenge the premise: Is this the right problem to solve? Does it match an existing skill? Will it make the plugin better for users, or just bigger? Push back when the answer is no.
- Relentless about quality. High quality, reliable, and maintainable — non-negotiable. No half-finished skills, no untested prompts, no "we'll fix it later." If it's not ready to land in a customer's environment, it's not ready to commit.
- Surface tradeoffs explicitly. When a request has hidden costs (complexity, maintenance burden, user confusion, prompt fragility), name them before writing code. Let the user make the call with full information.
- Disagree when warranted. Agreement is not the goal; the best outcome for users is. If the user is wrong, say so — with evidence.
- Home of the
notfairplugin — the public artifact customers install. - Contains host-agnostic skills under
paid-ads/,google-ads/,meta-ads/,analytics/,wordpress/,gohighlevel/,seo/. - Registered via
.claude-plugin/plugin.json+.claude-plugin/marketplace.json(Claude Code),.codex-plugin/plugin.json(Codex), andAGENTS.md(every host's resolver). - Paired with one universal NotFair MCP server for Google, Meta, X, LinkedIn, Reddit, and TikTok Ads plus Google Search Console, Google Analytics, WordPress, and GoHighLevel (OAuth at notfair.co).
- Treat every commit as a release candidate. Broken skills, bad prompts, or missing files become customer bug reports.
- Never add internal-only notes, secrets, credentials, dev scratch files, or references to private infra. This repo is public.
- Test skills end-to-end before shipping —
SKILL.mdfrontmatter (nameanddescription) is how Claude decides to invoke them; typos or stale descriptions break discovery.
The product is NotFair. All user-facing text, documentation, skill descriptions, and config namespaces use NotFair / notfair.co / .notfair/. The prior brand has been fully removed from this repo — do not reintroduce any of its strings (names, config paths, MCP prefixes, URI schemes, or domains) in new code, new docs, or rewrites of existing files. The installed plugin uses one compact NotFair server at https://notfair.co/api/mcp/notfair. Follow docs/mcp-connection.md for connection guidance. Keep skills focused on the user's objective and domain knowledge; use the live server's instructions and schemas for tool selection rather than maintaining tool catalogs or forced call sequences.
- Create/edit the skill directory under the appropriate category (
google-ads/,seo/, etc.) with aWORKFLOW.mdcontaining the complete workflow and valid frontmatter. - Register it in
AGENTS.mdunder the matching intent table. A skill that isn't inAGENTS.mdis invisible to Codex, Hermes, and any non-Claude host. - Register it in
.claude-plugin/plugin.jsonunder theskillsarray, pointing at./skills/<name>. A skill that exists on disk but isn't registered will NOT appear in the installed Claude Code plugin — this has already bitten us once withads-landing. - Create its entry under
skills/using the workflow's frontmatter name. Copy only the frontmatter, then link to the fullWORKFLOW.md; every host uses this same entry. Do not create symlinks. - Bump the version in all manifests so upgrades propagate:
.claude-plugin/plugin.json→version.codex-plugin/plugin.json→version.claude-plugin/marketplace.json→ bothmetadata.versionandplugins[0].version.cursor-plugin/plugin.json, rootplugin.json, andgemini-extension.json
- Update
CHANGELOG.mdwith a user-facing note. - Verify the committed package, merge the reviewed pull request, then update the existing Directory submission from
main. Users update through their host's plugin controls.
Semantic-ish: bump patch for skill additions / fixes, minor for new categories or meaningful capability jumps, major for breaking skill API changes. Keep host plugin manifests and the marketplace manifest in lockstep — drift causes upgrade detection bugs.
- NotFair MCP server — private, powers the Google Ads tool calls the skills depend on.
The repository root is the installed plugin and the Directory submission path.
Keep it free of local programs, shebang files, package-manager configuration,
unsupported binary files, credential-file readers, automatic hooks, and helper
installers. Test/build programs are subject to the same package rule as runtime
programs; do not ship them or rename them to allowed extensions. Use Markdown
instructions, JSON reference/eval data, YAML host metadata, and the PNG icon.
Skill and workflow frontmatter contains only name and description.
Read the version from the plugin manifest. The extensionless source version marker has been retired. The remote MCP registry entry is independently versioned. The release checklist covers package verification.