# AgentSkills 项目研究报告

| 项目名称 | AgentSkills —— AI 智能体技能集               |
| -------- | -------------------------------------------- |
| 报告类型 | 项目研究报告（PROJECT_REPORT）               |
| 报告日期 | 2026-08-08                                   |
| 许可证   | MIT License（Copyright © 2026 Shuery-Shuai） |

---

## 摘要

本项目构建了一套面向 AI 编码智能体（Agent）的开源技能（Skills）集合——AgentSkills。项目以「提示词 + 接口策略」为核心组织单元，每个技能由一个 `SKILL.md`（定义角色、工作流、行为准则与输出格式的完整提示词）与一个 `agents/openai.yaml`（定义展示名、简介与调用策略）组成。技能按「开发与规范 → 测试与修复 → 交付与部署 → 全自动化」四层递进组织，共 18 个技能，覆盖从代码规范、质量保障到生产部署、监控告警的完整软件工程闭环。项目同时提供 `skills_linker.sh` 一键安装脚本，可将全部技能软链接至全局技能目录，实现开箱即用。本项目采用 MIT 许可证开源，不包含第三方运行时依赖，许可证合规状态为完全合规。

**关键词**：AI 智能体；技能（Skills）；质量工程；自动化流水线；软件工程

---

## 第1章 绪论

### 1.1 项目背景

随着大语言模型（LLM）与 AI 编码智能体的快速发展，如何让智能体稳定、可复用地完成「代码审查、缺陷修复、性能测试、生产部署、监控告警」等工程化任务，已成为开发者社区关注的热点。传统上，这些任务依赖人工或碎片化的脚本，难以与 AI 智能体无缝衔接；而将领域知识封装为结构化的「技能」（Skills），则可以让智能体按既定流程执行高质量工程任务。

### 1.2 项目意义

本项目通过将多年软件工程实践沉淀为 18 个可复用、可组合的技能，实现以下价值：

- **能力升级**：将 AI 从「问答助手」升级为「质量工程团队」，使其具备端到端工程执行能力；
- **质量闭环**：形成「发现缺陷 → 自动修复 → 语法检查 → 性能验证 → 回归测试」的完整闭环；
- **安全可控**：内置生产环境保护、敏感信息脱敏、最小权限与人工确认点等安全规则；
- **可观测可审计**：每个技能输出带时间戳的结构化 Markdown 报告，全程留痕、便于追溯。

### 1.3 项目目标

1. 提供一套**开箱即用**、跨平台的智能体技能定义；
2. 通过技能互链形成**可组合的自动化流水线**（如 CI/CD 闭环）；
3. 保证工程任务执行的**安全性与可审计性**；
4. 以 **MIT 许可证**开源，降低社区采用门槛。

### 1.4 报告结构

本报告共七章：第 2 章介绍开发技术与许可证合规分析；第 3 章进行需求分析；第 4 章阐述详细设计；第 5 章说明编码与实现；第 6 章给出系统测试方法与结果；第 7 章进行总结与展望。附录 A 提供许可证清单，附录 B 汇总文档质量检查（lint / prettier / 死链）执行摘要。

---

## 第2章 开发技术

### 2.1 技术栈概述

本项目为「文档 + 配置 + 脚本」型仓库，技术栈轻量且无运行时依赖：

| 层面           | 技术 / 格式                                         | 说明                                            |
| -------------- | --------------------------------------------------- | ----------------------------------------------- |
| 技能提示词     | Markdown（GFM）                                     | `SKILL.md` 定义角色、工作流、行为准则与输出格式 |
| 接口与策略     | YAML                                                | `agents/openai.yaml` 定义展示信息与调用策略     |
| 安装与自动化   | Bash（Shell）                                       | `skills_linker.sh` 实现一键软链接安装           |
| 图表与文档增强 | Mermaid / shields.io                                | 架构图、流程图与徽章                            |
| 质量工具链     | shellcheck / markdownlint-cli2 / prettier / js-yaml | 语法检查与格式化                                |

### 2.2 核心技术

1. **SKILL.md 提示词规范**：采用统一的章节模板（角色与描述、支持格式、工作模式、行为准则、输出格式），使技能可被智能体稳定解析与执行；
2. **agents/openai.yaml 策略配置**：以结构化字段（`interface` / `policy`）描述技能的展示信息、隐式调用许可、确认要求与重试次数；
3. **技能互链机制**：技能之间通过 `/技能名` 相互调用，形成可复用的自动化链路（如 `ci-cd-pipeline` 串联 13 个子技能）；
4. **一键安装脚本**：`skills_linker.sh` 遍历分类目录，将各技能软链接至 `~/.agents/skills/`，实现全局可用。

### 2.3 许可证合规分析

本项目采用 **MIT License**（Copyright © 2026 Shuery-Shuai）。经对项目根目录及子目录扫描，未发现 `package.json`、`pyproject.toml`、`go.mod`、`requirements.txt`、`Cargo.toml`、`composer.json` 等任何第三方依赖清单文件，即**项目不包含第三方运行时依赖**，因此不存在依赖许可证冲突风险。

| 检查项       | 结果                                    |
| ------------ | --------------------------------------- |
| 项目主许可证 | ✅ MIT License（与 `LICENSE` 文件一致） |
| 第三方依赖   | ✅ 无（依赖文件数 = 0）                 |
| 许可证冲突   | ✅ 无                                   |
| 合规结论     | **完全合规**                            |

> [!NOTE]
>
> 文档中引用的 shields.io（徽章）与 Mermaid（图表）为在线服务或渲染库，不构成代码层面的许可证依赖；若未来引入第三方依赖，建议补充执行依赖许可证扫描。

---

## 第3章 需求分析

### 3.1 功能需求

按四大分类归纳的 18 个技能功能需求如下：

| 分类       | 技能                          | 功能需求描述                                                                 |
| ---------- | ----------------------------- | ---------------------------------------------------------------------------- |
| 开发与规范 | `readme-generator`            | 遍历项目生成开源风格 README，含徽章、Mermaid、提示块与死链检查               |
| 开发与规范 | `academic-readme-writer`      | 生成论文格式 `PROJECT_REPORT.md`，集成格式化、死链检查与许可证信息           |
| 开发与规范 | `google-style-formatter`      | 将代码重构为严格 Google 风格，补全注释并调用权威格式化工具                   |
| 开发与规范 | `syntax-checker`              | 自动识别语言并调用编译器 / linter 做语法检查，输出结构化报告                 |
| 开发与规范 | `dependency-security-scanner` | 扫描依赖已知漏洞（CVE），输出风险报告与修复优先级                            |
| 开发与规范 | `doc-link-checker`            | 检查 Markdown 文档外部链接可达性，标记死链并生成报告                         |
| 测试与修复 | `blackbox-tester`             | 黑盒测试：环境确认 → 用例生成 → 缺陷报告（仅限测试服务器）                   |
| 测试与修复 | `unit-test-generator`         | 分析源码自动生成缺失单元测试，覆盖正常 / 边界 / 异常场景                     |
| 测试与修复 | `bug-fixer-from-tests`        | 解析缺陷报告 → 定位根因 → 最小化修复 → 回归验证指引                          |
| 测试与修复 | `performance-baseline-tester` | 对核心 API 做性能基准测试，与历史基线对比识别退化                            |
| 测试与修复 | `auto-test-and-fix`           | 端到端编排「测试→修复→语法检查→性能→回归」闭环                               |
| 交付与部署 | `db-migration-checker`        | 分析迁移脚本风险（危险操作 / 锁表），支持预发环境模拟执行                    |
| 交付与部署 | `deploy-to-production`        | 多重确认下部署生产，集成迁移审查、健康检查与监控规则生成                     |
| 交付与部署 | `license-compliance-checker`  | 扫描依赖开源许可证，检查与主许可证的兼容性与冲突                             |
| 交付与部署 | `log-monitor-rule-generator`  | 扫描日志输出，生成 ELK / Loki / Prometheus 监控与告警规则                    |
| 全自动化   | `ci-cd-pipeline`              | 串联 13 个子技能的全自动 CI/CD 闭环                                          |
| 全自动化   | `project-health-check`        | 全量质量体检（安全 / 语法 / 测试 / 性能 / 文档 / 合规），输出 0-100 综合评分 |
| 全自动化   | `release-orchestrator`        | 发布管理：决定版本号、生成变更日志、创建标签、触发 CI/CD、监控与回滚         |

### 3.2 非功能需求

| 类别     | 需求描述                                                                |
| -------- | ----------------------------------------------------------------------- |
| 安全性   | 生产环境保护、敏感信息脱敏、最小权限、人工确认点                        |
| 可观测性 | 每个技能输出 `*_<timestamp>.md` 结构化报告，全程留痕                    |
| 可复用性 | 技能可独立使用，也可通过 `/技能名` 互链组合                             |
| 兼容性   | 覆盖 Python / Node / Java / Go / Shell / YAML / Markdown 等多语言工具链 |
| 可维护性 | 目录按分类组织，技能模板统一，便于新增与维护                            |

### 3.3 需求用例概览

以「CI/CD 全流程」为例，系统需按阶段依次调用安全扫描、黑盒测试、缺陷修复、格式化、文档生成、迁移审查与生产部署，任一阶段失败即暂停并报告：

```mermaid
flowchart LR
    R1["用户发起 CI/CD"] --> S0["静态分析<br/>(安全/许可证/语法)"]
    S0 --> S1["黑盒测试"]
    S1 -->|有缺陷| S2["缺陷修复 + 回归(≤3次)"]
    S2 --> S1
    S1 -->|通过| S3["测试增强 + 性能验证"]
    S3 --> S4["代码规范化 + 语法复查"]
    S4 --> S5["文档生成 + 死链检查"]
    S5 --> S6["数据库迁移审查"]
    S6 --> S7["生产部署"]
    S7 --> S8["监控规则生成"]
    S8 --> R2["生成 cicd_report"]
```

---

## 第4章 详细设计

### 4.1 系统总体架构

系统按「开发与规范 → 测试与修复 → 交付与部署 → 全自动化」四层递进组织，形成完整质量闭环：

```mermaid
flowchart TB
    subgraph SK["🧩 AgentSkills（18 技能）"]
        A["🛠️ 开发与规范<br/>readme-generator · syntax-checker<br/>google-style-formatter · doc-link-checker<br/>dependency-security-scanner · academic-readme-writer"]
        B["🧪 测试与修复<br/>blackbox-tester · unit-test-generator<br/>bug-fixer-from-tests · performance-baseline-tester<br/>auto-test-and-fix"]
        C["🚀 交付与部署<br/>db-migration-checker · deploy-to-production<br/>license-compliance-checker · log-monitor-rule-generator"]
        D["🤖 全自动化<br/>ci-cd-pipeline · project-health-check<br/>release-orchestrator"]
    end
    A --> B --> C
    B -.->|"auto-test-and-fix 闭环"| B
    D -->|"编排调用"| A
    D -->|"编排调用"| B
    D -->|"编排调用"| C
```

### 4.2 模块设计

#### 4.2.1 仓库目录结构

```text
AgentSkills/
├── skills_linker.sh                  # 一键安装脚本（软链接到 ~/.agents/skills/）
├── README.md                         # 项目说明
├── PROJECT_REPORT.md                 # 项目研究报告（本文件）
├── LICENSE                           # MIT 许可证
├── .markdownlint.json                # Markdown 规范配置
├── development-and-standards/        # ① 开发与规范（6 个技能）
├── testing-and-fixing/               # ② 测试与修复（5 个技能）
├── delivery-and-deployment/          # ③ 交付与部署（4 个技能）
└── full-automation/                  # ④ 全自动化（3 个技能）
```

#### 4.2.2 单个技能的内部结构

```text
<skill-name>/
├── SKILL.md              # 技能提示词（角色、工作流、行为准则、输出格式）
└── agents/
    └── openai.yaml       # 接口与策略配置（display_name / policy）
```

### 4.3 配置数据结构设计

`agents/openai.yaml` 采用两层结构，字段说明如下：

| 字段                               | 类型    | 说明                           |
| ---------------------------------- | ------- | ------------------------------ |
| `interface.display_name`           | string  | 技能展示名称                   |
| `interface.short_description`      | string  | 技能简介（用于调用方理解用途） |
| `policy.allow_implicit_invocation` | boolean | 是否允许隐式调用               |
| `policy.require_confirmation`      | boolean | 执行副作用操作前是否需人工确认 |
| `policy.max_retries`               | int     | 最大重试次数（避免死循环）     |

### 4.4 交互流程设计

「测试→修复→回归」闭环由 `auto-test-and-fix` 编排，核心循环如下：

```mermaid
flowchart TB
    P1["blackbox-tester<br/>初始测试"] --> P2{有致命/严重缺陷?}
    P2 -->|是| P3["bug-fixer-from-tests<br/>修复"]
    P3 --> P4["syntax-checker<br/>语法复查"]
    P4 -->|有语法错误| P4
    P4 -->|通过| P5["performance-baseline-tester<br/>性能验证"]
    P5 --> P6["blackbox-tester<br/>回归测试"]
    P6 -->|回归通过率<95% 且循环≤5次| P2
    P6 -->|收敛| P7["final_report"]
    P2 -->|否| P7
```

---

## 第5章 编码与实现

### 5.1 总体实现情况

项目共实现 18 个技能（每个含 `SKILL.md` 与 `agents/openai.yaml`）、1 个安装脚本（`skills_linker.sh`）与 1 份 Markdown 规范配置（`.markdownlint.json`）。所有技能提示词均遵循统一的「角色描述 → 支持格式 → 工作模式 / 工作流程 → 行为准则 → 输出格式」结构，确保可被智能体稳定解析。

### 5.2 安装脚本 `skills_linker.sh` 的实现

安装脚本遍历分类目录，将各技能软链接至 `~/.agents/skills/`，并对已存在链接、同名冲突等情况进行安全处理。该脚本已通过 `shellcheck` 检查（0 告警）：

```bash
#!/bin/bash
# 技能链接脚本 - 将当前目录下分类中的技能链接到 ~/.agents/skills/
TARGET_DIR="$HOME/.agents/skills"

# 创建目标目录（如果不存在）
mkdir -p "$TARGET_DIR"

# 遍历所有一级子目录（分类目录）
for category_dir in */; do
    # 排除非目录项
    [ -d "$category_dir" ] || continue
    # 遍历分类目录下的技能子目录
    for skill_dir in "$category_dir"/*/; do
        [ -d "$skill_dir" ] || continue
        skill_name="${skill_dir%/}"
        skill_name="${skill_name##*/}"

        # 源技能目录的绝对路径
        src="$(realpath "$skill_dir")"

        # 目标链接路径
        link="$TARGET_DIR/$skill_name"

        # 目标已存在且不是指向当前源时，区分符号链接与普通目录处理
        if [ -L "$link" ]; then
            current_target="$(readlink "$link")"
            if [ "$current_target" = "$src" ]; then
                echo "跳过: $link 已指向 $src"
                continue
            else
                echo "警告: $link 存在但指向不同目标 ($current_target)，将替换"
                rm "$link"
            fi
        elif [ -e "$link" ]; then
            echo "警告: $link 存在且不是符号链接，跳过 (手动处理)"
            continue
        fi

        # 创建符号链接
        ln -s "$src" "$link"
        echo "已链接: $src -> $link"
    done
done

echo "完成。所有技能已链接到 $TARGET_DIR"
```

### 5.3 接口策略配置 `agents/openai.yaml`

以 `blackbox-tester` 为例，接口策略配置定义了展示信息与调用策略：

```yaml
interface:
  display_name: "黑盒测试专家"
  short_description: "从 README 提取信息并执行全面的黑盒测试（仅限测试环境），输出缺陷报告。"
policy:
  allow_implicit_invocation: false # 需用户明确要求测试
  require_confirmation: true # 在执行任何可能产生副作用的测试动作前需确认
  max_retries: 2 # 网络或环境问题可重试，但避免死循环
```

### 5.4 技能提示词 `SKILL.md` 的结构

以 `syntax-checker` 为例，`SKILL.md` 采用「角色描述 → 支持语言与工具 → 误报处理 → 执行步骤 → 报告格式」的结构化写法，并集成误报处理（忽略标签）规范：

```markdown
---
name: syntax-checker
description: 自动识别代码语言并调用对应的语法检查工具（如编译器、解释器或专用 linter），检测语法错误，输出结构化检查报告。
---

你是一名代码语法验证专家，专注于检测代码中的语法错误（Syntax Errors）...
```

### 5.5 Markdown 规范配置 `.markdownlint.json`

为抑制 Markdown 文档中系统性出现的纯风格规则噪音（行长、标题与围栏空行、首行标题），项目建立了统一规范配置：

```json
{
  "MD013": false,
  "MD022": false,
  "MD031": false,
  "MD041": false
}
```

---

## 第6章 系统测试

### 6.1 测试环境与工具

| 工具              | 版本                          | 用途                    |
| ----------------- | ----------------------------- | ----------------------- |
| shellcheck        | 0.11.0                        | Shell 语法与静态检查    |
| js-yaml           | 4.x                           | YAML 语法解析校验       |
| markdownlint-cli2 | 0.23.2（markdownlint 0.41.1） | Markdown 结构与规范检查 |
| prettier          | 3.3.3                         | Markdown 格式化         |
| jq / python3      | —                             | JSON / 辅助校验         |

### 6.2 语法检查

| 检查对象       | 工具                | 文件数 | 结果        |
| -------------- | ------------------- | ------ | ----------- |
| Shell 脚本     | `shellcheck`        | 1      | ✅ 0 问题   |
| Shell 语法基线 | `bash -n`           | 1      | ✅ 通过     |
| YAML 配置      | `js-yaml`           | 18     | ✅ 全部通过 |
| Markdown       | `markdownlint-cli2` | 19     | ✅ 0 issues |
| Markdown 格式  | `prettier --check`  | 19     | ✅ 全部合规 |

### 6.3 链接检查

对 `README.md`、`PROJECT_REPORT.md` 等文档中的外部链接进行可达性检查（HEAD 请求，405 时回退 GET，超时 5 秒，同域间隔 0.5 秒），结果如下：

| 链接                                                  | 状态码    | 结果                                     |
| ----------------------------------------------------- | --------- | ---------------------------------------- |
| `img.shields.io/*`（徽章）                            | 200       | ✅ 可达                                  |
| `shields.io`                                          | 200       | ✅ 可达                                  |
| `mermaid.js.org`                                      | 200       | ✅ 可达                                  |
| `github.com/Shuery-Shuai/AgentSkills.git`（代码块内） | 301 → 404 | ⚠️ 仓库尚未公开（已在 README 标注 TODO） |

### 6.4 测试结论

系统测试全部通过：Shell 与 YAML 无语法错误，Markdown 无规范问题且格式合规；文档外部链接除「未公开仓库的克隆地址」外均可达。测试过程全程只读，未对生产环境执行任何操作。

---

## 第7章 总结与展望

### 7.1 工作总结

本项目设计并实现了一套结构化的 AI 智能体技能集合 AgentSkills：

1. **体系化分类**：将 18 个技能按「开发与规范 → 测试与修复 → 交付与部署 → 全自动化」四层组织，形成完整质量闭环；
2. **统一规范**：每个技能由 `SKILL.md`（提示词）与 `agents/openai.yaml`（策略）组成，模板统一、易于扩展；
3. **可组合可编排**：通过技能互链与 `ci-cd-pipeline` / `auto-test-and-fix` 编排器，实现端到端自动化；
4. **安全可审计**：内置生产环境保护、脱敏、人工确认点等安全规则，并输出时间戳报告；
5. **质量保障**：经 shellcheck / js-yaml / markdownlint-cli2 / prettier / 死链检查全面验证，全部通过。

### 7.2 不足

1. 部分技能依赖第三方工具（如 `shellcheck`、`yamllint`、`markdownlint-cli2`），需要目标环境预先安装；
2. `release-orchestrator` 等技能仍在完善中，其与版本控制系统的深度集成有待增强；
3. 仓库尚未发布至 GitHub（克隆地址暂不可用），动态徽章（构建状态、覆盖率）有待接入 CI 后补充。

### 7.3 展望

未来可进一步：完善 `release-orchestrator` 的发布与回滚流程；补充 GitHub Actions 工作流以自动执行全量质量检查；增加更多语言与框架的技能模板；探索与主流 AI 编码工具（Claude Code、VS Code Copilot 等）的深度集成。

---

## 参考文献

1. GitHub Flavored Markdown Spec. <https://github.github.com/gfm/>
2. shields.io 徽章服务. <https://shields.io/>
3. Mermaid 图表. <https://mermaid.js.org/>
4. ShellCheck —— Shell 脚本静态分析工具. <https://www.shellcheck.net/>
5. markdownlint-cli2 —— Markdown 规范检查工具. <https://github.com/DavidAnson/markdownlint-cli2>
6. Prettier —— 代码格式化工具. <https://prettier.io/>

---

## 致谢

感谢所有为本技能集贡献思路、反馈与代码的开发者；感谢 shields.io、Mermaid、ShellCheck、markdownlint-cli2 与 Prettier 等优秀开源工具，为本项目的实现与质量保障提供了坚实支撑。

---

## 附录A 许可证清单

| 组件                  | 许可证 | 说明              |
| --------------------- | ------ | ----------------- |
| AgentSkills（本项目） | MIT    | 见 `LICENSE` 文件 |
| 第三方运行时依赖      | 无     | 依赖文件数 = 0    |

> [!WARNING]
>
> 本清单基于项目当前状态生成，仅供参考，不构成法律意见。若后续引入第三方依赖，请重新执行许可证合规检查。

## 附录B 检查执行摘要

| 检查项            | 工具                       | 结果                                  |
| ----------------- | -------------------------- | ------------------------------------- |
| 语法检查（Shell） | `shellcheck 0.11.0`        | ✅ 0 问题                             |
| 语法基线（Shell） | `bash -n`                  | ✅ 通过                               |
| YAML 解析         | `js-yaml@4`                | ✅ 18/18 通过                         |
| Markdown 规范     | `markdownlint-cli2 0.23.2` | ✅ 0 issues                           |
| Markdown 格式     | `prettier 3.3.3`           | ✅ 合规                               |
| 死链检查          | HEAD/GET 请求              | ✅ 无死链（1 处待公开仓库地址已标注） |
| 许可证合规        | 静态扫描                   | ✅ 完全合规（MIT，无依赖）            |