agentleFS
Wolfe-JamWolfe-Jam/faf-cli/skills/faf-expert/SKILL.md

faf-expert

Skill44 starsChanged 10 months agoMITView on GitHub

Expert in the .faf format (Persistent Project Context for AI) and the faf-cli toolkit. Use when working with .faf files, scoring AI-readiness, syncing project context to CLAUDE.md, or discussing the Foundational Context Layer (FCL) doctrine. IANA-registered (application/vnd.faf+yaml). Anthropic-listed as "Persistent Project Context Server" (PR #2759, merged Oct 17 2025). Current CLI: v6.6.0 — The Trophy Edition.

  • Installs packages

2 other projects use a version of this.

Adopted by

Most recently taken up by

  • Other versions2 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 2

    1. Wolfe-Jam/grok-faf-mcp★ 19same name
    2. Wolfe-Jam/faf-skills★ 4same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository3 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Run faf --help for the full 26-command set.

    line 55
  2. Distinctive:

    Read the rationale; refute by inspection.

    line 100

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

FAF Expert — Persistent Project Context Specialist

What is .faf?

The .faf file is Persistent Project Context for AI — a single source of truth that survives across sessions, tools, and AI assistants.

  • IANA-registered media type: application/vnd.faf+yaml (registered Oct 30, 2025)
  • Anthropic-listed: modelcontextprotocol/servers PR #2759 — claude-faf-mcp shipped as "Persistent Project Context Server" (merged Oct 17, 2025)
  • Git-native: project.faf versions with your code; every clone gets full AI context
  • The CLI behind the FCL — the Foundational Context Layer for AI

The credo: FAF defines. AGENTS.md instructs. AI codes.

When to activate this skill

  • Creating, editing, or scoring .faf files
  • Syncing .faf → CLAUDE.md, or exporting it to AGENTS.md, .cursorrules, GEMINI.md
  • Diagnosing sub-Trophy scores and reaching 🏆 100%
  • Explaining the FCL, tier system, or app-type ladder
  • Connecting .faf work to the broader receipts: IANA, Anthropic PR #2759, MCP Registry

Install the CLI

bunx faf                       # Bun — zero install, fastest
npx faf                        # npm — works everywhere
npm install -g faf-cli         # global install
brew install faf-cli           # Homebrew

faf is the verb across every surface: bunx faf, npx faf, /faf (Claude Code plugin), faf (global). Bare faf shows your project's score; faf auto detects and fills.

The workflow

faf init → faf auto → faf go → 🏆 Trophy 100%
CommandWhat it does
faf initCreate a project.faf scaffold for your project
faf autoAuto-detect stack, fill what's detectable, score
faf goGuided interview to fill the remaining slots → Trophy
faf scoreCheck current AI-readiness (0–100%)
faf syncWrite CLAUDE.md from .faf (one way)
faf compile.faf → .fafb binary (sealed, portable, deterministic)
faf checkValidate .faf structure
faf infoVersion + system info

Run faf --help for the full 26-command set.

Scoring — Trophy 100% all-or-nothing

From v6.6.0 onward, faf-cli recommends only 🏆 Trophy.

TierScoreStatus
🏆 Trophy100%AI never has to guess
★ Gold99%+1 slot from Trophy
◆ Silver95%+Close — keep going
◇ Bronze85%+Interim — keep going
● Green70%+Interim — keep going
● Yellow55%+AI flipping coins
○ Red<55%AI working blind
♡ White0%No context at all

Why all-or-nothing? Architectural, not aspirational:

Layer 4   AI tooling          ← AI optimised by complete FCL
Layer 3   Agents              ← can act because FCL is complete
Layer 2   MD instructions     ← can be re-authored correctly
Layer 1   .faf (FCL)          ← 🏆 Trophy = complete = foundation

100% on Layer 1 makes Layers 2–4 work. Sub-100% degrades every layer above — instructions miss context, agents guess, AI optimisation can't happen.

🏆 is the only emoji. Sub-Trophy tiers use geometric Unicode (★ ◆ ◇ ● ○ ♡). The retired medal ladder (🥇🥈🥉🟢🟡🔴🤍) is history.

The app-types

The app-type answers one question: what does this repo ship? It sets which of the 33 slots count; the rest are slotignored. App-types are types of projects, not types of file (a CLAUDE.md or a SKILL.md sits inside a project of some type).

The full table, with each type's slots, is in docs/SCORING.md. Write the type's own name (cli, not cli-tool); a name faf doesn't know is treated as library.

About (not an app_type): declare about.represents: owner/repo. Inherits about.source_score. Do not set app_type: about.

The CLI auto-detects via # found: rationale next to type::

project:
  type: cli  # found: package.json bin

Read the rationale; refute by inspection. Glass Hood doctrine — the CLI shows its work.

.faf file structure (current schema)

faf_version: 3.0
app_type: cli

project:
  name: my-project
  goal: One-line elevator pitch
  main_language: TypeScript

stack:
  framework: React
  backend: Node.js
  db: PostgreSQL
  api: REST
  css: Tailwind
  state: Zustand
  pkg_manager: bun
  hosting: Vercel
  build: vite
  cicd: GitHub Actions
  runtime: Node 20+
  connection: prisma

human_context:
  who: target users
  what: one-line description
  why: the problem this solves
  where: where it ships
  when: production since YYYY-MM
  how: how it works — the mechanism, and the choice that shapes the code

v6.6.0 uses Mk4 canonical slot names in user-facing docs: db (was database), framework (was frontend), css (was css_framework), state (was state_management), api (was api_type), pkg_manager (was package_manager). 36k+ existing .faf files continue scoring correctly via read-time aliasing.

The sync flow — one way

.faf is the canonical Foundational Context Layer (FCL). CLAUDE.md / AGENTS.md / .cursorrules / GEMINI.md are downstream prose renders that READ .faf to save AI time. They never write back automatically.

.faf  ──── 8ms ───→  CLAUDE.md     (faf sync)
                     AGENTS.md     (faf export)
                     .cursorrules
                     GEMINI.md

faf sync --direction pull (CLAUDE.md → .faf backfill of name, goal and language) is Trophy-gated — blocked below 100% to prevent overwriting canonical slots with prose drift.

Receipts ladder

  • IANA-registered: application/vnd.faf+yaml at iana.org/assignments/media-types/application/vnd.faf+yaml — registered 2025-10-30
  • Anthropic-listed: PR #2759 merged Oct 17, 2025 — claude-faf-mcp added as "Persistent Project Context Server"
  • MCP Registry: FAF Ecosystem #2759 (Five Fingers: claude / faf / grok / gemini / WJTTC)
  • One dev, <12 months — IANA-registered, Anthropic-listed, xAI ZEPH commission, 100+ FAF-disciplined repos, the format used to build itself

Where to go next

You want to...Go here
Install + start using the CLIgithub.com/Wolfe-Jam/faf-cli
Read the v6.6 releaseCHANGELOG — The Trophy Edition
Understand the FCL / Trophy doctrinedocs/SCORING.md
Set up syncdocs/SYNC.md
Visit the format homefaf.one
Pin context to AI toolsRun faf export — authors AGENTS.md, .cursorrules, GEMINI.md from your .faf

FAF defines. AGENTS.md instructs. AI codes. v6.6.0 — The Trophy Edition. How no-score became a score.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.