FAi Brilliance

A skills-based standardization layer for FieldAssist delivery outputs.

Every output, unmistakably FieldAssist.

FAi Brilliance is an internal library of Skills — reusable SKILL.md instruction files that make every FieldAssist output (Excel, PPT, Doc, Consultative analysis) come out consistent, on-brand, and world-class by default. Browse them on the web, or — shadcn-style — install any skill straight into Claude Code, Codex, Cursor, or your terminal.

It's the 4th i: Information → Insight → Impact → Impression.

Install from anywhere

Every skill is served at a stable, CORS-enabled URL, so you never have to visit the site to use one. Three ways (see the in-app /docs page for the full guide):

# 1. Any AI agent (Claude Code / Codex / Cursor) — paste one line:
Fetch https://fai-brilliance.netlify.app/r/mbr-deck-standard.md and apply it to my deck.

# 2. Any terminal:
curl -o SKILL.md https://fai-brilliance.netlify.app/r/mbr-deck-standard.md

# 3. The CLI — installs it as a native Claude Code skill (.claude/skills/):
npx fai-brilliance add mbr-deck-standard --claude

The registry: /registry.json (index), /r/<id>.md (raw skills with Claude-skill frontmatter), /llms.txt (agent index). All generated at build time from src/data/skills.js by scripts/build-registry.mjs.

The site

A multi-page product site (Gumroad-style):

• Landing (/) — hero, the "install anywhere" pitch, featured skills, how it works.
• Library (/skills) — searchable, filterable, paginated grid; the Master Skill pinned; "🔥 Top in category" badges; contribute your own Community skill (persists in localStorage).
• Product page (/skill/:id) — full SKILL.md, an install panel (copy-able commands per tool + Download .md + Install/Use counter), an example-output gallery, sources, and related skills.
• Docs (/docs) — every way to use a skill from an agent or terminal, plus the CLI reference.
• Two tiers — Certified official standards, and Community open contributions.

CLI

Zero-dependency (Node 18+), runnable with no install:

npx fai-brilliance install --claude          # the WHOLE library → .claude/skills/
npx fai-brilliance install --dept Marketing  # just one team's skills
npx fai-brilliance list                       # browse the registry
npx fai-brilliance search excel               # find skills
npx fai-brilliance add mbr-deck-standard --claude   # one specific skill

Flags: --claude (native Claude Code skills), --all (with add), --dept <name>, --category <name>, --dir <path>, --registry <url> (or FAI_BRILLIANCE_REGISTRY). Published on npm as fai-brilliance — new versions ship automatically via the publish workflow (see Auto-update pipeline).

Offline by default — zero hosting cost. The CLI reads skills bundled inside the package (cli/data/skills.json, regenerated from src/data/skills.js on every build), so list / search / add make no network calls and never touch the website's host. Pass --registry <url> only when you want the freshest copy fetched live from the deployed site.

Auto-update pipeline (moderated)

Contributions are moderated — nothing goes live automatically (these skills become instructions people feed to AI agents, so unmoderated auto-publish would be unsafe). The flow:

Someone contributes on the site
  → lands in your review queue (Netlify Forms — free, no extra account)
  → you approve it into src/data/skills.js and push
     → GitHub Action auto-republishes the npm package (fresh CLI bundle)
     → Netlify auto-redeploys the site + registry

• Collection: the contribute form posts to a Netlify Form named skill-contribution (hidden detection form in index.html). Submissions appear under Netlify → Forms; turn on email notifications there to get pinged.
• Republish: .github/workflows/publish.yml runs when src/data/skills.js changes on main (or via Run workflow), regenerates the CLI bundle, bumps the patch version, and publishes to npm.

One-time setup to arm the auto-publish (trusted publishing — no tokens, no secrets, no 2FA changes):

1. Go to https://www.npmjs.com/package/fai-brilliance → Settings tab.
2. Find Trusted Publisher → choose GitHub Actions and enter:
   • Organization or user: tanayvasishtha
   • Repository: FAI-Brilliance
   • Workflow filename: publish.yml
   • Environment: (leave blank)
3. Save. Then GitHub → Actions → Publish CLI to npm → Run workflow to publish the current library; after that it runs itself on every skills change.

Netlify Forms needs no setup beyond a deploy — the hidden form is detected automatically.

Example outputs

Show what each skill produces: drop files into examples/<skill-id>/ and they appear in that skill's product-page gallery. See examples/README.md.

Brand

Aligned to the 2026 FieldAssist Brand & Identity Guidelines:

• Logo — the real FieldAssist wordmark (white on dark, colour on light) and the blue→pink mark as the favicon, in public/ (fa-logo-white.png, fa-logo-color.png, fa-mark.png, favicon.png). Raw source assets live in brand/ (git-ignored — they're 100+ MB originals; only the optimized web versions are committed).
• Colours — FA Blue #2B68CE, Vibrant Pink #FF7AAC, Deep Navy #112A52, Action Blue #1A6EFF (interactive), off-white #F7F7F7, plus Soft Yellow / Peach tints. The signature blue→pink gradient is reserved for the mark, emphasis, the accent strip, and icons.
• Type — Poppins (display/UI) + Open Sans (body), via @fontsource.
• The full brand standard is encoded in the Master Skill (src/data/skills.js).

Tech

• React + Vite + Tailwind CSS, react-router-dom for routing, react-markdown for SKILL.md rendering.
• Ships static, built to scale. No backend required today — seed data lives in src/data/skills.js; user-added skills and download counts persist in localStorage. But the whole app reads through a swappable data adapter, so a real API can be dropped in later with zero UI changes (see Scaling & backend-readiness below).

Scaling & backend-readiness

The app never talks to localStorage or a server directly — it depends only on a small SkillsRepository interface (src/lib/repository/):

list(query) · get(id) · getMaster() · catalog() · myDrafts() · create(skill) · topCommunityByCategory()

• localRepository — the default: bundled seed + localStorage, all async.
• httpRepository — real fetch implementation against a REST API. Ready to use.
• createRepository() picks one based on the VITE_API_BASE_URL env var.

To move to a shared backend: stand up a service implementing the endpoints listed in .env.example, set VITE_API_BASE_URL, and rebuild. No component changes.

Other things that make it scale to a large library:

• URL-driven state — search, filters, sort, and the open skill/contribute modal all live in the URL, so every view is deep-linkable and shareable (/skill/:id, /?cat=Excel&tier=Community).
• Pagination — the grid loads a page at a time ("Load more"), mapping 1:1 to an API's page/pageSize, so hundreds of skills never mount at once.
• Code-splitting — the heavy product page (react-markdown) and the contribute form are lazy-loaded, keeping the initial bundle small.
• Debounced search — avoids a query per keystroke once the repository is remote.
• Pure query logic (src/lib/repository/query.js) — filter/sort/paginate with the same semantics the server can reimplement.

Run locally

npm install
npm run dev       # http://localhost:5173

Build

npm run build     # outputs static site to dist/
npm run preview   # serve the production build locally

Deploy to Netlify

Option A — Drag & drop (fastest)

1. npm install && npm run build
2. Go to https://app.netlify.com/drop and drag the dist/ folder in.

Option B — Git + auto-deploy

1. Push this repo to GitHub.
2. Netlify → Add new site → Import from Git → pick the repo.
3. Build command npm run build · Publish directory dist · Deploy.

Option C — Netlify CLI

npm install -g netlify-cli
netlify deploy --build --prod

netlify.toml already sets the build command, publish directory, CORS headers for the registry, and the SPA redirect (/* → /index.html 200).

Name the site fai-brilliance (Netlify → Site settings → Change site name) so the CLI's default registry URL (https://fai-brilliance.netlify.app) resolves. On a different domain, the in-app commands still work (they use the current origin) — only the CLI's default needs --registry <url> / FAI_BRILLIANCE_REGISTRY. The build regenerates the registry every time, so /registry.json and /r/*.md always match src/data/skills.js.

Project structure

scripts/build-registry.mjs  # generates registry.json, /r/*.md, llms.txt, examples manifest
cli/index.mjs               # zero-dep CLI (npx github:… list / search / add)
examples/<skill-id>/        # example output files → product-page galleries
src/
  components/          # SiteNav, SiteFooter, Layout, CodeBlock, Hero, MasterCard,
                      #   Filters, SkillCard, HowItWorks, Badges, Modal, ModalFallback,
                      #   ContributeModal
  pages/
    LandingPage.jsx       # / — hero, install-anywhere pitch, featured, how it works
    LibraryPage.jsx       # /skills — filters (URL-synced), grid, pagination, contribute
    ProductPage.jsx       # /skill/:id — content + install panel + gallery + sources (lazy)
    DocsPage.jsx          # /docs — use skills from agents/terminal + CLI reference
  routes/ContributeRoute.jsx  # /skills/contribute (lazy modal)
  data/skills.js          # all seed skills in ONE editable file (source of the registry)
  lib/
    storage.js            # low-level localStorage read/write
    useDebounce.js        # debounced value hook
    useSkillLibrary.js    # paginated, async grid data hook
    repository/           # the data-adapter layer
      types.js            #   SkillsRepository + query/page contracts (JSDoc)
      query.js            #   pure filter / sort / paginate / top-in-category
      localRepository.js  #   localStorage + seed implementation (default)
      httpRepository.js   #   REST API implementation (backend swap-in)
      index.js            #   createRepository() factory (env-driven)
  App.jsx                 # route map (Layout + pages)
  main.jsx                # BrowserRouter + mount

Editing the library

Add or edit seed skills in src/data/skills.js — the single source for both the site and the registry. Each skill's content is a full SKILL.md (headings, lists, tables all render); optional sources: [{label, url}] shows on the product page. The registry regenerates on every npm run dev / npm run build.