# 🧩 AgentSkills — AI 智能体技能集

> 一套面向 AI 编码智能体（Agent）的开源技能（Skills）集合，覆盖 **开发规范、测试修复、交付部署与全自动化** 四大领域。每个技能由 `SKILL.md`（提示词）与 `agents/openai.yaml`（接口与策略）组成，开箱即用、可自由组合，帮你把 AI 从「问答助手」升级为「质量工程团队」。

![Skills](https://img.shields.io/badge/Skills-16-blue)
![Categories](https://img.shields.io/badge/Categories-4-42b883)
![Format](https://img.shields.io/badge/Format-Markdown%20%2B%20YAML%20%2B%20Bash-1f425f)
![License](https://img.shields.io/badge/License-MIT-blue)
![PRs](https://img.shields.io/badge/PRs-Welcome-brightgreen)

---

## 📋 目录

<!-- markdownlint-disable MD051 -->

- [✨ 特性](#-特性)
- [🗂️ 项目结构](#-项目结构)
- [🚀 快速开始](#-快速开始)
- [📦 技能清单](#-技能清单)
- [🛠️ 配置说明](#-配置说明)
- [🏗️ 架构设计](#-架构设计)
- [🔗 技能互链](#-技能互链)
- [🤝 贡献指南](#-贡献指南)
- [📄 许可证](#-许可证)
- [🙏 致谢](#-致谢)
<!-- markdownlint-enable MD051 -->

---

## ✨ 特性

- 🧩 **开箱即用**：每个技能自带完整提示词（`SKILL.md`）与接口策略（`agents/openai.yaml`），复制即用、无需额外依赖。
- 🗂️ **分层分类**：按「开发与规范 → 测试与修复 → 交付与部署 → 全自动化」四层递进组织，形成完整质量闭环。
- 🔗 **技能互链**：技能之间通过 `/技能名` 相互调用（如 `ci-cd-pipeline` 可串联 13 个子技能），可组装成自动化流水线。
- 🚀 **一键安装**：`skills_linker.sh` 将分类目录下全部技能软链接到 `~/.agents/skills/`，全局可用。
- 📊 **可观测可审计**：每个技能输出带时间戳的结构化 Markdown 报告（`*_<timestamp>.md`），全程留痕、便于审计。
- 🛡️ **安全优先**：内置强制安全规则——生产环境保护、敏感信息脱敏、最小权限、人工确认点。

---

## 🗂️ 项目结构

```text
AgentSkills/
├── skills_linker.sh                  # 一键安装脚本（软链接到 ~/.agents/skills/）
├── README.md                         # 项目说明（本文件）
├── development-and-standards/        # ① 开发与规范（6 个技能）
│   ├── readme-generator/             #     README 生成器
│   ├── academic-readme-writer/       #     论文格式项目报告
│   ├── google-style-formatter/       #     Google 风格代码格式化
│   ├── syntax-checker/               #     语法检查
│   ├── dependency-security-scanner/  #     依赖安全扫描（CVE）
│   └── doc-link-checker/             #     文档死链检查
├── testing-and-fixing/               # ② 测试与修复（5 个技能）
│   ├── blackbox-tester/              #     黑盒测试
│   ├── unit-test-generator/          #     单元测试生成
│   ├── bug-fixer-from-tests/         #     缺陷修复
│   ├── performance-baseline-tester/  #     性能基线测试
│   └── auto-test-and-fix/            #     测试-修复闭环编排
├── delivery-and-deployment/          # ③ 交付与部署（4 个技能）
│   ├── db-migration-checker/         #     数据库迁移检查
│   ├── deploy-to-production/         #     生产部署
│   ├── license-compliance-checker/   #     许可证合规检查
│   └── log-monitor-rule-generator/   #     日志监控规则生成
└── full-automation/                  # ④ 全自动化（3 个技能）
    ├── ci-cd-pipeline/               #     CI/CD 全自动流水线
    ├── project-health-check/         #     项目健康度检查
    └── release-orchestrator/         #     发布编排（🚧 待完善）
```

### 单个技能的目录结构

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

---

## 🚀 快速开始

### 1️⃣ 克隆仓库

<!-- TODO: 仓库公开后请核对下方地址；当前仓库尚未发布（访问返回 404），也可直接使用本地目录 -->

```shell
git clone https://github.com/Shuery-Shuai/AgentSkills.git
cd AgentSkills
```

> [!NOTE]
>
> 当前仓库尚未发布到 GitHub（克隆地址暂不可用），可先将本地目录直接作为技能根目录使用，待仓库公开后此命令即可生效。

### 2️⃣ 一键安装全部技能

在仓库根目录执行：

```shell
chmod +x skills_linker.sh
./skills_linker.sh
```

脚本会把所有分类下的技能目录软链接到 `~/.agents/skills/`：

```console
已链接: /path/to/AgentSkills/readme-generator -> /home/xxx/.agents/skills/readme-generator
完成。所有技能已链接到 /home/xxx/.agents/skills
```

> [!NOTE]
>
> `skills_linker.sh` 会跳过指向不同目标的同名已存在链接（打印警告），不会覆盖非符号链接目录，可安全重复执行。

### 3️⃣ 在 Agent 中调用

在支持 Skills 的 AI 编码工具（如 Claude Code、VS Code Copilot Chat 等）中，直接以技能名唤起即可，例如 `/blackbox-tester`、`/ci-cd-pipeline`。

---

## 📦 技能清单

### ① 开发与规范 `development-and-standards/`

| 技能                          | 说明                                                                  |
| ----------------------------- | --------------------------------------------------------------------- |
| `readme-generator`            | 遍历项目生成开源风格 README，含徽章、Mermaid、GitHub 提示块与死链检查 |
| `academic-readme-writer`      | 生成论文格式的 `PROJECT_REPORT.md`，集成格式化、死链检查与许可证信息  |
| `google-style-formatter`      | 将代码重构为严格 Google 风格，补全注释并调用权威格式化工具            |
| `syntax-checker`              | 自动识别语言并调用编译器 / linter 做语法检查，输出结构化报告          |
| `dependency-security-scanner` | 扫描依赖已知漏洞（CVE），输出风险报告与修复优先级                     |
| `doc-link-checker`            | 检查 Markdown 文档所有外部链接可达性，标记死链并生成报告              |

### ② 测试与修复 `testing-and-fixing/`

| 技能                          | 说明                                                           |
| ----------------------------- | -------------------------------------------------------------- |
| `blackbox-tester`             | 黑盒测试专家：环境确认 → 用例生成 → 缺陷报告（仅限测试服务器） |
| `unit-test-generator`         | 分析源码自动生成缺失单元测试，覆盖正常 / 边界 / 异常场景       |
| `bug-fixer-from-tests`        | 解析缺陷报告 → 定位根因 → 最小化修复 → 回归验证指引            |
| `performance-baseline-tester` | 对核心 API 做性能基准测试（k6），与历史基线对比识别退化        |
| `auto-test-and-fix`           | 端到端编排「测试→修复→语法检查→性能→回归」闭环，直至缺陷清零   |

### ③ 交付与部署 `delivery-and-deployment/`

| 技能                         | 说明                                                      |
| ---------------------------- | --------------------------------------------------------- |
| `db-migration-checker`       | 分析迁移脚本风险（危险操作 / 锁表），支持预发环境模拟执行 |
| `deploy-to-production`       | 多重确认下部署生产，集成迁移审查、健康检查与监控规则生成  |
| `license-compliance-checker` | 扫描依赖开源许可证，检查与主许可证的兼容性与冲突          |
| `log-monitor-rule-generator` | 扫描日志输出，生成 ELK / Loki / Prometheus 监控与告警规则 |

### ④ 全自动化 `full-automation/`

| 技能                   | 说明                                                                         |
| ---------------------- | ---------------------------------------------------------------------------- |
| `ci-cd-pipeline`       | 串联 13 个子技能的全自动 CI/CD 闭环：安全→测试→修复→格式化→文档→部署→监控    |
| `project-health-check` | 全量质量体检（安全 / 语法 / 测试 / 性能 / 文档 / 合规），输出 0-100 综合评分 |
| `release-orchestrator` | 发布编排（🚧 内容待完善）                                                    |

> [!TIP]
>
> `ci-cd-pipeline` 是「总指挥」：它按阶段依次调用安全扫描、黑盒测试、缺陷修复、格式化、文档生成、迁移审查与生产部署，任一阶段失败即暂停并报告。

---

## 🛠️ 配置说明

每个技能由两部分组成，均可按需定制：

| 文件                 | 作用                                                   | 示例字段                                                           |
| -------------------- | ------------------------------------------------------ | ------------------------------------------------------------------ |
| `SKILL.md`           | 技能的完整提示词，定义角色、工作流、行为准则与输出格式 | 角色描述、阶段流程、报告模板                                       |
| `agents/openai.yaml` | 接口与策略配置                                         | `display_name`、`short_description`、`policy.require_confirmation` |

示例 `agents/openai.yaml`：

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

> [!WARNING]
>
> 多数技能内置 `require_confirmation: true` 与「生产环境保护」规则。凡涉及数据库写入、部署或副作用操作，务必先确认目标环境为测试 / 预发环境。

---

## 🏗️ 架构设计

```mermaid
flowchart TB
    subgraph SK["🧩 AgentSkills"]
        A["🛠️ 开发与规范<br/>readme-generator · syntax-checker<br/>google-style-formatter · ..."]
        B["🧪 测试与修复<br/>blackbox-tester · unit-test-generator<br/>bug-fixer-from-tests · ..."]
        C["🚀 交付与部署<br/>db-migration-checker · deploy-to-production<br/>license-compliance-checker · ..."]
        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
```

数据流 / 调用链示意（以 CI/CD 流水线为例）：

```mermaid
flowchart LR
    S1["依赖安全扫描"] --> S2["许可证合规"]
    S2 --> S3["语法检查"]
    S3 --> S4["黑盒测试"]
    S4 -->|有缺陷| S5["缺陷修复"]
    S5 --> S4
    S4 -->|通过| S6["格式化 + 语法复查"]
    S6 --> S7["文档生成 + 死链检查"]
    S7 --> S8["数据库迁移审查"]
    S8 --> S9["生产部署"]
    S9 --> S10["监控规则生成"]
```

---

## 🔗 技能互链

技能之间通过 `/技能名` 相互调用，形成可复用的自动化链路。典型组合：

- **全流程发布**：`/ci-cd-pipeline` 一键串联安全 → 测试 → 修复 → 部署 → 监控。
- **文档质量保障**：`/readme-generator` 生成 → `/doc-link-checker` 校验 → `/google-style-formatter` 规范化代码片段。
- **测试闭环**：`/blackbox-tester` 发现缺陷 → `/bug-fixer-from-tests` 修复 → `/syntax-checker` 复查 → `/auto-test-and-fix` 回归。

---

## 🤝 贡献指南

欢迎通过 Issue / PR 贡献新技能或改进现有技能。建议遵循以下规范：

1. 每个技能放在对应分类目录下，包含 `SKILL.md` 与 `agents/openai.yaml`。
2. `SKILL.md` 至少包含：角色与描述、工作流程、行为准则、输出格式。
3. 涉及破坏性或副作用操作的技能，务必在 `openai.yaml` 中设置 `require_confirmation: true`。
4. 新增技能后，可运行 `./skills_linker.sh` 验证安装脚本兼容性。

<!-- TODO: 补充 CONTRIBUTING.md 与具体的贡献模板 -->

---

## 📄 许可证

本项目基于 [MIT License](LICENSE) 开源（Copyright © 2026 Shuery-Shuai）。详见 [LICENSE](LICENSE) 文件。

---

## 🙏 致谢

- 感谢所有为本技能集贡献思路与反馈的开发者。
- 感谢 [shields.io](https://shields.io) 提供徽章服务，[Mermaid](https://mermaid.js.org) 提供图表渲染。