Leeaoyin/dr-agent-skills

技能

一个用于收集、整理和复用 Agent 技能的个人仓库。

本仓库存储可复用的技能，适用于 AI agent、编码 agent、文档生成 agent、代码审查 agent、工具使用 agent、工程工作流、上下文管理和 token 优化。

每个技能都组织为一个独立目录，包含清晰的使用场景、激活条件、执行流程、约束、输出要求和示例。

目标

本仓库并非旨在成为简单的提示词集合。

其目的是将可复用的 agent 工作流转化为结构化、可维护且可验证的技能。

主要目标包括：

* 捕获可复用的 agent 工作流
* 规范技能结构和编写约定
* 提高编码 agent 和通用 agent 的可靠性
* 减少重复的提示词编写
* 降低不必要的上下文 token 消耗
* 鼓励 agent 复用现有工具、框架和项目能力
* 为复杂任务提供明确的流程、边界和失败策略
* 为自定义 agent、基于 MCP 的 agent 和 Agent OS 设计提供可复用的能力模块

什么是技能？

在本仓库中，技能是针对某一类任务的结构化能力定义。

一个技能通常定义：

* 适用场景
* 激活条件
* 执行流程
* 输入要求
* 输出格式
* 约束
* 工具使用规则
* 失败策略
* 示例
* 质量检查清单

技能不同于一次性提示词。提示词通常为单次交互而编写，而技能则面向长期复用、工程一致性和稳定执行。

仓库结构

推荐结构：

skills/
├── README.md
├── README-ZH.md
├── framework-first-coding/
│   ├── SKILL.md
│   ├── README.md
│   └── README-ZH.md
├── agent-harness-evaluation-skill/
│   ├── SKILL.md
│   ├── README.md
│   └── README-ZH.md
└── references/
├── skill-template.md
├── writing-guide.md
└── quality-checklist.md

其中：

* README.md 是仓库级文档
* /SKILL.md 是 agent 使用的核心规则文件
/README.md 是面向开发者和维护者的人类可读说明
references/ 包含共享模板、编写指南、检查清单和参考资料

包含的技能

框架优先编码技能

目录：

framework-first-coding/

目的：

约束编码 agent 在编写自定义实现代码之前，先检查并复用现有框架特性、依赖、SDK、工具类、共享组件和项目抽象。

适用于：

* 添加 API
* 修复 bug
* 重构代码
* 集成第三方 API
* 编写数据库查询
* 请求验证
* 授权处理
* 文件上传
* HTTP 调用
* 日志、缓存、调度及其他常见工程任务

核心原则：

先查找现有能力。仅在必要时编写新代码。

此技能有助于减少重复实现、降低 token 消耗、提升代码一致性并增强可维护性。

Agent Harness 评估技能

目录：

agent-harness-evaluation-skill/

用途：

通过确定性测试、故障注入、混沌场景和可靠性指标，系统性地评估 AI Agent Harness 实现的健壮性、可靠性、安全性、可恢复性、上下文工程效率和生产就绪度。

适用于：

* 构建新的 Agent 框架
* 在发布前审查现有 Agent 系统
* 向 harness 中引入新工具
* 更改重试或检查点机制
* 升级模型提供商
* 添加多 Agent 工作流
* 衡量提示缓存和上下文效率
* 为生产部署做准备

核心原则：

评估执行框架，而非模型智能。

此技能有助于在生产前发现可靠性缺口、防止重复副作用和安全违规、验证恢复机制，并强制执行生产门禁标准。

技能编写约定

每个技能通常应至少包含两个文件：

skill-name/
├── SKILL.md
└── README.md

SKILL.md

SKILL.md 是 agent 读取和执行的核心文件。它应当清晰、可操作且简洁。

推荐结构：

name: skill-name
metadata:
version: "1.0"
category: "category-name"
description: "一句话描述何时以及为何使用此技能。"

技能名称

用途

何时使用

输入

执行流程

输出要求

约束

工具使用规则

失败策略

质量检查清单

示例

README.md

README.md 是为人编写的。它可以更详细地解释背景、用途、适用场景、行为和示例。

推荐结构：

技能名称

概述

为什么需要此技能

适用场景

工作原理

预期的 Agent 行为

目录结构

用法

示例

局限性

推荐搭配

命名约定

技能目录名称应使用小写英文单词和连字符：

framework-first-coding
minimal-patch-coding
code-review
security-review
document-generation
tool-failure-strategy

避免：

FrameworkFirstCoding
framework_first_coding
框架优先编码
skill1
my-skill-new

命名原则：

* 简短
* 清晰
* 可搜索
* 描述核心能力
* 避免不必要的抽象

建议的技能分类

技能可以按任务类型分组。

编码技能

用于代码生成、修改、重构和审查。

示例：

* framework-first-coding
* minimal-patch-coding
* code-review
* security-review
* test-first-coding
* dependency-inspection
* project-convention-following
智能体技能

用于智能体执行流程、工具使用和任务编排。

示例：

* tool-use-planning
* tool-failure-strategy
* multi-step-task-execution
* human-in-the-loop
* agent-loop-control
* context-compaction

文档技能

用于创建、编辑、总结和结构化文档。

示例：

* document-generation
* technical-report-writing
* research-summary
* docx-processing
* slide-generation
* proposal-writing

检索技能

用于搜索、RAG、证据提取和知识库问答。

示例：

* rag-answering
* evidence-based-research
* academic-search
* web-research
* source-grounded-summary

评估技能

用于评估、评分、检查和质量管理。

示例：

* agent-harness-evaluation-skill
* benchmark-design
* answer-evaluation
* rubric-scoring
* quality-check
* regression-test-analysis

推荐技能模板

创建新技能时，请使用以下模板：

name: example-skill
metadata:
version: "1.0"
category: "general"
description: "Use this skill when..."

Example Skill

Purpose

Describe the purpose of this skill.

When to Use

Use this skill when:

- Condition 1
- Condition 2
- Condition 3

Inputs

Expected inputs:

- Input 1
- Input 2

Execution Procedure

Step 1: Understand the Task

Clarify the goal, constraints, and expected output.

Step 2: Inspect Available Context

Check existing files, tools, dependencies, documents, or prior state.

Step 3: Execute the Task

Follow the defined workflow.

Step 4: Validate the Result

Check correctness, completeness, safety, and formatting.

Output Requirements

The output should include:

- Required item 1
- Required item 2
- Required item 3

Constraints

The agent must:

- Constraint 1
- Constraint 2

The agent must not:

- Forbidden behavior 1
- Forbidden behavior 2

Failure Strategy

If the task cannot be completed:

1. Explain what failed.
2. Explain what was attempted.
3. Provide the best partial result.
4. Suggest the next safe action.

Quality Checklist

Before finalizing, check:

- [ ] The task goal is satisfied
- [ ] The output follows the requested format
- [ ] No unnecessary implementation is added
- [ ] Existing tools or context were used properly
- [ ] Risks and limitations are stated when relevant

Examples

Example usage:
text
Use this skill to...

设计原则

本仓库中的技能应遵循以下原则。

1. 可操作

技能不应仅描述抽象原则。它应告诉智能体：

- 何时使用
- 首先做什么
- 接下来做什么
- 何时停止
- 出现失败时该怎么做
- 输出应是什么样子

2. 可复用

技能应适用于一类任务，而不仅仅是一次对话。

不推荐：

Help me fix this login API this time.

推荐：

修复后端 API 问题时，首先检查路由、HTTP 方法、参数绑定、安全拦截、异常日志以及现有项目约定。

3. 可组合

一个技能应能与其他技能协同工作。

示例：

框架优先编码技能
+ 最小补丁技能
+ 安全审查技能
+ 测试验证技能

4. 可验证

一个技能应包含检查清单，以便审查输出。

示例：

- 智能体是否复用了现有框架能力？
- 智能体是否避免了重复实现？
- 智能体是否遵循了项目约定？
- 智能体是否在相关时解释了失败原因？

5. Token 高效

一个技能应减少不必要的输出。

推荐做法：

* 清晰定义输出格式
* 避免冗长的背景解释
* 避免反复解释基础概念
* 避免不必要地输出整个文件
* 优先使用差异、聚焦步骤和最小变更

使用方式

本仓库可以通过多种方式使用。

作为 Claude Code 技能

将技能目录放置在 Claude Code 可识别的位置。

skills/
└── framework-first-coding/
├── SKILL.md
└── README.md

作为 Cursor 或 IDE 规则

从 SKILL.md 中提取核心规则到项目级规则文件。

示例：

.cursor/rules/framework-first-coding.mdc

作为自定义智能体的能力模块

在自定义智能体系统中，技能可以作为能力声明或策略模块加载：

智能体接收任务
→ 根据描述匹配技能
→ 加载 SKILL.md
→ 遵循执行流程
→ 使用检查清单验证

作为 MCP 智能体的工具使用约束

对于支持 MCP 的智能体，技能可以约束工具选择、文件读取、代码搜索、构建检查、测试执行和失败处理。

维护工作流

添加新技能时：

1. 定义该技能解决的问题。
2. 确认它适用于一类可复用的任务。
3. 创建独立目录。
4. 编写 SKILL.md。
5. 编写 README.md。
6. 添加示例输入和预期输出。
7. 添加质量检查清单。
8. 在根 README.md 中注册该技能。
9. 根据真实失败案例进行迭代。

技能质量检查清单

在添加或修改技能之前，请检查：

* [ ] 技能有清晰的名称
* [ ] 技能有清晰的描述
* [ ] 定义了适用场景
* [ ] 定义了不适用场景
* [ ] 执行步骤明确
* [ ] 定义了输出要求
* [ ] 定义了约束条件
* [ ] 包含失败策略
* [ ] 包含质量检查清单
* [ ] 技能能减少重复工作
* [ ] 技能能减少智能体行为的不确定性
* [ ] 技能能与其他技能组合
* [ ] 技能避免过度复杂
* [ ] 技能避免只有模糊原则而缺乏执行细节

推荐组合

在真实智能体系统中，可以将多个技能组合成完整的工作流。
编码智能体组合

framework-first-coding
+ minimal-patch-coding
+ project-convention-following
+ test-verification
+ security-review

研究智能体组合

web-research
+ evidence-based-summary
+ source-citation
+ contradiction-check
+ report-writing

文档智能体组合

document-generation
+ outline-planning
+ style-consistency
+ docx-processing
+ final-quality-check

RAG 智能体组合

retrieval-planning
+ query-rewriting
+ evidence-selection
+ answer-grounding
+ hallucination-check

版本管理

每个技能应维护自己的版本号。

示例：

metadata:
version: "1.0"

建议的版本管理方式：

* 1.0：初始可用版本
* 1.1：小幅规则调整
* 1.2：新增示例或检查清单项
* 2.0：执行流程或设计目的发生重大变更

路线图

可能新增的技能：

* 最小补丁编码技能
* 工具失败策略技能
* 依赖检查技能
* 项目约定技能
* 代码审查技能
* 安全审查技能
* RAG 回答技能
* 基于证据的研究技能
* 文档生成技能
* 智能体循环控制技能
* 上下文压缩技能
* 人在回路技能
* 上下文工程技能
* 多智能体通信技能

总结

本仓库管理个人积累的智能体技能。

其核心价值是：

将一次性的提示词经验转化为可复用、可组合、可维护、可验证的智能体能力模块。

通过持续收集和完善技能，本仓库可以成为编码智能体、研究智能体、文档智能体、MCP 智能体以及自定义 Agent OS 实现的可复用能力库。