276 lines
11 KiB
Markdown
276 lines
11 KiB
Markdown
# 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`。 |