# AI智能体技能集合

`AI智能体` `技能工具` `开发工具` `自动化` `CLI`

# Aivokone 技能库（`ak-skills`）

基于开放 [skills 标准](https://skills.sh/) 的智能体技能集合。

本仓库托管运维工具、文档工作流和开发实践。每个技能均以独立目录形式存放于 `skills/<技能名>/`。

## 安装（skills.sh / npx skills）

```bash
# 将本仓库所有技能安装到当前项目
npx skills add aivokone/ak-skills
```

完整使用说明和安装详情，请参阅 [skills.sh 文档](https://skills.sh/docs)。

## 技能索引

下表为本仓库的规范技能索引。

| 名称 | 标识符 | 描述 |
|------|--------|------|
| [Seravo 开发者](skills/seravo-dev/) | `seravo-dev` | Seravo 托管 WordPress 运维：自定义 `wp-*` CLI、Git 部署、DDEV 本地环境、数据库同步、故障排查 |
| [Google Ads 查询](skills/google-ads-query/) | `google-ads-query` | 通过 GAQL 查询 Google Ads：广告系列、转化、关键词、广告效果、出价 |
| [GA4 查询](skills/ga4-query/) | `ga4-query` | 通过 Data API 查询 Google Analytics 4：流量、会话、页面浏览、实时数据、转化 |
| [智能体飞行记录仪](skills/agent-flight-recorder/) | `agent-flight-recorder` | 智能体运行的全程飞行记录仪：将偏差记录到每次运行的独立文件中 |
| [本地参考文档](skills/local-ref/) | `local-ref` | 将库文档缓存到本地，每次会话从磁盘读取而非重新拉取 |
| [PR 修复循环](skills/pr-fix-loop/) | `pr-fix-loop` | 系统化 PR 修复循环——检查所有反馈渠道、修复代码，循环直至完成 |
| [SwiftBar](skills/swiftbar/) | `swiftbar` | 为 macOS 创建、编辑和调试 SwiftBar 菜单栏插件 |
| [代码库导览](skills/codebase-guide/) | `codebase-guide` | 适合新手的代码库导览：项目目的、技术栈、架构、数据流、关键文件 |

## 智能体索引

从 `agents/` 目录自动发现的插件级子智能体。

| 名称 | 标识符 | 描述 |
|------|--------|------|
| [PR 审查员](agents/pr-reviewer.md) | `pr-reviewer` | 基于 Sonnet 的子智能体，负责完整的 PR 修复循环生命周期 |

## 技能目录

### Seravo 开发者（`seravo-dev`）

面向 Seravo 托管项目的 WordPress 运维指南，涵盖部署、本地环境搭建、数据库工作流以及 Seravo 专属事故响应。包含 IPv4 安全的 SSH 接入模式，以及以 DDEV 优先的本地工作流（用于 Seravo 主机访问和数据同步）。

主要知识来源为 Seravo 帮助中心和开发者文档，并为智能体使用整理了以 DDEV 优先、安全优先的实际操作模式。

来源文件：
- `skills/seravo-dev/SKILL.md`
- `skills/seravo-dev/references/seravo-guide.md`
- `skills/seravo-dev/references/seravo-to-local-to-github.md`

安装到项目范围：

```bash
npx skills add aivokone/ak-skills --skill seravo-dev
```

全局安装：

```bash
npx skills add aivokone/ak-skills --skill seravo-dev -g
```

### Google Ads 查询（`google-ads-query`）

面向 Google Ads 账户的只读 GAQL 查询工具。提供轻量级 Python CLI（`gads` 别名），通过标准输入管道（`echo "QUERY" | gads -`）执行 Google Ads 查询语言查询，返回结构化 JSON。涵盖广告系列效果、转化追踪审计、关键词分析、搜索词报告和广告组指标。包含枚举代码参考和常用报告任务的预置查询模式。

来源文件：
- `skills/google-ads-query/SKILL.md`
- `skills/google-ads-query/references/enums.md`
- `skills/google-ads-query/scripts/query.py`

安装到项目范围：

```bash
npx skills add aivokone/ak-skills --skill google-ads-query
```

全局安装：

```bash
npx skills add aivokone/ak-skills --skill google-ads-query -g
```

### GA4 查询（`ga4-query`）

基于子命令的 CLI，通过 Data API 查询 Google Analytics 4。支持标准报告（维度、指标、过滤器、日期范围、排序）、实时数据，以及管理命令（列出账户、属性详情、自定义维度和指标）。包含精选的维度和指标参考，以及用于复杂过滤逻辑的 `--json` 透传选项。

来源文件：
- `skills/ga4-query/SKILL.md`
- `skills/ga4-query/references/dimensions.md`
- `skills/ga4-query/references/metrics.md`
- `skills/ga4-query/scripts/query.py`

安装到项目范围：

```bash
npx skills add aivokone/ak-skills --skill ga4-query
```

全局安装：

```bash
npx skills add aivokone/ak-skills --skill ga4-query -g
```

### 智能体飞行记录仪（`agent-flight-recorder`）

智能体运行的纯记录型飞行日志器。仅记录偏离预期路径的情况（绕道、重试、环境意外、缺失上下文、阻塞、质量返工），写入每次运行的独立文件。

来源文件：
- `skills/agent-flight-recorder/SKILL.md`

运行输出：
- `.agents/flight-recorder/flight-YYYY-MM-DD-HHMMSS-TZ.md`
- 文件头部 schema：`flight-recorder/v2.5`
- 头部包含记录器元数据：`recorder_agent`（产品名）、`recorder_model`（精确模型 ID）、可选的 `recorder_effort` 和 `task`
- 运行尾部包含 `entries`、`high_severity`、`outcome`，便于快速扫描
- 条目包含 `at` 时间戳（带时区的 ISO-8601），用于排序和时长估算
- 默认 Git 规范：在 `.gitignore` 中忽略 `/.agents/flight-recorder/`（仅在有意版本化日志时才取消忽略）

安装到项目范围：

```bash
npx skills add aivokone/ak-skills --skill agent-flight-recorder
```

全局安装：

```bash
npx skills add aivokone/ak-skills --skill agent-flight-recorder -g
```

### 项目指令片段

如需在特定项目中强制使用，可在项目的智能体指令文件（如 `AGENTS.md`、`CLAUDE.md` 等）中添加以下简短说明：

```md
### 飞行记录仪（`agent-flight-recorder`）

- 对于长期或多步骤任务，如有 `agent-flight-recorder` 技能，请使用它。
- 如技能不可用，请手动在 `.agents/flight-recorder/` 下写入一个运行文件。
- 仅记录偏差：重试、绕道、缺失工具、阻塞性缺失上下文、假设和质量返工。
- 任务进行中不要提及日志。
- 任务完成时，若有条目被创建，请注明：`飞行记录仪：记录了 N 条条目。见 <路径>。`
```

### 本地参考文档（`local-ref`）

将库文档缓存到本地，使每次会话从磁盘读取而非从外部源重新拉取。支持 Context7 API、WebFetch 和手动来源。包含以下命令：初始化项目文档缓存（`local-ref init`）、本地优先查找文档（`local-ref lookup`）、更新缓存文档（`local-ref update`）、机会性保存已拉取文档（`local-ref save`）。

文档写入 `docs/reference/<主题>.md`——项目专属，每份 100-200 行，包含对实际项目文件的交叉引用。每个文件包含机器可读头部（`<!-- source="..." cached="..." -->`），支持可靠的自动更新。

来源文件：
- `skills/local-ref/SKILL.md`

安装到项目范围：

```bash
npx skills add aivokone/ak-skills --skill local-ref
```

全局安装：

```bash
npx skills add aivokone/ak-skills --skill local-ref -g
```

### PR 修复循环（`pr-fix-loop`）

系统化的 PR 修复循环，检查所有渠道（对话、行内、评审）的反馈，修复代码，发布修复报告，并循环直至无新反馈。在无反馈时自动调用审查智能体。

包含辅助脚本（相对于技能目录）：

- `scripts/get-context.sh` — 当前分支、PR、变更、时间戳（状态检测入口）
- `scripts/open-branch.sh` — 确保工作树在非主分支上（幂等）
- `scripts/check-pr-feedback.sh` — 检查 PR 的所有三个反馈渠道
- `scripts/reply-to-inline.sh` — 在线程中回复行内评论
- `scripts/post-fix-report.sh` — 将修复报告发布为 PR 对话评论（支持文件路径或标准输入）
- `scripts/invoke-review-agents.sh` — 通过单条合并评论触发审查智能体（`--format-only` 用于嵌入 PR 正文）
- `scripts/create-pr.sh` — 幂等 PR 创建，含分支安全保护（`--invoke` 嵌入智能体触发器，输出 `CREATED:`/`EXISTS:`）
- `scripts/commit-and-push.sh` — 暂存、提交并推送，含分支安全保护
- `scripts/wait-for-reviews.sh` — 调用智能体后轮询新反馈
- `scripts/check-new-feedback.sh` — 差异化反馈检查（仅检查指定时间戳之后的新条目）

来源文件：
- `skills/pr-fix-loop/SKILL.md`

安装到项目范围：

```bash
npx skills add aivokone/ak-skills --skill pr-fix-loop
```

全局安装：

```bash
npx skills add aivokone/ak-skills --skill pr-fix-loop -g
```

### 项目指令片段

如需在特定项目中强制使用，可在项目的智能体指令文件（如 `AGENTS.md`、`CLAUDE.md` 等）中添加以下简短说明：

```md
### PR 修复循环（`pr-fix-loop`）

- 调用 `/pr-fix-loop` 对 PR 执行完整的审查-修复-审查循环。
- 检查所有三个反馈渠道（对话、行内、评审），循环直至无新反馈。
```

### SwiftBar（`swiftbar`）

为 macOS 创建、编辑和调试 SwiftBar 菜单栏插件。涵盖完整的 SwiftBar/BitBar 输出协议、插件命名规范、元数据格式、SF Symbols、流式插件和常用模式。支持 bash 和 Python 插件。包含诊断损坏插件的调试工作流。

来源文件：
- `skills/swiftbar/SKILL.md`
- `skills/swiftbar/references/patterns.md`

安装到项目范围：

```bash
npx skills add aivokone/ak-skills --skill swiftbar
```

全局安装：

```bash
npx skills add aivokone/ak-skills --skill swiftbar -g
```

### 代码库导览（`codebase-guide`）

生成适合新手阅读的 Markdown 代码库导览文档。输出单份文档，涵盖项目目的、技术栈、架构（含 Mermaid 图表）、数据流、关键文件及运行方法。根据项目规模自动调整深度——从小型 CLI 到大型 Monorepo 均适用。

来源文件：
- `skills/codebase-guide/SKILL.md`
- `skills/codebase-guide/references/output-template.md`
- `skills/codebase-guide/references/writing-rules.md`

安装到项目范围：

```bash
npx skills add aivokone/ak-skills --skill codebase-guide
```

全局安装：

```bash
npx skills add aivokone/ak-skills --skill codebase-guide -g
```

## 智能体目录

### PR 审查员（`pr-reviewer`）

基于 Sonnet 的子智能体，处理完整的 PR 修复循环生命周期。将所有 PR 工作流操作委托给隔离上下文：检查所有渠道的反馈、修复代码、提交、发布修复报告，并循环直至完成。自动预加载 `pr-fix-loop` 技能。

来源文件：
- `agents/pr-reviewer.md`

## 贡献 / 添加技能

本仓库遵循渐进式披露模式：保持 `SKILL.md` 精简，将详细流程放在 `references/` 目录下。

规范：不在 `skills/<技能名>/` 下添加 `README.md`；将智能体必要行为保留在 `SKILL.md` 中，将面向用户的目录详情保留在根目录 `README.md` 中。

添加新技能或对现有技能进行重大更新时，请同步更新：
- `README.md`（技能索引和对应技能的技能目录部分）
- `.claude-plugin/plugin.json`（插件清单）

贡献者规范详见 `AGENTS.md`。