faf-cli — Persistent Project Context (FAF Expert Skill)
Give AI coding agents real, versioned project context via one IANA-registered .faf file, auto-generating AGENTS.md, CLAUDE.md, GEMINI.md and .cursorrules so you never re-explain your repo.
The skill itself is pure documentation (SKILL.md): it executes no code and requests no permissions. SECURITY.md declares local-first, read-only-by-default, explicit-command writes, and no network except opt-in bench --submit; CI runs npm audit and trufflehog secret scanning. Deductions: these security claims are repo-level self-statements unverifiable statically; the skill is heavy on self-attesting receipts (IANA, Anthropic PR #2759, 'One dev') not verifiable from the files; publisher identity unverified.
Documentation is internally consistent with a clear command table; the repo has real CI (multi-platform tests, packed-tarball install smoke test with version assertion) and targeted tests (ai-slop-guard), meeting the static ceiling. Deductions: the skill pins v6.6.0 while package. is 7.12.0, so commands/behavior may have drifted; static review cannot execute key paths and failure-feedback quality on abnormal input is only partly inferable from tests.
Trigger scenarios are clear (create/edit/score .faf, sync to CLAUDE.md, etc.). Deductions: capability boundaries and non-fit ranges are not declared; the skill's version info is badly stale (v6.6.0 vs actual 7.12.0), risking mismatched invocation expectations; Chinese-language support unmentioned; npm/Homebrew distribution reachability from mainland China is uncertain.
Well-structured, layered docs (install, command table, schema, links), clear MIT license, CHANGELOG and versioning exist. Deductions: SKILL.md version (v6.6.0) contradicts the actual repo version (7.12.0) — a maintenance/update-path defect; marketing/doctrinal language ('Trophy doctrine', 'receipts') is mixed into technical documentation; single maintainer with unclear long-term maintenance responsibility.
The skill's claimed workflow (init→auto→go→sync) is complete and the repo dogfoods itself, offering some corroboration. Deductions: static review cannot verify outputs are directly usable; benefit claims ('AI never has to guess', the necessity of 100%) are doctrinal assertions rather than comparative evidence; marginal value over hand-writing AGENTS.md lacks independent evaluation.
The repo contains genuine CI workflows and committed test suites covering part of the key paths (CLI smoke, packed-tarball, slop-guard validator), meeting the static ceiling. Deductions: external receipts (IANA registration, Anthropic PR #2759, download counts, Zenodo papers) are not independently verifiable from the files; the mapping between the skill's claims and test coverage is only partially traceable.
- The skill pins v6.6.0 while the repo is at 7.12.0: command behavior and defaults may have changed; verify with faf --help and the CHANGELOG before use.
- External 'receipts' (IANA registration, Anthropic PR #2759, download counts) are unverified claims in this review.
- The repo declares local-first and read-only-by-default, but this is self-statement; third-party dependencies such as faf-scoring-kernel have not been independently audited.
- Installation relies on npm/Homebrew; reachability from mainland-China networks is unverified and may require mirrors.
- Heavy doctrinal/marketing language (Trophy, receipts) permeates the docs; judge actual functionality by commands and tests.
- This is a purely static source review; no commands were executed and confidence is low.
What does this skill do, and when should you use it?
faf-cli is a TypeScript CLI that detects your real stack and authors a .faf project-context file — an IANA-registered format (application/vnd.faf+yaml, Oct 30, 2025) that versions with your code in Git, so every clone ships full AI context. The faf-expert skill covers creating, editing, and scoring .faf files against a 100%-Trophy target, plus syncing them into downstream markdown briefs. The author also maintains a companion MCP server listed in Anthropic's official servers repo (PR #2759). It suits developers who want multiple AI tools to share one canonical, drift-free context source.
Runs faf init/auto/go to create and populate project.faf with auto-detected stack facts (framework, database, package manager, CI/CD); scores AI-readiness 0–100% with faf score, recommending only Trophy (100%); renders .faf one-way into CLAUDE.md, AGENTS.md, GEMINI.md and .cursorrules via faf export/sync; compiles .faf into a sealed .fafb binary with faf compile; manages portable agent memory in the IANA-registered .fafm format via faf memory (v7.2.0+); and ships 26 subcommands including diff, hooks, and show.
- Team developer: project uses Claude Code, Cursor and Gemini simultaneously and all tools should read one canonical, non-drifting context
- New project starter: detect the stack from package. and produce AI-readable project docs in minutes
- Engineer onboarding onto a legacy repo: generate a .faf for any GitHub repo without cloning via faf git <url>
- Maintainer tracking AI-readiness: use the scoring ladder to guarantee context completeness so agents never guess
- User needing persistent agent memory: migrate Claude Code memory into .fafm and do deterministic recall
What are this skill's strengths and limitations?
- IANA-registered formats (.faf/.fafm/.fafa) with formal standard and published format papers
- Git-native: context versions with code; clones carry full context
- Complete tooling: bunx/npx/Homebrew install, 26 subcommands, compiled binaries, pre-commit hooks
- Listed in Anthropic's MCP servers directory (PR #2759) and Awesome Claude Code
- Self-hosted dogfooding — the repo ships its own score=100 project.faf
- Version inconsistency: SKILL.md cites v6.6.0 as current while README documents up to v7.12.0
- Marketing metrics (133k+ downloads, 'one dev <12 months') are self-reported and independently unverified
- Reverse sync (MD → .faf) is locked below 100%, which is strict for casual users
- Deeply tied to its own YAML schema and scoring doctrine; teams with established CLAUDE.md workflows should weigh migration cost
How do you install this skill?
Try it with no install: bunx faf or npx faf. Install globally: npm install -g faf-cli or brew install wolfe-jam/faf/faf-cli. The skill file lives at skills/faf-expert/SKILL.md in the repo; place it in your skills directory per the Agent Skills standard.
How do you use this skill?
In your project root: faf init to create project.faf → faf auto to detect and score → faf go for the guided interview to reach 100% → faf export to author AGENTS.md/CLAUDE.md. Or prompt an assistant: 'Create and score a .faf file for this project, then sync it to CLAUDE.md.' Run faf --help for the full command set.
How does this skill compare with similar options?
Compared with hand-written CLAUDE.md/AGENTS.md, faf-cli generates context from the real stack rather than manual upkeep, reducing drift; its own dogfooding notes keep a hand-maintained AGENTS.md as the 'BETTER ops briefing', so the two can coexist.