# Programming Agent Skills：为编码智能体设计的实用工作流技能包

> Programming Agent Skills 是一个面向编码智能体的开源技能包，提供从代码库入门、范围澄清到调试、清理、子智能体协调等16个可复用技能，帮助智能体在真实软件仓库中实现更可靠、可验证的工程行为。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-06-14T19:45:33.000Z
- 最近活动: 2026-06-14T19:54:16.133Z
- 热度: 161.8
- 关键词: coding agent, agent skills, workflow, debugging, GitHub tracking, subagent, codebase cleanup, verification, TDD
- 页面链接: https://www.zingnex.cn/forum/thread/programming-agent-skills
- Canonical: https://www.zingnex.cn/forum/thread/programming-agent-skills
- Markdown 来源: ingested_event

---

## 原作者与来源

- 原作者/维护者：stevennitesh
- 来源平台：GitHub
- 原始标题：programming-agent-skills
- 原始链接：https://github.com/stevennitesh/programming-agent-skills
- 来源发布时间/更新时间：2026-06-14T19:45:33Z

---

## 项目背景：编码智能体的可靠性挑战

随着大型语言模型能力的提升，编码智能体（Coding Agents）正在从实验性工具走向实际应用。然而，这些智能体在真实软件仓库中的表现往往存在可预测的问题：过度规划、过度构建、依赖过时的代码摘要、跳过问题复现、在理解基线之前就进行修改、丢失用户更改的追踪，或者在未经验证的情况下就声称任务完成。

Programming Agent Skills 项目正是为解决这些问题而诞生。它不是一个庞大的流程框架，而是一套精心设计的**可移植技能包**，旨在引导智能体走向更可靠、更负责任的工程行为。

## 核心理念与设计原则

项目的设计受到多个思想的影响，包括 Superpowers 风格的技能工作流、Matt Pocock 对工程纪律的偏好，以及 Andrej Karpathy 关于智能体失败模式和编码权衡的讨论。其核心设计理念可以概括为：

### 证据优先于印象
智能体应当优先阅读相关的源代码、测试、日志、文档和 CI 输出，而不是依赖可能过时的摘要。

### 最小有效工作流
为任务选择最小的可靠工作流，而非应用所有可能的流程。

### 可审查的变更
偏好小而可审查的变更，而非大范围的重写。

### 验证先于声明
将测试、命令输出、差异比较、CI 状态和行为观察视为证据，在声称完成前进行验证。

### 保护用户工作
诚实地保护用户的工作和状态不确定性，避免破坏性的 Git 操作。

## 技能架构：控制器与门控

技能包采用双层架构，区分两种类型的技能：

### 控制器技能（Controlling Skills）
控制器技能主导主要工作流，包括代码库入门、范围澄清、规划、跟踪执行、实现、调试、清理和技能创作。它们是智能体执行任务的"大脑"。

### 门控技能（Gate Skills）
门控技能在风险边界介入，包括工作空间安全、持久跟踪、子智能体协调、并行实现的隔离，以及最终验证。它们是智能体的"安全网"。

这种分离确保了智能体既能高效执行任务，又能在关键节点保持谨慎。

## 16个核心技能详解

项目包含16个精心设计的技能，每个技能都有明确的触发条件、目的、程序、停止/询问条件和交接规则。

### 代码库入门与路由

**repo-onboarding（代码库入门）**
当智能体需要学习不熟悉的代码库时使用。它会读取代码库的指令、命令、上下文、跟踪器约定和安全约束，为后续工作建立基础。

**coding-router（编码路由器）**
非平凡代码库任务的核心入口。它根据请求、代码库证据、风险和预期完成检查，选择最小的可靠下一步工作流。这是大多数工作的起点。

### 范围与规划

**clarify-scope（澄清范围）**
当请求不清晰、范围过广、涉及架构或具有风险时使用。帮助智能体在动手前理解真正需要做什么。

**slice-plan（切片规划）**
已批准的工作需要多个可审查的源代码、测试、文档或跟踪切片时使用。将大任务分解为可管理的部分。

**issue-driven-execution（问题驱动执行）**
当工作由 GitHub Issues 支持时使用。将工作转化为计划文档和问题，一次处理一个已声明、已验证的实现或研究问题。

### 实现与开发

**tdd-slice（TDD 切片）**
实现或更改一个调用者可见的行为时使用。遵循测试驱动开发模式，确保变更有明确的验证标准。

**github-tracking（GitHub 跟踪）**
当 Issues、PRD、PR、CI 状态、审查线程或持久的 GitHub 记录有用时使用。帮助智能体与现有的开发流程集成。

**pre-pr-review（PR 前审查）**
分支、提交、工作树或 PR 就绪的差异需要在打开或更新拉取请求前进行语义审查时使用。

### 调试与诊断

**diagnose-loop（诊断循环）**
测试、构建、CI、日志、输出、崩溃或行为失败且原因尚不清楚时使用。提供结构化的调试流程，从证据出发定位问题。

### 重构与清理

**codebase-cleanup（代码库清理）**
清理或重构工作应在保持行为的同时使未来变更更容易时使用。确保重构不会引入回归。

### 子智能体协调

**subagent-workflow（子智能体工作流）**
当有限的代码库探索、实现或审查可以安全地通过子智能体运行时使用。定义了父智能体如何委托和审查子智能体的工作。

**worktree-isolation（工作树隔离）**
已批准的跨智能体或会话的并行实现需要单独的分支/工作树时使用。还定义了重叠工作的集成策略。

### 安全与验证

**workspace-safety（工作空间安全）**
当脏树、分支、暂存区、提交、生成的输出、依赖安装或有风险的 Git/文件操作需要小心处理时使用。防止意外破坏用户工作。

**verify-before-done（完成前验证）**
智能体即将声称工作已完成、已修复、已审查、通过、安全、就绪或可合并时使用。强制要求在声明前提供证据。

### 技能创作

**author-skills（创作技能）**
创建或修订编码智能体技能或技能包指令时使用。确保技能本身的质量和一致性。

## 典型工作流路径

技能包设计了多种典型路径，覆盖常见的开发场景：

### 新代码库或过时上下文
```
repo-onboarding -> coding-router -> 选定工作流
```

### GitHub 支持的多问题工作
```
issue-driven-execution -> 计划文档和问题 -> 声明、实现、检查点和验证每个问题
```

### 功能或行为请求
```
coding-router -> clarify-scope 或 slice-plan -> tdd-slice -> verify-before-done
```

### Bug、失败测试或 CI 错误
```
coding-router -> diagnose-loop -> 专注的源代码变更和回归检查 -> verify-before-done
```

### 清理或重构
```
coding-router -> codebase-cleanup -> 行为保持切片 -> verify-before-done
```

### PR 或审查工作
```
coding-router -> github-tracking -> 源代码变更或响应 -> verify-before-done
```

### 多智能体实现
```
控制器技能 -> subagent-workflow -> worktree-isolation（已批准的并行实现） -> 父集成、差异审查和验证
```

## 使用方法与部署

### AGENTS.md 路径
当需要可移植的全局默认值而不安装任何技能时，使用 `AGENTS.md`。将其复制到智能体的全局指令位置或编程仓库中，然后添加仓库特定的真实来源文件、命令、约束和发布规则。

### 技能目录路径
当智能体运行时支持可加载技能时，复制所需技能到本地技能目录，或指向此仓库的 `skills/` 目录（如果支持仓库本地技能）。

### Codex 风格快速启动
```bash
mkdir -p "$CODEX_HOME/skills"
cp -R skills/repo-onboarding "$CODEX_HOME/skills/"
cp -R skills/coding-router "$CODEX_HOME/skills/"
cp -R skills/workspace-safety "$CODEX_HOME/skills/"
cp -R skills/verify-before-done "$CODEX_HOME/skills/"
```

建议从 `repo-onboarding`、`coding-router`、`workspace-safety` 和 `verify-before-done` 开始，然后根据需要添加其他技能。

## 验证与质量保证

项目包含静态验证脚本 `scripts/validate-skills.sh`，用于检查：

- 技能前置元数据的完整性
- README 技能映射的一致性
- 退役词汇的使用情况
- 发布 markdown 中的尾随空格
- `git diff --check` 输出

对于公开发布，添加 `--public` 标志还会检查：
- 跟踪的源代码语料路径
- 忽略的本地源代码语料目录
- 过时的技能名称
- 本地标识符或类密钥模式
- Git 历史/对象路径

## 项目现状与路线图

这是一个实验性基线，但已经过高风险工作流的测试。项目开发者表示，随着实际工作暴露弱措辞、缺失检查、不清晰交接或不必要的流程，未来会有修订。

项目采用 MIT 许可证，鼓励社区贡献和采用。

## 结语

Programming Agent Skills 为编码智能体领域带来了一个重要的范式转变：从追求更强大的模型能力，转向设计更可靠的工程行为。通过提供结构化的工作流技能，它帮助智能体在真实软件仓库中表现得像负责任的工程师——阅读代码、理解上下文、小心操作、验证结果。

对于正在使用或构建编码智能体的开发者和团队来说，这个技能包提供了一个经过深思熟虑的起点，可以显著提升智能体的可靠性和实用性。