faf-expert

FAF Expert - Project DNA Specialist

Become an expert. The mechanic's manual — install, configure, troubleshoot, score. See also: faf-wizard — the "done for you" pit crew that generates .faf files for any project.

What is .faf?

The package.json for Context.

project/
├── package.json     ← npm reads this
├── project.faf      ← AI reads this
├── README.md
└── src/

"package.json wasn't built for this, .faf was" — .faf Inventor

"package.json gives me a list of dependencies, .faf shows me how to use them" — Claude Code (Anthropic)

Once you get used to it, it's just another file helping you code.

---

.faf is the universal format for persistent AI project context - "Project DNA ✨ for ANY AI".

Core Concepts:

• Foundational AI-context Format - YAML-based project context file
• Persistent Context - Survives across sessions, tools, and AI assistants
• Universal - Works with Claude, ChatGPT, Gemini, Cursor, any AI
• Measurable - Championship scoring system (0-100% AI-readiness)
• Official Anthropic MCP Steward - PR #2759 MERGED
• Foundation Layer - CLAUDE.md syncs FROM .faf, preventing context drift

When to Use This Skill

Activate this skill when:

• Creating or updating .faf files
• Working with CLAUDE.md files
• Running faf CLI commands (init, auto, score, formats, bi-sync)
• Scoring project AI-readiness
• Setting up MCP server (claude-faf-mcp)
• Configuring tool visibility (v2.8.0+)
• Discussing project context or documentation

Key Files

• .faf - YAML format, machine-readable project context
• CLAUDE.md - Markdown format, human-readable project guide
• Bi-Sync - .faf ↔ CLAUDE.md kept in sync automatically
• project.faf - v1.2.0 standard naming

Common Commands

faf-cli Commands

faf init              # Create .faf from project
faf auto              # Auto-detect stack and create .faf
faf score             # Rate AI-readiness (0-100%)
faf formats           # List 153+ supported formats
faf bi-sync           # Sync .faf ↔ CLAUDE.md
faf status            # Check project AI-readiness
faf validate          # Validate .faf structure
faf doctor            # Diagnose and fix issues
faf migrate           # Migrate to latest format

MCP Tools (claude-faf-mcp v5.1.0)

33 tools available:

Configuration:

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

Core Tools (21):

• Essential Workflow: faf, faf_auto, faf_init, faf_innit, faf_status
• Quality: faf_score, faf_validate, faf_doctor, faf_audit
• Intelligence: faf_formats, faf_stacks, faf_skills, faf_install_skill
• Sync: faf_sync, faf_bi_sync, faf_update, faf_migrate
• AI: faf_chat, faf_enhance
• Help: faf_index, faf_faq, faf_about

Advanced Tools (30+): Set FAF_MCP_SHOW_ADVANCED: "true" to enable:

• Display variants: faf_display, faf_show, faf_check
• Trust system: faf_trust, faf_trust_confidence, faf_trust_garage
• File operations: faf_read, faf_write, faf_list, faf_exists, etc.
• DNA tracking: faf_dna, faf_log, faf_auth, faf_recover
• Utilities: faf_choose, faf_clear, faf_share, faf_credit

AI-Readiness Scoring

Championship Tiers:

• 🏆 95-100% - Championship (Gold)
• 🥇 85-94% - Podium (Silver)
• 🥈 70-84% - Points (Bronze)
• 🥉 55-69% - Midfield
• 🟢 40-54% - Backmarker
• 🟡 25-39% - Struggling
• 🔴 10-24% - Critical
• 🤍 0-9% - DNF (Did Not Finish)

Target: 85%+ for production projects

.faf File Structure

# Basic .faf structure
format: typescript-nextjs
language: typescript
framework: nextjs
version: "14.0.0"

structure:
  - src/
  - components/
  - pages/

dependencies:
  react: "^18.0.0"
  next: "^14.0.0"

testing: jest
deployment: vercel

# v1.2.0+ additions
project_name: "My Project"
ai_readiness_score: 87

Best Practices

1. Start with faf auto - Let it detect your stack
2. Review and refine - Auto-detection is 85% accurate, tweak as needed
3. Run faf score - Target 85%+ for championship context
4. Use faf bi-sync - Keep .faf and CLAUDE.md in sync
5. Update regularly - As project evolves, update context
6. Use core tools first - Advanced tools are opt-in for specific needs

The FAF Family

6 Championship Integrations:

• React (20M/week npm downloads) 🏆
• TypeScript (40M/week) 🏆
• Next.js (5M/week) 🏆
• Vite (9M/week) 🥇
• Svelte (400K/week) 🥇
• n8n (401K/week - TURBO only) 🥇

Installation

faf-cli (npm)

npm install -g faf-cli

faf-cli (Homebrew)

brew install faf-cli

claude-faf-mcp (MCP Server)

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

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

For advanced tools:

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

v2.8.0 Tool Visibility System

Problem Solved: Reduced cognitive load from 51 tools to 21 core tools.

How It Works:

• Default: Shows 21 essential tools
• Opt-in: Enable all 51 tools via environment variable
• Smart Filtering: Tools categorized by purpose
• Backward Compatible: Existing setups continue working

Categories:

• workflow - Essential commands
• quality - Scoring and validation
• intelligence - Format/stack detection
• sync - Context synchronization
• ai - AI enhancement features
• help - Documentation
• trust - Trust validation
• file - File operations
• utility - Misc tools

Configuration Priority:

1. Environment variable (FAF_MCP_SHOW_ADVANCED)
2. Config file (~/.fafrc)
3. Default (core only)

Philosophy

The Noodle Philosophy 🍜

• YAML noodles for AI (machine-readable)
• Converts to markdown/TXT for humans (human-readable)
• Interconnected context, not flat data

Format-First

• The format is the foundation
• Without .faf, there is no universal context
• Format-driven architecture

Official Stewardship

• Anthropic-approved MCP server (PR #2759 MERGED)
• Account Managers for all things .FAF in Anthropic ecosystem
• Governance responsibility for format specification

Brand Values

• NO BS ZONE - Only real stats, verified claims
• Championship Standards - <50ms performance, 1,000+ tests
• Free Forever - MIT license, open source
• Trust is Everything - Built on credibility
• Professional, Boring, Trusted - F1-grade engineering

Stats (Real, Verified - March 2026)

• 36,400+ total downloads across npm, PyPI, crates.io
• 94+ production releases across 16 packages, 3 registries
• 1,143 tests passing (faf-cli) + 351 tests (claude-faf-mcp)
• 153+ formats validated (TURBO-CAT engine)
• IETF Internet-Draft filed: draft-wolfe-faf-format
• Zenodo/CERN publication: #18251362
• WJTTC Gold Certified - F1-inspired testing standards
• Anthropic-approved MCP server (Official steward)

Version History

• v5.0.6 - faf-cli latest (1,143 tests, Bun-optimized)
• v5.1.0 - claude-faf-mcp latest (33 tools, 351 tests)
• v1.2.0 - faf-mcp universal

Resources

• Website: https://faf.one
• CLI npm: https://npmjs.com/package/faf-cli
• MCP npm: https://npmjs.com/package/claude-faf-mcp
• GitHub: https://github.com/Wolfe-Jam/faf-cli
• Homebrew: brew install faf-cli
• Chrome Extension: Chrome Web Store (Google approved)

Testing Standards

WJTTC (WolfeJam Technical & Testing Center)

• F1-Inspired testing methodology
• 3 Tiers: Brake Systems, Engine Systems, Aerodynamics
• Philosophy: "We break things so others never have to know they were broken"
• All tests reported and documented
• Gold certification for production releases

Troubleshooting

MCP Server Not Loading

# Check logs
tail -f ~/Library/Logs/Claude/mcp-server-claude-faf-mcp.log

# Verify config
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Test locally
node /path/to/claude-faf-mcp/dist/src/index.js

Tool Count Verification

# Should show 21 core tools (default)
# Or 51 tools (advanced mode)
# Check console output when MCP loads

CLI Not Found

# Install globally
npm install -g faf-cli

# Or via Homebrew
brew install faf-cli

# Verify installation
faf --version

Advanced Usage

Custom Config File

Create ~/.fafrc:

{
  "showAdvanced": true
}

Or key=value format:

FAF_SHOW_ADVANCED=true

Local Development

# Use local build
{
  "mcpServers": {
    "faf": {
      "command": "node",
      "args": ["/path/to/claude-faf-mcp/dist/src/index.js"],
      "env": {
        "FAF_MCP_SHOW_ADVANCED": "false"
      }
    }
  }
}

---

Skill Control

To disable this skill temporarily:

# Rename directory to disable
mv ~/.claude/skills/faf-expert ~/.claude/skills/faf-expert.disabled

To re-enable:

# Rename back to enable
mv ~/.claude/skills/faf-expert.disabled ~/.claude/skills/faf-expert

Or just delete the directory to remove completely.

---

How to Get This Skill

Option 1: Manual Installation

1. Copy this SKILL.md file
2. Create directory: ~/.claude/skills/faf-expert/
3. Save as: ~/.claude/skills/faf-expert/SKILL.md
4. Restart Claude Code

Option 2: Git Clone (if published)

# Coming soon - published skills repository
git clone [skills-repo] ~/.claude/skills/faf-expert

Option 3: From FAF CLI (future)

# Planned feature
faf skill install faf-expert

---

Made with 🧡 by wolfejam.dev Official Anthropic MCP Steward Championship Edition v5.1.0 🏎️✨ IANA-Registered Format: application/vnd.faf+yaml (Oct 30, 2025)