impl
zuozh11/agent-skill-engineering · skills.sh
Open source Repository Open in the app JSON README (API)
About
Skill publicada por zuozh11/agent-skill-engineering no skills.sh. Instale com: npx skills add zuozh11/agent-skill-engineering@impl
Details
- Kind
- Agent skills
- Publisher
- zuozh11
- Origin
- skillssh
- Category
- ferramentas
- Stars
- 1
- Last push
- 2026-09-18T07:18:36Z
- Repository state
- ativo
- Language
- JavaScript
- License
- MIT
- Added
- 2026-10-07 06:34:45
- Updated
- 2026-10-07 06:34:45
- Origin id
zuozh11/agent-skill-engineering/impl
README
# Agent Skills — Engineering
面向开发工程师的 Agent Skill 集合，从 [mattpocock/skills](https://github.com/mattpocock/skills) 改造而来，覆盖大型事项寻路、需求收敛、接口规划、任务切分、实现提交、缺陷诊断、架构改进、代码简化和代码评审。
本仓库去掉外部 Issue Tracker 依赖，使用项目内 `CONTEXT`、`RULE`、PRD、API 清单和轻量任务卡保存上下文；实现阶段按具有业务意义的完整提交单元提交。
## 快速开始
1. 优先使用对应宿主的插件安装。Codex、Grok 和 Claude Code 均使用 marketplace / 用户级插件；只在宿主不支持插件时使用独立 Skill 安装。
2. 在目标仓库中运行 `/setup-agent-skills`。
3. 配置完成后即可使用全部 Skill。
## 安装与更新
### Codex 插件
#### 全局安装
注册仓库 marketplace，并安装插件：
```bash
codex plugin marketplace add zuozh11/agent-skill-engineering
codex plugin add agent-skill-engineering@agent-skill-engineering
```
更新 marketplace 后，重新打开 Codex 或新建任务以加载最新版：
```bash
codex plugin marketplace upgrade agent-skill-engineering
```
### Grok 插件
#### 全局安装
```bash
grok plugin install zuozh11/agent-skill-engineering#plugins/agent-skill-engineering --trust
grok plugin enable agent-skill-engineering
```
更新：
```bash
grok plugin update agent-skill-engineering
```
### Claude Code 插件
#### 全局安装
```bash
claude plugin marketplace add zuozh11/agent-skill-engineering --scope user
claude plugin install agent-skill-engineering@agent-skill-engineering --scope user
```
更新：
```bash
claude plugin marketplace update agent-skill-engineering
claude plugin update agent-skill-engineering@agent-skill-engineering --scope user
```
### 独立 Skill（兼容方式）
当宿主不支持插件或只需要单独 Skill 时使用：
项目级安装：
```bash
npx skills@latest add zuozh11/agent-skill-engineering
```
全局安装：
```bash
npx skills@latest add zuozh11/agent-skill-engineering --global
```
更新项目级或全局 Skill：
```bash
npx skills@latest update --project
npx skills@latest update --global
```
参考：[Codex 插件文档](https://developers.openai.com/codex/plugins/build)、[Grok 插件文档](https://docs.x.ai/build/features/skills-plugins-marketplaces)、[Claude Code 插件 marketplace 文档](https://docs.anthropic.com/en/docs/claude-code/plugin-marketplaces)。
---
## 工作流管线
```
大型模糊事项: wayfinder → 决策路线清晰
需求产物: to-prd | to-api | to-task（均可基于当前需求上下文独立调用）
实现提交: impl → atomic-commit
质量流程: diagnosing-bugs | code-review | improve-codebase-architecture
决策追问: ask-me
共享设计语言: codebase-design
```
`wayfinder`、`improve-codebase-architecture` 和 `setup-agent-skills` 为显式调用 Skill；其他 Skill 可按描述自动匹配，也可直接点名调用。
## 为什么要这套流程
### 问题 1：很难一次性把所有逻辑讲清楚
> _不知道怎么和 agent 讲需求，很难一次性把所有逻辑讲清楚。目标、限制、边界和取舍没说完，agent 就会用自己的假设补空白。_
**解法**：`/ask-me` 把决策组织成设计树，按依赖分轮追问。事实由 Agent 查证，只把需要用户偏好、业务判断或风险接受的关键取舍交给用户；约定范围内没有需要用户确认的关键取舍时结束，并展示设计树。
---
### 问题 2：口头需求没法复盘
> _口头描述散在对话里，缺少整体视图，人工很难回看、评审和发现遗漏。_
**解法**：`/to-prd` 生成 `PRD.md`，把需求固化成可回看、可评审的文档。
---
### 问题 3：需求太大，边界说不清
> _需求横跨多个业务结果时，直接进入实现会让任务边界和验收范围变得模糊。_
**解法**：`/to-task` 按完整业务结果生成轻量任务卡。每张卡只写需求来源、本次做什么、功能规则和验收标准，不预设技术方案、依赖或实施顺序。
---
### 问题 4：实现和提交缺少业务边界
> _按文件、技术层或改动类型拆分实现，容易产生没有独立业务意义、无法整笔回滚的提交。_
**解法**：`/impl` 根据需求分解具有业务意义的提交单元，按最小实现阶梯选择方案，调用 `/atomic-commit` 提交后收集评审 brief（本单元提交、业务结果、候选依据），交给 `/code-review` 自行判断依据适用性并决定启用 Standards 或 Spec 维度，并将确认必要的修复 amend 到当前提交。需要隔离 worktree 时用 `/impl -w`，需要子 Agent 或 workflow 时用 `/impl -a`。用户也可直接调用 `/code-review`；`--std` / `--spec` 是维度锁，只跑被锁定的维度，不传参数时评审两个互不串用的维度。
---
### 问题 5：Agent 听不懂项目术语
> _你说一个业务词，agent 不知道它对应哪个实体、模块，就只能每次重新查代码库，或者用猜的。_
**解法**：`CONTEXT.md` 沉淀项目术语、实体关系和规范命名。项目 Hook 只注入延迟选择协议，Agent 通过默认紧凑的 `scope` 取得可选 Context，最后用一次紧凑加载取得当前任务需要的完整知识。
---
### 问题 6：做过的决策被反复询问
> _数据权限怎么做、用户信息怎么取，这类长期决策不能只留在对话里，否则后续实现很容易绕开它。_
**解法**：`RULE` 按场景记录长期规则和关键决策。`scope` 一次返回按 `sceneId`、`ruleId` 排序的场景和原子规则名称；Agent 按任务相关性选择 `sceneId` 或 `ruleId` 并加载，需要时可继续补充知识，避免机械塞入全部规则正文。
---
## 核心概念
### 项目知识
工作流通过 `项目知识协议 → scope → 按需 load` 使用两类项目知识；需要落盘长期知识时再运行 `maintain`：
- **`CONTEXT.md`** — 项目术语表。定义业务概念、实体关系、规范命名。走项目知识协议的 skill 使用这里的词汇。
- **`RULE`** — 按场景组织的项目规则。`scope` 返回的 `sceneId`、`sceneName`、`ruleId` 和 `ruleName` 帮助 Agent 判断相关性，`references` 声明需要一并加载的直接依赖。
`AGENTS.md` / `CLAUDE.md` 标记块内联同一套协议，无 Hook 的宿主按该块执行。Codex / Claude Code 的 `UserPromptSubmit` Hook 只发送短提醒；协议缺失时可按提醒运行 `protocol` 恢复。上下文压缩和子 Agent 启动时，Hook 提供完整加载步骤。Agent 在需要知识时执行默认输出单行 JSON 的 `scope`，根据当前任务选择 Context、`sceneId` 或 `ruleId`；多 Context 项目可只选择 RULE。`sceneId` 加载整个场景，`ruleId` 加载单条原子 RULE。只采用直接适用、仍有效且未被本次明确要求取代的规则，已有知识足够时复用，范围变化时补充 `load`。
发现值得长期保留的项目知识时运行 `maintain`，按其返回的维护边界和格式落盘。当前请求或会话已明确授权该修改时直接完成；只对尚未授权的新规则、语义变更或冲突提问。一次性结论和能从代码确认的事实不记录；参数不清或命令报错时运行 `project-knowledge -h`。
> Hook 是知识提示入口，不是安全边界。配置损坏时提醒并继续任务；只有真实使用暴露问题时再增加约束。
### 项目文档布局
领域知识和任务都以 Markdown 文件形式存放在仓库内，不依赖外部服务：
```
docs/
├── CONTEXT.md ← 项目术语和命名约定
├── agents/
│ ├── context-format.md ← CONTEXT 与 CONTEXT-MAP 格式
│ ├── rules-format.md ← RULE 场景、命名与 references
│ └── project-knowledge.mjs ← scope、load、maintain、protocol、hook 与 validator
├── rules/ ← 项目规则（RULE）
│ ├── A01-通用约束-优先改造现有骨架.md
│ └── C01-校验规则-字段校验用BeanValidation.md
└── scratch/
└── <NN>-<中文需求名称>/ ← NN 按需求进入仓库的顺序递增
├── PRD.md ← /to-prd 按需产出
├── API清单.md ← /to-api 按需产出
└── tasks/
├── 01-完成业务结果A.md ← /to-task 按需产出
└── 02-完成业务结果B.md
```
`<NN>-<中文需求名称>` 的编号表示需求工作目录在 `docs/scratch/` 下的创建顺序；中文需求名称和任务卡名称使用 `CONTEXT.md` 中的统一术语，目录内的任务卡使用独立编号。
> 上面是单 Context 布局（大多数仓库）。monorepo（多 Context）改用 `docs/CONTEXT-MAP.md` 注册各 Context 根目录的 `CONTEXT.md`；RULE 始终统一放在领域文档根目录的 `docs/rules/`。`/setup-agent-skills` 会部署单文件脚本、只安装当前宿主的项目级 Hook，并保护已有 Agent 指令和其他 Hook。
---
## Skill 参考
### 大型事项寻路
[wayfinder](https://github.com/zuozh11/agent-skill-engineering/blob/HEAD/skills/wayfinder/SKILL.md) 把超过单次 Agent 会话容量、推进路线仍不清晰的事项记录为本地 Markdown 决策地图。它逐张解决决策票，直到迷雾和地图前沿清空，再按实际需要进入 PRD、API、任务或实现工作流。
### 主管线
| Skill | 用途 |
|-------|------|
| **[to-prd](https://github.com/zuozh11/agent-skill-engineering/blob/HEAD/skills/to-prd/SKILL.md)** | **将需求上下文整理为可独立评审的 `PRD.md`** |
| **[to-api](https://github.com/zuozh11/agent-skill-engineering/blob/HEAD/skills/to-api/SKILL.md)** | **将需求上下文规划为公开路由、内部入口、停用入口、对象图与跨接口 ID 的接口清单** |
| **[to-task](https://github.com/zuozh11/agent-skill-engineering/blob/HEAD/skills/to-task/SKILL.md)** | **按完整业务结果将需求上下文切分为轻量任务卡** |
| **[impl](https://github.com/zuozh11/agent-skill-engineering/blob/HEAD/skills/impl/SKILL.md)** | **按业务意义分解并提交最小正确实现，再收集评审 brief 交给 `code-review` 自动判定维度并 amend 必要修复；`-w` 使用 worktree，`-a` 使用子 Agent 或 workflow** |
| **[code-review](https://github.com/zuozh11/agent-skill-engineering/blob/HEAD/skills/code-review/SKILL.md)** | **只读评审固定范围；未指定维度时自动分类依据并启用有依据的维度，`--std` / `--spec` 为维度锁** |
### 关键辅助
[ask-me](https://github.com/zuozh11/agent-skill-engineering/blob/HEAD/skills/ask-me/SKILL.md) 通过持续深入的追问，打磨计划、决策或设计。使用设计树、设计树前沿和分轮追问收口决策；约定范围内没有需要用户确认的关键取舍时结束，并展示本次讨论形成的设计树。
`to-prd` 在关键业务取舍未决时使用它，需求完整则直接成稿；`to-api` 和 `impl` 只在存在影响显著且无法自行确认的决策时调用。已确认决策直接复用。`to-task` 只切分已有需求上下文，不依赖它。
[codebase-design](https://github.com/zuozh11/agent-skill-engineering/blob/HEAD/skills/codebase-design/SKILL.md) 提供最小实现阶梯，以及所有权、接口、接缝、适配器与局部性的共享设计语言。`impl` 和 `code-review` 使用阶梯选择或评判实现；涉及模块形状时再读取所有权判断。`improve-codebase-architecture` 用它评估模块深化机会。
### 其他辅助 Skill
| Skill | 用途 |
|-------|------|
| **[diagnosing-bugs](https://github.com/zuozh11/agent-skill-engineering/blob/HEAD/skills/diagnosing-bugs/SKILL.md)** | 按代码、数据和必要实验诊断；难复现、间歇或性能问题再用能变红的循环 |
| **[improve-codebase-architecture](https://github.com/zuozh11/agent-skill-engineering/blob/HEAD/skills/improve-codebase-architecture/SKILL.md)** | 扫描模块深化机会，生成可视化 HTML 报告，并围绕选中候选收口决策 |
| **[atomic-commit](https://github.com/zuozh11/agent-skill-engineering/blob/HEAD/skills/atomic-commit/SKILL.md)** | 将具有业务意义的完整提交单元整理为可直接回滚的本地提交 |
### 配置
| Skill | 用途 |
|-------|------|
| **[setup-agent-skills](https://github.com/zuozh11/agent-skill-engineering/blob/HEAD/skills/setup-agent-skills/SKILL.md)** | 部署项目知识脚本与格式，并安装当前宿主的项目级 Hook |
---
## 与原版的差异
| 原版 (mattpocock/skills) | 本仓库 |
|--------------------------|--------------------------------------------------|
| `/wayfinder` 使用 Issue Tracker 保存地图和决策票 | 使用 `docs/scratch/<需求>/WAYFINDER.md` 与 `wayfinder/` 本地 Markdown 文件 |
| 依赖 Issue Tracker 和 triage labels | 使用项目内 `CONTEXT`、`RULE` 和 Markdown 需求材料 |
| `/to-spec` 发布规格到 Issue Tracker | `/to-prd` 在本地生成 PRD |
| `/to-tickets` 发布 tracer-bullet tickets | `/to-task` 生成只描述需求的轻量任务卡 |
| `/implement` 驱动 TDD 并衔接代码评审 | `/impl` 按业务意义选择并提交最小正确实现，再收集评审 brief 交给 `code-review` 自动判定维度并 amend 必要修复 |
| `/triage` 管理 Issue 分诊状态机 | 移除，本地工作流不维护分诊状态机 |
| 英文 Skill | 翻译核心方法，并接入项目知识与本地授权边界 |
## 维护与验证
`skills/` 是技能内容的权威目录，插件内的技能目录由脚本同步。评审按维度读取 `STANDARDS.md` 或 `SPEC.md`；安装按宿主读取 Hook 分支；接口模板在成稿时读取。全量 Standards 仍逐条核对全部 RULE 和目标代码段。
```bash
bash scripts/sync-codex-plugin-skills.sh
node --test tests/plugin-mirror.test.mjs skills/setup-agent-skills/tests/project-knowledge.test.mjs
```
技能行为另用 [独立样例](https://github.com/zuozh11/agent-skill-engineering/blob/HEAD/evals/skill-behavior/README.md) 验证，覆盖完整与未决 PRD、已有授权、单维度评审和修复交付。行为样例需要真实 Agent 执行，普通单元测试不代表这些样例已通过。已有项目升级知识协议时重新运行 `/setup-agent-skills`；插件更新不会自动改写其他仓库部署的脚本。
## 通用工作流工具
除工程 skill 外，推荐搭配安装 [mattpocock/skills](https://github.com/mattpocock/skills) 中的通用生产力工具：
| Skill | 用途 |
|-------|------|
| **handoff** | 将当前对话压缩为一份交接文档，以便其他 agent 可以继续后续工作 |
| **writing-great-skills** | 创建和改进可预测、边界清晰的 Skill |
安装命令：
```bash
npx skills@latest add mattpocock/skills \
-s handoff \
-s writing-great-skills
```
## 致谢
基于 [Matt Pocock](https://github.com/mattpocock) 的 [skills](https://github.com/mattpocock/skills) 仓库改造；最小实现、代码评审与架构改进中的简化原则融合自 Dietrich Gebert 的 [Ponytail](https://github.com/DietrichGebert/ponytail)。项目知识、业务意义提交和代码所有权设计分别吸收了 DDD、A Philosophy of Software Design 与 The Pragmatic Programmer 的思想。
## 许可证
本项目基于 [MIT License](https://github.com/zuozh11/agent-skill-engineering/blob/HEAD/LICENSE) 发布。