93 lines
5.0 KiB
Markdown
93 lines
5.0 KiB
Markdown
# Coding Skills
|
|
|
|
两个中文工程 skill，用精简的当前决策保持目标一致，并将规划与实施放在不同会话。
|
|
|
|
| Skill | 用途 | 产出 |
|
|
| --- | --- | --- |
|
|
| `align-plan` | 调查代码、每轮提问 1–3 个问题、核对假设并收敛范围 | 当前决策与用户确认后的可执行计划 |
|
|
| `execute-plan` | 按已确认计划实施、验证、核对范围和 review | 外部实施记录与本地 Git commit |
|
|
|
|
## 安装
|
|
|
|
仓库采用 `skills/<名称>/SKILL.md`，每个入口包含 `name` 和 `description`，可由 [skills CLI](https://github.com/vercel-labs/skills#creating-skills) 发现。没有运行时依赖，无需插件清单。
|
|
|
|
在本地仓库目录中按需安装：
|
|
|
|
```sh
|
|
npx skills add . --skill align-plan --skill execute-plan
|
|
```
|
|
|
|
发布到 Git 仓库后，将 `.` 替换为实际的 `owner/repo` 或 Git URL。两个 skill 可单独安装，不依赖对方文件。安装时由 CLI 选择目标 agent；这里不自动安装或发布。
|
|
|
|
## 使用
|
|
|
|
在项目目录中开始规划，例如：
|
|
|
|
```text
|
|
使用 align-plan，目标是修复订单查询的分页重复问题。
|
|
本次保留现有接口格式。讨论资产放到 /绝对路径/工程讨论。
|
|
```
|
|
|
|
Agent 先调查再提问，纠正有证据的错误判断，每轮维护精简的当前决策。范围明显变大时，会提出分阶段建议供用户选择。关键问题解决后，展示完整计划，由用户确认后保存。
|
|
|
|
计划列出修改文件、目标、原因和验收要求，不预写详细实现代码。核心算法可附少量代码或伪代码帮助审查；具体实现由执行 agent 在已批准的行为和架构边界内自主决定。
|
|
|
|
随后自行开启新会话，指定保存的计划：
|
|
|
|
```text
|
|
使用 execute-plan 执行 /绝对路径/工程讨论/项目/任务/plan-v1.md
|
|
```
|
|
|
|
支持命令式调用的宿主也可使用对应的 skill 命令，具体语法以宿主为准。Skill 不负责自动创建新会话，也不能保证检测或清除旧上下文。
|
|
|
|
执行时允许增加必要测试或配置文件并说明理由；涉及业务、接口、架构或其他范围扩展时，需更新计划并确认。验证和 review 通过后创建本地提交，不 push。
|
|
|
|
## 资产约定
|
|
|
|
首次未指定资产目录时会询问；之后从项目 `.agent/MEMORY.md` 复用。这个文件只保存必要定位信息，通过 Git 本地 exclude 排除，不修改项目共享 `.gitignore`。已被跟踪时会先报告冲突，不自行取消跟踪。
|
|
|
|
讨论资产默认位于用户选择的代码库外部目录：
|
|
|
|
```text
|
|
资产根目录/
|
|
项目标识/
|
|
日期-任务主题/
|
|
current.md 当前目标、确认决策、约束与未决问题
|
|
plan-v1.md 已确认、自包含的计划
|
|
execution-日期时间.md 实施与验证记录
|
|
```
|
|
|
|
新的批准版本另存。当前决策随讨论更新，不累计聊天全文；执行记录不能覆盖已批准计划。目录失效或无法写入时会报告，不自行改存代码库。个人绝对路径不写入可分发的 skill。
|
|
|
|
每份生成的 Markdown 资产（包括本地 MEMORY）第一行保留决策日期注释：
|
|
|
|
```markdown
|
|
<!-- 决策日期：2026-09-10 -->
|
|
```
|
|
|
|
日期对应资产所依据的决策，使用用户当地日期。未确认草稿先记创建日期，正文标明待确认；确认后更新为确认日期。已批准计划保留原日期，新版本使用新确认日期；实施记录沿用计划决策日期，执行时间单独记录。纯进度或排版更新不改决策日期。
|
|
|
|
## 验证
|
|
|
|
结构检查：
|
|
|
|
```sh
|
|
npx skills add . --list
|
|
```
|
|
|
|
预期仅发现 `align-plan` 和 `execute-plan`。若已安装 skill-creator，可用其 `scripts/quick_validate.py` 分别检查两个 skill 目录；它是开发期检查工具，不是安装或运行依赖。
|
|
|
|
行为检查应使用真实 agent 在隔离项目中演练：目录首次询问与复用、错误假设纠正、长对话恢复、目标分阶段、批准前不实现、新会话交接、必要配套文件与范围扩展的区别、过期计划、测试覆盖与重复、已有用户修改及提交隔离。
|
|
|
|
结构验证只能检查格式和可发现性；静态场景复核只能发现指令缺口。两者都不证明模型实际遵循工作流，实际行为需要另行记录演练证据。不要把文字规则当作宿主级权限隔离。
|
|
|
|
## 参考来源
|
|
|
|
独立编写本仓库指令，借鉴以下机制，不复制其完整工作流，也不要求安装这些项目：
|
|
|
|
- [Ponytail](https://github.com/DietrichGebert/ponytail)：理解问题后，优先复用并选择满足目标的最小实现。
|
|
- [Superpowers](https://github.com/obra/superpowers)：参考 brainstorming 的确认边界、writing-plans 的文件与验证说明、executing-plans 的计划复核。
|
|
- [Matt Pocock Skills](https://github.com/mattpocock/skills)：参考 grill-me / grilling 的先调查事实、再讨论决策。这里限制每轮 1–3 问，以目标和验收收敛，不要求穷尽所有分支。
|
|
|
|
上游工作流会变化；本仓库的实际规则以两个 `SKILL.md` 为准。
|