Show HN：Implement-spec——与运行框架无关的、从规格到已验证 PR 的 Agent Skill

面向 AI 编程 Agent 的严谨工程流程，被封装为可移植的 Agent Skills：将一份规格端到端实现为经过验证的 PR；以独立判断审查代码——无论是你自己的分支还是他人的 PR；像专业作者一样处理审查反馈；并让文档（面向 Agent 与面向人类）持续与其描述的代码保持一致。

• 与运行框架无关（Harness-agnostic）——采用标准 SKILL.md 目录。Claude Code、Codex、Cursor、Gemini CLI、GitHub Copilot 以及不断增加的客户端列表均可原生加载；在其他环境中（Windsurf、Goose，或使用终端的人类），只需一行指向技能文件的说明即可。
• 与代码库无关（Codebase-agnostic）——不对你的仓库、语言或工具链作任何假设。构建、测试和 lint 命令从仓库中发现或作为输入传入，绝不硬编码。
• 以研究为基础（Research-grounded）——持久化台账、全新上下文审查、证据优先报告：设计决策可追溯至 Agent 工程相关文献（设计依据）。

大多数 Agent 都能根据规格写出看似合理的代码。但它们难以稳定完成围绕代码的所有工作——在长周期内保持计划，测试自己写出的内容，发现实现悄然偏离规格之处，并证明结果而不是仅作断言。implement-spec 将这套纪律打包起来：向它交付一份适合 Agent 执行的规格，它会自主完成整个生命周期，仅在最后呈现结果。

spec ─▶ branch ─▶ plan + test matrix ─▶ implement (tests alongside) ─▶ two-pass self-review ─▶ gap analysis vs the spec ─▶ close gaps ─▶ live verification ─▶ PR + acceptance-criteria evidence report

• 证据优先于声明——“完成”意味着最终报告中的每项验收标准都对应一个可验证工件（测试、命令输出或实时检查），而不是模型声称它已完成。
• 可经受长周期运行——磁盘上的持久化运行台账使任务可在崩溃或上下文压缩后恢复。
• 与工作量相称的严谨性——台账、自审、差距分析、测试、实时验证等每个重型阶段都可单独选择退出，因此一行修复不必承担十个阶段的成本。

完整设计依据及每个阶段背后的研究文献见 skills/implement-spec/README.md。

另有七项技能与它配套——其中两项用于跨会话扩展构建，其余则用于审查、答复与文档维护：

当一份规格大到无法在一次专注运行中完成时，decompose-spec 和 orchestrate-build 会将其转变为一条可恢复的 PR 链——implement-spec 仍是逐任务执行的工作单元，在每个任务单中以全新上下文运行一次：

• decompose-spec 是规划者，也是整个构建质量的上限：它按精确目标切分规格——使用尽可能少的任务单，使每个任务单都能在一个全新上下文中以足够严谨度完成，且任何切分都不会割裂一项共享的隐含决策——随后在全新上下文中审查自己的拆分结果，并建立构建台账。两个边界条件（上限是上下文腐化，下限是决策碎片化）可追溯至其设计依据。
• orchestrate-build 是驱动器。其关键做法是：将排序编排做成确定性代码——一个可移植的循环（drive-build.sh，可发现 claude -p / goose run / codex exec / gemini -p）不持有任何状态，并将每个任务单分派至一个全新上下文——因此整个构建过程中没有任何上下文会持续累积，也不存在会逐渐腐化的长期 Agent 上下文。状态保存在台账中；人类可在任务单边界通过编辑台账来暂停并干预。如果运行框架能力较弱，它会降级为每任务单一个子 Agent，或使用手动创建的新会话；其设计依据解释了为何它仍保持与运行框架无关。

同桌的三个角色，共享同一套认识论——每一项标记都必须可证明，精确率胜过召回率（误报会让审查者失去他人的信任）：

• self-review 是 PR 前的作者角色：第 1 轮运行自动发现的构建、测试、lint（通过 verify.sh；当仓库未声明工具链时，它会推断工具链）以及二元检查清单；第 2 轮则在独立性规则下进行设计批评——运行框架支持子 Agent 时使用全新上下文，否则遵循从磁盘获取证据的纪律。它也是 implement-spec 的审查阶段。
• review-pr 是审查者角色：以 CI 和（可选的）本地验证为依据，随后分别针对正确性、设计、安全性和范围开展聚焦审查；发现的问题须依次通过可证明性 → 置信度 → 新颖性 → 实质性筛选，标记为 blocking/important/nit/question，数量受上限控制以避免告警疲劳，并以建议块形式发布。它提供信息，但批准权仍归人类。
• address-pr-comments 是作者的答复角色：每个未解决讨论串都必须得到修复、提交链接、有理有据的反驳、回答或范围明确的后续事项——绝不沉默，绝不奉承，也绝不在审查进行中强制推送（force-push）。

相同的收敛理念，面向两套消费者与质量标准不同的语料库——在 LLM 工作之前，每套都配有确定性的、可由 CI 门禁控制的漂移检测器：

• agent-docs 负责其他技能所依赖的、面向 Agent 的知识层（AGENTS.md 层级）。它有两种模式——bootstrap（侦察 → 挖掘易错点 → 生成）与 refresh（漂移分类 → 精准修复）——通过一个检测器自动选择；该检测器借助 git 历史，将失效引用归类为后来过期还是编写错误。它负责维护共享的文档编写指南。
• refresh-repo-docs 负责供人类阅读的内容：README、docs/、CHANGELOG、指南和示例。其检测器会标记失效引用，以及比其所引用代码更旧的文档；审计范围由证据确定（只审查被标记的文档，而不是“通读整个仓库”）；发现项被归类为过时（stale）/冗余（cruft）/缺口（gap）/模式漂移（mode-drift），并以 Diátaxis 作为逐文档质量视角；任何未经验证的声明都不会被写入。

作为 Claude Code 插件：

/plugin marketplace add SteveVitali/agent-skills /plugin install agent-skills@agent-skills

或者通过符号链接，适用于任何能在磁盘上发现技能的客户端（~/.claude/skills/、项目的 .agents/skills/ 等）：

git clone https://github.com/SteveVitali/agent-skills.git ~/agent-skills ln -s ~/agent-skills/skills/* ~/.claude/skills/

不原生支持技能的客户端（例如 Windsurf）：只需一行指向技能文件的工作流或规则——“读取并遵循 <path>/skills/implement-spec/SKILL.md”。

每项技能都在 SKILL.md frontmatter 中声明其输入；请以自然语言说明它们（“实现 docs/spec.md，跳过台账，基于 main 分支”）。系统要求：git、bash 3.2+ 和标准 Unix 工具；PR 相关技能（review-pr、address-pr-comments）还需要已认证的 GitHub CLI（gh）。

.claude-plugin/ # 插件与市场清单（Claude Code） skills// ├── SKILL.md # 入口文件（Agent Skills 格式：frontmatter + 步骤） ├── README.md # 设计依据（如有） ├── modes/ # 按需加载的模式专用步骤文件（如适用） ├── scripts/ # 辅助 shell 工具（兼容 bash 3.2+） └── checklists/ # 辅助检查清单 / 共享参考文档（如适用）

统一且可预测的入口文件名意味着：被指向 skills/ 的 Agent（或工具）知道每项技能从何处开始；技能目录中的其他一切内容都是从其 SKILL.md 引用的渐进式披露材料。

• 持久状态优先于上下文——任何必须在上下文压缩或崩溃后存续的内容都写入磁盘（运行台账、快照、报告），绝不只保留在上下文中。
• 外部验证优先于自我评估——编译器、测试和实时系统才是裁决者；Agent 若没有证据便声称“完成”，则视为尚未完成。
• 判断独立性——尽可能在全新上下文中进行审查，并且始终根据磁盘上的内容而非撰写时的记忆进行论证。
• LLM 之前先用确定性方法——低成本、由退出码控制的脚本处理一切机械性工作（漂移检测、工具链检查），让模型判断力只用于真正需要判断的地方。
• 渐进式披露——中心文件保持简短；模式文件、指南和检查清单仅在需要时加载。
• 与工作量相称的严谨性——每个重型阶段都可选择退出，因此一行修复不必承担十个阶段的成本。

1. 创建包含 frontmatter 的 skills/<name>/SKILL.md：name、description（它做什么以及何时使用）和 inputs（每项包含 name、required、description）。正文应保持与运行框架无关——技能文件中不应包含特定工具的指令。
2. 编写足够具体、能够验证的指令（“运行 X，预期退出码为 0”），并针对前沿模型校准：说明做什么与为什么，而不是击键级别的如何做。
3. 如果技能接近规格中 SKILL.md 约 500 行的上限，或者具有不同模式，就将其拆分为中心文件加 modes/ 文件（参见 agent-docs）。
4. Shell 辅助工具放入 scripts/：兼容 bash 3.2、自包含、默认只读——任何会修改内容的工具都必须在文件头中说明，已知限制也应写在文件头中。
5. 任何地方都不要假设仓库、语言或工具链：应从仓库中发现它们，或将其作为输入接收。

• Agent Skills——这些技能所遵循的开放格式。
• anthropics/skills——Anthropic 的参考技能集合；大多是能力型技能（文档、设计、测试工具）。
• obra/superpowers——一套完整的交互式开发方法论（头脑风暴 → 计划 → 子 Agent 驱动的 TDD）。理念相近，但重心不同：superpowers 优化人类参与其中的工作流；agent-skills 优化自主运行及其证据链。
• claude-hibernate——让正在运行的 Claude Code 会话跨重启休眠。它起源于此仓库；由于其本质上专属于 Claude Code，因此位于独立项目中。

MIT

Rigorous engineering process for AI coding agents, packaged as portable Agent Skills: implement a spec end to end to a verified PR, review code with independent judgment — your own branch, or anyone's PR — work through review feedback like a professional author, and keep documentation (agent-facing and human-facing) converged with the code it describes.

• Harness-agnostic — standard SKILL.md directories. Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, and a growing list of clients load them natively; anywhere else (Windsurf, Goose, a human with a terminal), a one-line pointer to the skill file works.
• Codebase-agnostic — no assumptions about your repo, language, or toolchain. Build/test/lint commands are discovered from the repo or passed as inputs, never hardcoded.
• Research-grounded — durable ledgers, fresh-context review, evidence-first reporting: the design decisions trace to the agent-engineering literature (rationale).

Most agents can write plausible code from a spec. What they don't do reliably is everything around that — hold the plan across a long horizon, test what they wrote, catch where the implementation quietly diverges from the spec, and prove the result rather than assert it. implement-spec packages that discipline: hand it an agent-ready spec, and it runs the lifecycle autonomously, surfacing only at the end.

spec ─▶ branch ─▶ plan + test matrix ─▶ implement (tests alongside)
     ─▶ two-pass self-review ─▶ gap analysis vs the spec ─▶ close gaps
     ─▶ live verification ─▶ PR + acceptance-criteria evidence report

• Evidence over claims — "done" means every acceptance criterion in the final report maps to a verifiable artifact (a test, a command's output, a live check) — not that the model says so.
• Survives long horizons — a durable run ledger on disk makes the run resumable across crashes and context compaction.
• Proportional rigor — every heavyweight phase (ledger, self-review, gap analysis, tests, live verification) is individually opt-out, so a one-line fix doesn't pay a ten-phase tax.

The full design rationale, with the literature behind each phase, is in skills/implement-spec/README.md.

Seven more skills stand alongside it — two scale it across sessions, the rest review, answer, and document:

When a spec is too large for one focused run, decompose-spec and orchestrate-build turn it into a resumable chain of PRs — implement-spec is still the per-ticket worker, run once per ticket in a fresh context:

• decompose-spec is the planner, and the quality ceiling of the whole build: it partitions the spec to a precise objective — the fewest tickets such that each fits one fresh context with rigor headroom and no cut severs a shared implicit decision — then reviews its own split in a fresh context and seeds the build ledger. The two bounds (context rot above, fragmented decisions below) trace to the rationale.
• orchestrate-build is the driver. Its key move: sequencing is deterministic code — a portable loop (drive-build.sh that discovers claude -p / goose run / codex exec / gemini -p) that holds no state and dispatches each ticket to a fresh context — so nothing accumulates context across the build and there is no long-lived agent context to rot. State lives in the ledger; the human pauses and intervenes at ticket boundaries by editing it. Degrades to a subagent-per-ticket or a manual fresh-session floor where a harness offers less; the rationale covers why it stays harness-agnostic.

Three seats at the same table, sharing one epistemology — every flag must be demonstrable, and precision beats recall (false positives are how reviewers lose the room):

• self-review is the author pre-PR: Pass 1 runs auto-discovered build/test/lint (via verify.sh, which infers the toolchain when the repo doesn't declare one) plus binary checklists; Pass 2 is design critique under independence rules — fresh context where the harness supports subagents, evidence-from-disk discipline where it doesn't. Also implement-spec's review phase.
• review-pr is the reviewer's seat: grounded in CI and (optionally) local verification, then separate focused passes for correctness, design, security, and scope; findings gated by demonstrability → confidence → novelty → materiality, labeled blocking/important/nit/question, capped to prevent alert fatigue, posted with suggestion blocks. It informs — approval stays human.
• address-pr-comments is the author answering: every unresolved thread gets a fix, a commit link, a reasoned push-back, an answer, or a scoped follow-up — never silence, never sycophancy, never a mid-review force-push.

Same convergence philosophy, two corpora with different consumers and quality bars — each with a deterministic, CI-gateable drift detector in front of the LLM work:

• agent-docs owns the agent-facing knowledge layer (AGENTS.md hierarchy) the other skills run on. Two modes — bootstrap (reconnaissance → gotcha mining → generation) and refresh (drift triage → surgical fixes) — auto-selected by a detector that classifies broken references as went stale vs authoring error using git history. Owns the shared Doc Authoring Guidelines.
• refresh-repo-docs owns what humans read: README, docs/, CHANGELOG, guides, examples. Its detector flags broken references and docs older than the code they cite; the audit is scoped by evidence (flagged docs, not "read the whole repo"), findings are classed stale/cruft/gap/mode-drift with Diátaxis as the per-doc quality lens, and no claim is written unverified.

As a Claude Code plugin:

/plugin marketplace add SteveVitali/agent-skills
/plugin install agent-skills@agent-skills

Or by symlink , for any client that discovers skills on disk (~/.claude/skills/, a project's .agents/skills/, etc.):

git clone https://github.com/SteveVitali/agent-skills.git ~/agent-skills
ln -s ~/agent-skills/skills/* ~/.claude/skills/

Clients without native skill support (e.g. Windsurf): a one-line workflow or rule pointing at the skill file is enough — "Read and follow<path>/skills/implement-spec/SKILL.md".

Each skill declares its inputs in SKILL.md frontmatter; state them in natural language ("implement docs/spec.md, skip the ledger, base off main"). System requirements: git, bash 3.2+, and standard Unix tools; the PR skills (review-pr, address-pr-comments) additionally need an authenticated GitHub CLI (gh).

.claude-plugin/              # plugin + marketplace manifests (Claude Code)
skills/<skill-name>/
├── SKILL.md             # entry point (Agent Skills format: frontmatter + steps)
├── README.md            # design rationale (where it exists)
├── modes/               # mode-specific step files, loaded on demand (where applicable)
├── scripts/             # supporting shell helpers (bash 3.2+ compatible)
└── checklists/          # supporting checklists / shared reference docs (where applicable)

One predictable entry filename means an agent (or tool) pointed at skills/ knows where every skill starts; everything else in a skill directory is progressive-disclosure material referenced from its SKILL.md.

• Durable state over context — anything that must survive compaction or a crash goes to disk (run ledgers, snapshots, reports), never only in context.
• External verification over self-assessment — compilers, tests, and live systems are the arbiters; an agent's claim of "done" without evidence is treated as not done.
• Judgment independence — review happens in a fresh context where possible, and always argues from what is on disk rather than memory of writing it.
• Deterministic before LLM — cheap, exit-code-gated scripts handle everything mechanical (drift detection, toolchain checks) so model judgment is spent only where judgment is required.
• Progressive disclosure — hub files stay small; mode files, guidelines, and checklists load only when needed.
• Proportional rigor — every heavyweight phase is opt-out, so a one-line fix doesn't pay a ten-phase tax.

1. Create skills/<name>/SKILL.md with frontmatter: name, description (what it does and when to use it), and inputs (each with name, required, description). Keep the body harness-neutral — no tool-specific directives in skill files.
2. Write instructions that are concrete enough to verify ("run X, expect exit 0"), and calibrated to a frontier model: specify what and why , not keystroke-level how.
3. If the skill nears the spec's ~500-line ceiling for SKILL.md or has distinct modes, split into a hub + modes/ files (see agent-docs).
4. Shell helpers go in scripts/: bash 3.2-compatible, self-contained, read-only by default — anything mutating must say so in its header, and known limitations belong in the header too.
5. No assumptions about repo, language, or toolchain anywhere: discover from the repo or take it as an input.

• Agent Skills — the open format these skills conform to.
• anthropics/skills — Anthropic's reference collection; mostly capability skills (documents, design, testing tools).
• obra/superpowers — a full interactive development methodology (brainstorm → plan → subagent-driven TDD). Kindred spirit, different center of gravity: superpowers optimizes the human-in-the-loop workflow; agent-skills optimizes the autonomous run and its evidence trail.
• claude-hibernate — hibernate running Claude Code sessions across reboots. Began in this repo; Claude Code-specific by nature, so it lives on its own.

MIT