# AI智能体技能集合

`AI智能体` `技能工具` `开发工具` `WordPress` `Google Ads` `GA4` `PR管理` `macOS`

# Aivokone 技能集 (`ak-skills`)

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

本仓库托管运维工具、文档工作流和开发实践。每个技能以独立单元存放于 `skills/<skill-name>/`。

## 安装（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 帮助中心和 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` 别名），通过 stdin 管道（`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`
- 文件头格式：`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/<topic>.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 对话评论发布（文件路径或 stdin）
- `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/<skill-name>/README.md`；在 `SKILL.md` 中保存智能体必要行为，在根目录 `README.md` 中保存面向用户的目录详情。

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

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