faf-expert
Skill19 starsChanged 10 months agoMITView on GitHub
Expert in .faf (Foundational AI-context Format) files for persistent project context. Use when working with .faf files, project DNA, syncing project.faf into CLAUDE.md, faf-cli commands, MCP server configuration, or AI-readiness scoring (0-100%). Updated for v2.8.0 Tool Visibility System.
- Installs packages
2 other projects use a version of this.
Adopted by
Most recently taken up by
- Wolfe-Jam/faf-skillstheir own version, first seen Nov 13, 2026
- Wolfe-Jam/faf-clitheir 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/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.
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
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
- Very specific: line 134
Use
faf sync: - Write CLAUDE.md from .faf after each change - Distinctive: line 233
NO BS ZONE: - Only real stats, verified claims
- Distinctive: line 273
All tests reported and documented
≈ “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 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
.faffiles - Working with
CLAUDE.mdfiles - Running
fafCLI commands (init, auto, score, formats, 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 contextCLAUDE.md- Markdown format, human-readable project guide- Sync -
faf syncwrites CLAUDE.md from.faf(one way;.fafis the source) 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 sync # Write CLAUDE.md from .faf (one way)
faf status # Check project AI-readiness
faf validate # Validate .faf structure
faf doctor # Diagnose and fix issues
faf migrate # Migrate to latest formatMCP 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 - Sync:
faf_sync(old namefaf_bi_syncstill works),faf_update,faf_migrate - AI:
faf_chat - 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: 87Best 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 sync- Write CLAUDE.md from .faf after each change - 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-clifaf-cli (Homebrew)
brew install faf-cliclaude-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 commandsquality- Scoring and validationintelligence- Format/stack detectionsync- Context synchronizationai- AI enhancement featureshelp- Documentationtrust- Trust validationfile- File operationsutility- 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)
- 11,000+ total downloads (CLI + MCP combined)
- 5,000+ MCP downloads (weekly: 800+)
- 6,000+ 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.1.1 - faf-cli latest
- v2.8.0 - MCP Tool Visibility System (CURRENT)
- v2.7.3 - Previous MCP stable
- v1.2.0 - project.faf standard naming
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.jsTool Count Verification
# Should show 21 core tools (default)
# Or 51 tools (advanced mode)
# Check console output when MCP loadsCLI Not Found
# Install globally
npm install -g faf-cli
# Or via Homebrew
brew install faf-cli
# Verify installation
faf --versionAdvanced Usage
Custom Config File
Create ~/.fafrc:
{
"showAdvanced": true
}Or key=value format:
FAF_SHOW_ADVANCED=trueLocal 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.disabledTo re-enable:
# Rename back to enable
mv ~/.claude/skills/faf-expert.disabled ~/.claude/skills/faf-expertOr 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-expertOption 3: From FAF CLI (future)
# Planned feature
faf skill install faf-expertMade with 🧡 by wolfejam.dev Official Anthropic MCP Steward Championship Edition v2.8.0 🏎️✨ IANA-Registered Format: application/vnd.faf+yaml
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.

