Faf expert

Skill Wolfe-Jam/faf-skills/skills/faf-expert

Master the IANA-registered .faf format (application/vnd.faf+yaml) — the typed, portable context that makes any AI understand your project. Covers scoring internals, MCP server config, bi-directional sync, and the full 21-slot model. The mechanic's manual for expert-level control. New to FAF? Start with faf-context to hit 100%, then come here to go deep. See also faf-wizard for the done-for-you path.From its SKILL.md

Install

npx -y skills add Wolfe-Jam/faf-skills --skill faf-expert

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

4 stars4 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its file declares

Copied from the file, not written here

The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

9.9 KB, as published. Nobody here has run it

FAF Expert — Master the Format

.faf is an IANA-registered context format (application/vnd.faf+yaml) — a typed, portable file you own, readable by any AI, with no bespoke manifest and no vendor lock-in. This is the mechanic's manual: scoring internals, MCP configuration, bi-directional sync, and the full slot model.

The FAF skill family — where this fits

Skill	What it's for
faf-wizard	Done-for-you — one-click `.faf` for any project	DFY
faf-context	The builder's quickstart — hand the AI what it needs to hit 100% ✪, fast	← start here if you're new
faf-expert (you are here)	Master the format — scoring internals, MCP config, bi-sync, the full slot model	Deep

New to FAF? Start with faf-context to reach 100%. Come here to go deep.

When to use this skill

Configuring .faf files and the MCP server beyond the basics
Understanding the scoring engine and how to drive a project to high tiers
Multi-AI workflows — one context across Claude, Cursor, Gemini, Codex, Windsurf
Reviving a legacy codebase into AI-readable project DNA
Standardizing context format across a team

The format

project/
├── package.json     ← dependencies (npm reads this)
├── project.faf      ← AI context (any AI reads this)
├── CLAUDE.md        ← human docs (synced from .faf)
└── src/             ← code (guided by the context)

README.md is prose for humans · CLAUDE.md is prose for Claude · project.faf is structure for ANY AI (IANA application/vnd.faf+yaml). One source of truth; everything else is emitted from it.

Universal compatibility — one `.faf`, every tool

AI platform	Emitted file	Command
Claude (Desktop / Code)	`CLAUDE.md`	`faf sync`
OpenAI Codex / agents	`AGENTS.md`	`faf sync`
Cursor	`.cursorrules`	`faf export --cursor`
Google Gemini	`GEMINI.md`	`faf export --gemini`
GitHub Copilot	`.github/copilot-instructions.md`	`faf export --copilot`

Quick start

1. Install the CLI

npm install -g faf-cli        # or: brew install wolfe-jam/faf/faf-cli
faf --version

2. Configure the MCP server — add to Claude Desktop's claude_desktop_config.json, then restart Claude:

{
  "mcpServers": {
    "faf": {
      "command": "npx",
      "args": ["-y", "claude-faf-mcp@latest"]
    }
  }
}

3. The loop to 100% ✪

faf auto     # 1. detect stack + language, seed context from your README
faf score    # 2. the % + exactly which slots are still empty
faf go       # 3. guided fill — answer only the gaps the AI can't source
faf score    # 4. 100% ✪
faf sync     # 5. push context → CLAUDE.md / AGENTS.md

CLI commands

# The path to Trophy
faf auto                # detect + seed (fills what it can)
faf score               # AI-readiness % + the empty slots
faf go                  # guided fill — close the gaps
faf sync                # emit CLAUDE.md / AGENTS.md from the .faf

# Anytime
faf init                # create a fresh project.faf
faf check               # validate structure (IANA-clean)
faf git <url>           # score any GitHub repo → .faf, no clone
faf formats             # browse the supported stacks
faf migrate             # upgrade an older .faf
faf export --copilot    # emit .github/copilot-instructions.md
faf taf setup           # wire up TAF test receipts (CI)

MCP server tools

claude-faf-mcp brings the format into the tool surface. The live tool set (verified against the running server):

# The path to 100% ✪
faf_auto     → scan manifests (package.json, Cargo.toml, pyproject.toml…) + fill the .faf
faf_score    → 0–100% AI-readiness + tier + per-slot breakdown
faf_go       → the friendly front door — asks the 6 Ws
faf_sync     → sync .faf → CLAUDE.md (+ optionally AGENTS.md)

# Anytime
faf_init     → create a new project.faf (name, goal, language) + starting score
faf_context  → set / show the active project path faf_ calls resolve against
faf_doctor   → diagnose: empty / weak slots + how to fix each
faf_enhance  → refine the .faf with an AI model (claude / gemini / grok, optional consensus)
faf_trust    → attest integrity: validity, score + a deterministic parity hash anyone can verify
faf_bench    → prove the .faf earns its place — the context's worth on THIS repo, falsifiably
faf_about    → explain the FAF format — project DNA for AI (IANA-registered)

# Project soul (.fafm) — memory across sessions
faf_etch     → remember a decision / gotcha / win to the .fafm
faf_recall   → recall memories from the .fafm, ranked by priority + recency

(The exact set evolves release to release — verify against your installed version with the MCP client's tool list.)

Scoring

Tiers

Score	Tier	Symbol	Status
100%	Trophy	✪	Perfect — Gold Code
99%	Gold	★	Exceptional
95%	Silver	◆	Top tier
85%	Bronze	◇	Production ready
70%	Green	●	Solid foundation
55%	Yellow	●	Needs improvement
1%	Red	○	Major work needed
0%	White	♡	Empty

The score is deterministic — a WASM-compiled engine, mechanical and falsifiable. Same input → same score, every time. FAF doesn't lie.

The 21-slot model

faf-cli scores on 21 slots. Your app_type selects which are active — a CLI ignores frontend slots (slotignored, never counted against you). Detection fills the stack + language; you supply only the underivable bits — project.name/goal + the 6 Ws (a sharp goal seeds several). 100% = every active slot filled (not all 21). (Teams / Enterprise tiers add more slots — separate from faf-cli's 21.)

# project.faf — IANA application/vnd.faf+yaml
faf_version: "3.0"

project:                          # required
  name: modern-web-app
  goal: Real-time collaboration platform for distributed teams
  main_language: typescript

human_context:                    # the 6 Ws — the underivable half
  who: distributed product teams
  what: real-time collaboration tool
  why: remove the latency tax of async handoffs
  where: AWS (ECS)
  when: production, since 2026
  how: TypeScript · React · Node · PostgreSQL

stack:                            # auto-detected
  frontend: react
  backend: express
  database: postgresql
  runtime: node
  deployment: aws-ecs
  build: vite
  testing: vitest
  cicd: github-actions

Validation rules: must have faf_version, project.name, project.goal · valid YAML · no secrets/credentials · works across all AI platforms.

The honesty rule

The engine only scores what's truthfully there — detection fills the stack, you fill the underivable Ws, and what nobody can source stays honestly empty. Empty beats wrong. That's why the resulting context is trustworthy.

Best practices — drive to Trophy

faf auto                    # 1. baseline: detect + seed
faf score                   # 2. see the empty slots
faf go                      # 3. close the gaps (guided)
faf check                   # 4. IANA compliance
faf sync                    # 5. emit CLAUDE.md / AGENTS.md
git add project.faf CLAUDE.md AGENTS.md && git commit -m "Add AI context (.faf)"

The .faf is the standard — commit it, and everyone's AI shares one context. Common boosters: add the human_context block, specify deployment, document the testing strategy.

Ecosystem

Package	Registry	Purpose
`faf-cli` (`faf`)	npm	the CLI
`claude-faf-mcp`	npm	Claude Desktop / Code MCP server
`faf-mcp`	npm	universal MCP server
`gemini-faf-mcp`	PyPI	Google Gemini integration
`grok-faf-mcp`	npm	xAI Grok integration
`faf-scoring-kernel`	npm	the WASM scoring engine

100k+ downloads across npm + PyPI + crates.io. claude-faf-mcp, faf-mcp, and gemini-faf-mcp hold AAA on Glama (earned, not conferred).

Standing

IANA-registered media type: application/vnd.faf+yaml
In the original Anthropic MCP ecosystem (PR #2759, merged Oct 2025)
Maintainer of the .faf format specification

Troubleshooting

MCP server not responding

faf check                                   # is the .faf well-formed?
# re-check claude_desktop_config.json (see Quick start), then restart Claude
tail -f ~/Library/Logs/Claude/mcp-server-claude-faf-mcp.log

Low AI-readiness score

faf score          # shows the empty slots holding you back
faf go             # guided fill — close them to 100%

Tools not showing — restart Claude after editing the config, and confirm the server started (see the MCP log above).

Get this skill

Plugin marketplace (recommended): /plugin marketplace add Wolfe-Jam/faf-skills → /plugin install faf@faf-skills
Manual: git clone https://github.com/Wolfe-Jam/faf-skills.git && cp -r faf-skills/skills/* ~/.claude/skills/
Browse the family: https://skills.faf.one

Resources

Website: https://faf.one · Skills Site: https://skills.faf.one
faf-cli: https://github.com/Wolfe-Jam/faf-cli · npm: https://npmjs.com/package/faf-cli
claude-faf-mcp: https://npmjs.com/package/claude-faf-mcp

MIT · part of the FAF skill family (faf-context · faf-wizard · faf-expert). The format is the foundation — without .faf, there is no portable context.