faf-expert
Skill4 starsChanged 4 days agoMITView on GitHub
The reference for the IANA-registered .faf format (application/vnd.faf+yaml): the 33 slots every .faf is scored on, scoring, MCP setup, `faf sync` to CLAUDE.md, `faf export` to AGENTS.md and other files, and project memory (.fafm) for the BEST rung. Use for questions about how FAF works: "how is my score calculated?", "what does slotignored mean?", "set up the FAF MCP server", "how does faf sync work with CLAUDE.md?". New to FAF? Start with faf-context.
- Installs packages
2 other projects use a version of this.
Adopted by
Most recently taken up by
- Wolfe-Jam/faf-clitheir own version, first seen Jan 26, 2026
- Wolfe-Jam/grok-faf-mcptheir own version, first seen Jan 26, 2026
Other versions2 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 2
- Wolfe-Jam/faf-cli★ 44same name
- Wolfe-Jam/grok-faf-mcp★ 19same 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 repository7 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- faf-contextSkill
- faf-goSkill
- faf-wizardSkill
- repo-maintainerSkill
- wjttc-builderSkill
- wjttc-testerSkill
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
- Distinctive: line 27
If the project has a project.faf, read it first: most questions are about that file.
- Very specific: line 199
Validation rules: must have faf_version, project.name, project.goal · valid YAML · no secrets/credentials · works across all AI platforms.
≈ “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.
Files
<!-- faf:start -->v: 1
needs: []
reads: ["the project's project.faf, when the question is about it"]
writes: []
network: []
publishes: false
done_when: "the question is answered, with the command, slot or file it concerns"
project: project.faf<!-- faf:end -->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.
Steps
- If the project has a project.faf, read it first: most questions are about that file.
- Find the answer in the sections below (the format, the CLI, the MCP tools, scoring).
- Answer with the exact command, slot or file, and say which section it came from.
The FAF skill family — where this fits
| Skill | What it's for | |
| faf-wizard | A .faf for any project: repo facts filled in, the goal and six W's suggested for you to confirm | Generate |
| 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, 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
.faffiles 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 export --agents |
| 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 --version2. Add the MCP server. In Claude Code:
claude mcp add faf -- npx -y claude-faf-mcp@7.0.1Or in Claude Desktop, add this to claude_desktop_config.json and restart Claude:
{
"mcpServers": {
"faf": {
"command": "npx",
"args": ["-y", "claude-faf-mcp@7.0.1"]
}
}
}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: faf export --agents)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 from the .faf
faf export --agents # emit 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 (shallow-clones to a temp dir)
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 core tools in claude-faf-mcp v7:
# 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_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 | ✪ | AI is optimized to 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 always-33 slot model
Every .faf is scored against the same 33 slots. faf-cli fills the 21 base slots and marks the 12 enterprise slots slotignored unless your app type uses them; slotignored slots never count against you. 100% ✪ = every active slot filled. 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).
# 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
hosting: aws-ecs
build: vite
testing: vitest # informational — not one of the 33 scored slots
cicd: github-actionsValidation 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
faf export --agents # and 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 Code / Desktop MCP server |
faf-mcp | npm | MCP server for Cursor, VS Code and other MCP IDEs |
gemini-faf-mcp | PyPI | Google Gemini integration |
grok-faf-mcp | npm | Grok integration |
faf-scoring-kernel | npm | the WASM scoring engine |
150k+ downloads across npm + PyPI + crates.io. claude-faf-mcp, faf-mcp, and gemini-faf-mcp hold AAA on Glama (claude-faf-mcp · faf-mcp · gemini-faf-mcp).
Standing
- IANA-registered media type:
application/vnd.faf+yaml - Listed in modelcontextprotocol/servers (PR #2759, merged 2025-10-17)
- Maintainer of the
.fafformat 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.logLow 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.
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
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.

