name	faf-expert
description	Expert in .faf (Foundational AI-context Format) files for persistent project context. Use when working with .faf files, project DNA, CLAUDE.md bi-sync, faf-cli commands, MCP server configuration, or AI-readiness scoring (0-100%). Updated for v2.8.0 Tool Visibility System.

FAF Expert - Project DNA Specialist

What is .faf?

.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

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 v2.8.0+)

v2.8.0 introduces Tool Visibility System:

21 Core Tools (default) - Essential workflow
51 Total Tools (opt-in) - All features

Configuration:

{
  "mcpServers": {
    "faf": {
      "command": "npx",
      "args": ["-y", "claude-faf-mcp@2.8.0"],
      "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

Start with faf auto - Let it detect your stack
Review and refine - Auto-detection is 85% accurate, tweak as needed
Run faf score - Target 85%+ for championship context
Use faf bi-sync - Keep .faf and CLAUDE.md in sync
Update regularly - As project evolves, update context
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:

Environment variable (FAF_MCP_SHOW_ADVANCED)
Config file (~/.fafrc)
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 - November 2025)

13,000+ total downloads (CLI + MCP combined)
6,700+ MCP downloads (weekly: 800+)
6,500+ CLI downloads
79 tests passing (57 MCP + 22 visibility)
153+ formats validated (TURBO-CAT engine)
<10ms tool filtering (5x better than 50ms target)
Zero regressions in v2.8.0 release
WJTTC Gold Certified - F1-inspired testing standards
Anthropic-approved MCP server (Official steward)

Version History

v3.2.7 - faf-cli latest
v3.3.7 - claude-faf-mcp latest (TYPE_DEFINITIONS parity)
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

Copy this SKILL.md file
Create directory: ~/.claude/skills/faf-expert/
Save as: ~/.claude/skills/faf-expert/SKILL.md
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 v2.8.0 🏎️✨ IANA-Registered Format: application/vnd.faf+yaml (Oct 31, 2025)

Install Skill

SKILL.md