faf-cli — 持久化项目上下文工具（FAF 格式专家）
用一份 IANA 注册的 .faf 文件为 AI 编码助手提供真实、可版本化的项目上下文，自动生成 AGENTS.md、CLAUDE.md、GEMINI.md 和 .cursorrules，告别重复解释项目。
该技能本身为纯文档（SKILL.md），不执行代码、不请求权限；仓库 SECURITY.md 声明本地优先、默认只读、写操作需显式命令、除 opt-in 的 bench --submit 外无网络行为，CI 含 npm audit 与 trufflehog 秘密扫描。扣分项：这些安全声明是仓库层面的自述，静态审查无法验证；技能大量自证性宣传（IANA、Anthropic PR #2759、'One dev'等）无法在文件内核实，发布者身份未经验证。
文档内部一致，命令表清晰，仓库含真实 CI（多平台测试、打包安装冒烟测试、版本一致性断言）和针对性测试文件（如 ai-slop-guard），符合静态上限。扣分项：技能文档钉在 v6.6.0，而 package. 为 7.12.0，命令集与行为可能已漂移；静态审查无法执行关键路径，异常输入的失败反馈质量只能部分从测试推断。
触发场景明确（创建/编辑/评分 .faf、同步 CLAUDE.md 等），用途清晰。扣分项：能力边界与非适用范围未明确声明；技能版本信息严重过时（v6.6.0 vs 实际 7.12.0），可能造成误触发期望；中文支持未提及；核心依赖 npm/Homebrew 分发在大陆网络可达性存疑。
结构清晰、分层合理（install、命令表、schema、链接），MIT 许可明确，有 CHANGELOG 和版本化。扣分项：SKILL.md 的版本号（v6.6.0）与仓库实际版本（7.12.0）不一致，属于维护/更新路径缺陷；大量营销化、教条化语言（'Trophy doctrine'、'receipts'）混入技术文档；单一维护者，长期维护责任不明确。
技能声称帮助生成/维护项目上下文文件，命令流程（init→auto→go→sync）描述完整，仓库自举（dogfooding）提供一定佐证。扣分项：静态审查无法验证输出可直接使用；宣称的收益（'AI never has to guess'、100% 必要性）主要是教条式论断而非对比证据；与手动撰写 AGENTS.md 相比的边际价值缺乏独立评估。
仓库含真实 CI 工作流与已提交测试套件，覆盖部分关键路径（CLI 冒烟、打包安装、 slop-guard 验证器），达到静态上限。扣分项：外部凭证（IANA 注册、Anthropic PR #2759、下载量、Zenodo 论文）未在文件内可独立核实；技能自身主张与测试覆盖之间的对应关系仅部分可追溯。
- 技能文档钉在 v6.6.0，但仓库实际版本为 7.12.0：命令行为、默认值可能已变化，使用前请核对 faf --help 与 CHANGELOG。
- IANA 注册、Anthropic PR #2759、下载量等'凭证'为外部主张，本审查未独立核实。
- 仓库声明本地优先且默认只读，但这属于自述；依赖 faf-scoring-kernel 等第三方包的安全性未经独立审计。
- 安装依赖 npm/Homebrew，中国大陆网络可达性未经验证，可能需要镜像。
- 大量教条式/营销化语言（Trophy、receipts）混入文档，评估实际功能时请以命令与测试为准。
- 本评审为纯静态源码审查，未执行任何命令，置信度为低。
这个 Skill 能做什么，适合哪些场景？
faf-cli 是一个 TypeScript CLI 工具，从你的真实技术栈中检测并生成 .faf 项目上下文文件。.faf 是 IANA 注册的格式（application/vnd.faf+yaml，2025年10月30日），随代码一起进行 Git 版本管理，克隆即得完整 AI 上下文。该技能（faf-expert）指导创建、评分和同步 .faf 文件，目标是 100% Trophy 完整度。作者还维护了配套的 MCP 服务器（Anthropic 官方仓库 PR #2759）。适合希望多个 AI 工具共享同一份事实上下文的开发者。
运行 faf init/auto/go 创建并填充 project.faf，自动检测框架、数据库、包管理器等技术栈；用 faf score 按 0–100% 评分，仅推荐 Trophy（100%）；用 faf export/sync 将 .faf 单向渲染为 CLAUDE.md、AGENTS.md、GEMINI.md、.cursorrules；支持 faf compile 将 .faf 编译为 .fafb 二进制；7.2.0 起通过 IANA 注册的 .fafm 格式提供 faf memory 记忆管理；26 个子命令覆盖 diff、hooks、show 等。
- 团队开发者：项目同时使用 Claude Code、Cursor 和 Gemini，希望所有工具读到同一份不漂移的上下文
- 新项目启动者：在几分钟内从 package. 检测出技术栈并生成 AI 可读的项目说明
- 接手旧仓库的工程师：用 faf git <url> 无需克隆即可为任意 GitHub 仓库生成 .faf
- 关注 AI 就绪度的维护者：用评分体系确保上下文完整，避免 AI 猜测
- 需要持久化 Agent 记忆的用户：用 .fafm 格式迁移 Claude Code 记忆并做确定性召回
这个 Skill 有哪些优点和局限？
- IANA 注册格式（.faf/.fafm/.fafa），有正式标准和格式论文支撑
- Git 原生：上下文随代码版本化，克隆即得
- 工具链完善：bunx/npx/Homebrew 安装，26 个子命令，含编译二进制与 pre-commit hooks
- 被 Anthropic MCP 服务器目录收录（PR #2759），并列入 Awesome Claude Code
- 作者自举使用，仓库自带 score=100 的 project.faf
- 文档声称 v6.6.0 为当前版本，README 却显示 7.12.0，版本信息在 SKILL.md 与 README 之间存在不一致
- 下载量、'one dev <12 months' 等宣传性指标来自项目自身，未独立验证
- 反向同步（MD → .faf）在低于 100% 时被锁定，对只想轻量使用的用户较严格
- 深度依赖 YAML 生态与自身评分体系，已有自定义 CLAUDE.md 工作流的团队需评估迁移成本
如何安装这个 Skill？
无需单独安装即可试用：bunx faf 或 npx faf。全局安装：npm install -g faf-cli 或 brew install wolfe-jam/faf/faf-cli。技能文件位于仓库的 skills/faf-expert/SKILL.md，按 Agent Skills 标准放入你的技能目录即可。
如何使用这个 Skill？
安装后在项目根目录依次运行：faf init 创建 project.faf → faf auto 自动检测并评分 → faf go 引导式访谈补齐人工填写槽位直至 100% → faf export 生成 AGENTS.md/CLAUDE.md 等。也可直接对 AI 助手说：'帮我为这个项目创建并评分一个 .faf 文件，然后同步到 CLAUDE.md'。完整命令集用 faf --help 查看。
这个 Skill 与同类方案有什么区别？
与手写 CLAUDE.md/AGENTS.md 相比，faf-cli 从真实技术栈生成而非人工维护，可减少漂移；README 自述其 dogfooding 模式中 AGENTS.md 为手工维护的'更优简报'，说明两者可并存。