Archify 的 Cursor 原生 Skill 接入实录安装、发现、端到端验证与可复现验收指南【免费下载链接】archifyAgent skill for beautiful, verifiable architecture, workflow, sequence,>项目地址: https://gitcode.com/GitHub_Trending/arch/archify本篇技术指南以 Archify 仓库内一份带日期的兼容性验收记录docs/cursor-acceptance-2026-07.md为主线完整还原 Archify 这一开源的 Agent Skill 如何通过官方skillsCLI 安装到 Cursor、被 Cursor Agent 原生发现并执行最终产出通过 9/9 校验的自包含 HTML 架构图的全过程。读完本文你将掌握一条可复现的 Cursor 项目级安装命令、doctor / validate / deliver / check / visual-check的完整验收链路以及哪些关于 Cursor 兼容性的表述可以写进文档、哪些必须谨慎回避。这是一份什么样的验收记录cursor-acceptance-2026-07.md是一份日期受限的兼容性记录dated compatibility record而非对任意 Cursor 版本或任意模型的普遍承诺。记录开篇即明确三件事验证时间2026-07-23验证范围项目级project-localCursor Agent Skill 发现 一次已检查的 Architecture 交付结论边界不声称每个 Cursor 版本或模型都会产生相同输出。这种只对记录环境负责的措辞方式对应着仓库中另一份研究报告 docs/research-cursor-onboarding-2026-07.md 里Defensible claims vs claims to avoid的原则——可以确认的写实未做基准测试的绝不虚构。验收记录本身就是该研究提出的Real Cursor discovery and invocation人工发布闸门通过后的实证存档。环境快照被验证的边界验收发生在特定的软件组合下任何复现都必须先对照此表组件版本 / 取值Cursor Agent CLI2026.07.20-8cc9c0b模型选择autoCursor CLI 默认操作系统macOS 26.5.225F84Skills CLIskills1.5.20Archify 源码codex/cursor-onboarding分支基于e7e22a1注意最后一行的措辞验收使用的 Archify 源码来自codex/cursor-onboarding分支。这暗示验收前仓库刚完成 Cursor 的一等公民first-class接入改造且该改造不新增 Cursor 专属的SKILL.md分支——记录第 30 行明确写出会话中不存在任何 Cursor 专属的SKILL.md、渲染器、schema 或提示词分叉。从源码看Archify 的 Skill 包本体位于仓库 archify/ 目录其 package.json 声明engines: { node: 18 }且 CLI 二进制入口为./bin/archify.mjs。运行时只需 Node.js 18不需要npm install——这是后续安装即用验收的前提也是 docs/research-cursor-onboarding-2026-07.md 中Installed runtime contract验收闸门的核心。安装与发现一条可复现的 Cursor 安装命令项目级安装命令验收工作区是一个全新的临时目录使用固定版本 显式参数的可复现命令完成安装npx -y skills1.5.20 add /path/to/archify \ --skill archify --agent cursor --copy --yes参数含义如下参数作用npx -y skills1.5.20通过 npx 直接运行官方 Skills CLI-y自动确认下载固定版本保证行为可复现add /path/to/archify指定本地 Archify 仓库路径作为 Skill 来源--skill archify显式指定要安装的 Skill 名称Archify 包内可能有多个 Skill--agent cursor指定安装目标 Agent 为 Cursor--copy以复制模式写入独立 Skill 树而非默认的符号链接模式--yes跳过交互式确认安装后skills list --agent cursor --json报告存在一个**项目作用域project-scoped**的Cursor安装位于.agents/skills/archify。随后新开的 Cursor Agent 会话独立报告发现.agents/skills/archify/SKILL.md这验证了 Cursor 的原生 Skill 目录契约Cursor 会自动扫描.agents/skills/目录以及~/.agents/skills/等用户级目录一个包含SKILL.md的文件夹就是一个可发现的 Skill。验收记录特意强调安装器使用的是.agents/skills而非~/.cursor/skills因为 docs/research-cursor-onboarding-2026-07.md 已核实skills1.5.20的安装器把 Cursor 当作通用 Agent全局安装会解析到~/.agents/skills/archify而不是 README 中写的~/.cursor/skills/archify。编写前健康检查doctor会话在开始编写前先运行了archify doctor成功退出。doctor是 Archify CLI 的自检命令从 archify/bin/archify.mjs 的commandDoctor实现看它逐项检查Node.js 版本要求 ≥ 18核心模板assets/template.html示例渲染器、live preview 运行时、visual-check 运行时、输出路径安全运行时场景指南recipes/scenarios.mjs、渐进式编写参考文档Architecture compare 运行时与证明夹具五个类型的 renderer schema example 完整性architecture / workflow / sequence / dataflow / lifecycle。doctor全部通过会输出Archify is ready.否则会列出缺失项并以非零码退出。这也是 SKILL.md 中Setup and fallback一节推荐的验证方式node bin/archify.mjs doctor node bin/archify.mjs demo output-directory端到端任务六组件事件处理架构图任务定义Cursor 被要求用 Archify 绘制一张六组件本地事件处理架构图组件包括Webhook ClientAPI GatewayEvent RouterWorkerPostgreSQLDead Letter Queue作者定义的主路径为Webhook Client → API Gateway → Event Router → Worker → PostgreSQL显式失败路径为Worker → Dead Letter Queue关系标签为on failure。这是一个典型的一条主路径 一条带语义标签的失败支路架构场景与 archify/SKILL.md 中One obvious main path; side branches leave the nearest main-path node的编写不变量完全一致。产物与工作区纪律Cursor 只在工作区根目录写入了类型化 JSON 源码 已检查的 HTML此外只有安装器所属的文件。这对应 SKILL.md 的Artifact first原则候选 JSON 先落盘再校验、再交付交付成功后候选即被冻结不再修改。Archify 的编写主路径可概括为从需求中判定图类型architecture/workflow/sequence/dataflow/lifecycle读取对应 schema 与示例 JSON 作为字段形状参考设置meta.quality_profile为showcase除非用户明确要求密集的standard图每次编辑候选后立即校验交付前再校验一次校验通过后用deliver做最终验收。9/9 校验从哪里来验收回执中的checksPassed: 9/9并非虚构数字而是有确定性的实现依据。Archify 的最终产物检查器位于 archify/scripts/check-render-output.mjs它先做四类工件级artifact检查single_svg产物中恰好只有一个svg根finite_svgSVG 中不出现NaN、undefined、Infinity、-Infinityorthogonal_arrows所有关系线均正交无对角线段legend_clearance关系线不侵入图例区域。再叠加展示级showcase才强制开启的组合质量检查COMPOSITION_CHECKSlabel_route_clearance关系标签与路由之间保持清晰间隙relationship_crossings无关关系不发生交叉relationship_corridors无关关系不共用歧义走廊container_border_runs关系线不沿容器边界贴行route_rhythm路由的弯折与拉伸在建议预算内。在 archify/bin/archify.mjs 的commandDeliver中delivery回执的validation.checksPassed就是result.checks.filter(c c.ok).lengthcheckCount为result.checks.length——这就是 9/9 的出处。注意 SKILL.md 的提醒A receipt with only 4 artifact checks is basic validation, never showcase acceptance只有 9 项全过、0 组合错误、0 警告才是 showcase 验收通过。交付回执确定性证据与独立复验Cursor 会话的交付回执delivery receipt原文如下validation: passed visual_review: skipped (image reader unavailable in Cursor session) correction_rounds: 0 quality: showcase compositionStatus: pass checksPassed: 9/9 errors: 0 warnings: 0 artifact.sha256: d4d443f160fafd7615234987a5572d7169916719b9a97b9231e9f48434c79e4a artifact.bytes: 582743这份回执的字段与 archify/references/delivery-contract.md 定义的交付契约一一对应字段含义validation: passed9 项 artifact 检查全部通过quality: showcase使用 showcase 质量档位对应--quality showcase等价于环境变量ARCHIFY_QUALITY_PROFILEshowcasecompositionStatus: pass组合质量检查交叉、走廊、边界贴行、标签间隙、路由节奏通过correction_rounds: 0首次交付即通过无需聚焦修正轮契约上限为 2 轮visual_review: skippedCursor 会话中无图像读取能力感知级视觉审阅被如实标记为跳过而非谎报通过artifact.sha256/artifact.bytes产物字节级身份供独立复验比对回执的诚实性要点在于visual_review: skipped (image reader unavailable)。交付契约明确区分三条独立声明deliver证明确定性 artifact 检查与字节身份SHA-256 字节数visual-check从精确产物收集自动化浏览器证据evidenceKind: automated-browser且永远报告visualReview: pending感知级视觉审阅必须由真实人类或具备图像能力的审阅者完成。验收记录随后做了独立复验用 Archify 的validate --json和check --json重新运行九个通过项、零组合发现、字节数以及 SHA-256 回执全部一致。这印证了deliver的确定性交付会将规格的精确字节冻结到同目录私有快照、渲染该快照、跑完整 artifact 检查器、全部通过后才原子替换目标文件因此同一输入必然得到同一产物字节。复验时使用的命令形如node bin/archify.mjs validate type candidate.json --quality showcase --json node bin/archify.mjs check output.htmlcheck子命令在 archify/bin/archify.mjs 中直接调用scripts/check-render-output.mjs并透传其退出码validate则走渲染器的诊断边界installRendererDiagnosticBoundary任何失败都以结构化诊断code / severity / subject / evidence / supportedFixes而非裸堆栈输出保证机器可读回执的稳定。浏览器审阅Presentation Stage、章节聚焦与 Start 页生成的 HTML 在内置浏览器中以1280×720 桌面视口打开验收覆盖三个界面维度Presentation Stage六节点主路径完整可读Worker → Dead Letter Queue 失败关系视觉上保持可区分章节聚焦选中作者定义的Failure to DLQchapter 后视图精确框定 Worker 与 Dead Letter Queue 两个节点其余部分降为上下文。同时Start 页被完整演练Cursor 选择器、中英文切换、agent URL 状态、精确的全局/项目安装命令展示。最后落地页landingLive Proof 的仅脚本沙箱script-only sandbox通过了其初始 Signal Flow 章节检查与一次刻意的 Blueprint 切换。三个界面的最终干净会话中浏览器控制台零警告、零错误。需要说明的是章节chapter聚焦能力来自 Archify 可选的meta.views至多 5 个策划章节属于 Viewer Runtime 的读者能力而仅脚本沙箱意味着 Live Proof 在无网络、纯脚本环境下工作不依赖外部资源。这两个机制从 archify/references/viewer-runtime.md 与 archify/SKILL.md 的 Optional viewer capabilities 一节可以交叉印证。边界与断言哪些话可以讲哪些必须谨慎验收记录的 Boundaries retained 一节是全文最值得参考的方法论它划定了与 Cursor 兼容性相关的可说/不可说边界skills use ... --agent cursor不被支持skills1.5.20的交互式启动器只注册了claude-code和codex会拒绝 Cursor 启动因此文档不得推荐该用法研究报告中有明确验证。不承诺物理路径~/.cursor/skillsCursor 官方同时扫描.agents/skills而验证过的安装器实际使用的正是该目录文档承诺Cursor 官方扫描的目录这一事实而不承诺具体物理路径。全局/项目安装表述全局安装表述为用户级user-wide项目安装表述为仓库局部repository-local两者都使用显式--copy复制模式。不做全面基准声明这份记录不基准测试其他 Cursor 模型、不声称自动更新、也不替代 Archify 的确定性与感知级交付闸门。研究报告 docs/research-cursor-onboarding-2026-07.md 对此有更系统的归纳值得直接引用的现在可辩护结论包括Cursor 在 Editor 与 CLI 中支持 Agent Skills用--agent cursor安装 Archify项目作用域使用.agents/skills/archify在 Node.js 18 可用、无需npm install的前提下安装后的 Archify 包通过doctor、校验与已检查的 HTML 交付Archify 在 Cursor、Claude、Codex、opencode 之间复用同一份可移植SKILL.md与渲染器契约。需要继续回避的表述则包括已全面测试各 Cursor 模型、CLI 全局安装到~/.cursor/skills/archify、Skill 会自动更新等。这正是验收记录 not a claim that every Cursor version or model produces identical output 这句话的完整落点。如何在自己的环境中复现这次验收若你想在本地复现这次 Cursor 验收可按以下步骤执行准备环境Node.js ≥ 18本机安装 Cursor 且具备 Cursor Agent CLI对照上述版本快照版本差异可能导致行为不同。安装进入一个全新临时目录执行项目级安装命令npx -y skills1.5.20 add /path/to/archify \ --skill archify --agent cursor --copy --yes确认发现运行skills list --agent cursor --json确认.agents/skills/archify存在新开 Cursor Agent 会话确认其报告发现.agents/skills/archify/SKILL.md。健康检查运行node .agents/skills/archify/bin/archify.mjs doctor观察Archify is ready.。端到端任务让 Cursor 编写六组件 Architecture JSON或你自己的场景主路径加一条带标签的失败支路交付回执应报告quality: showcase、checksPassed: 9/9、errors: 0、warnings: 0。独立复验对同一 JSON 分别运行validate --json与check --json比对九个通过项与回执中的 SHA-256 / 字节数。浏览器审阅在桌面视口打开交付的 HTML检查 Presentation Stage、章节聚焦与主题切换记录控制台是否零警告零错误。如实记录边界无论结果如何按验收记录的格式记录 Cursor 版本、模型、OS 与作用域不要外推结论。复现过程中可参考仓库内的支撑材料archify/SKILL.md编写与验收主路径、archify/bin/archify.mjs全部 CLI 子命令与回执生成、archify/references/delivery-contract.md交付、视觉检查与交接回执契约、archify/scripts/check-render-output.mjs9 项 artifact 检查与组合质量检查、archify/package.jsonNode 版本与 bin 入口、archify/test/cli.test.mjs已安装副本场景下的五模式交付测试以及 docs/research-cursor-onboarding-2026-07.md本次验收背后的完整调研、可辩护声明清单与五个验收闸门定义。总结这份 Cursor 验收记录的价值不仅在于Archify 能在 Cursor 里跑通更在于它示范了如何把一次 Agent 兼容性验证做成可复现、可独立复验、边界清晰的工程实践——安装命令固定版本与参数、回执携带字节级身份、独立命令复验、浏览器与感知级审阅分层记录、最终只对记录环境负责。对任何希望让自己的 Skill 进入 Cursor 生态的开发者这都是一个可以直接照抄的验收模板。【免费下载链接】archifyAgent skill for beautiful, verifiable architecture, workflow, sequence,>项目地址: https://gitcode.com/GitHub_Trending/arch/archify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考