agent-skill-pack
5 个零依赖、只读、可跨平台的 Agent Skills。一套 SKILL.md,WorkBuddy / Codex / DeepSeek Harness 同时可用。
写一次,三个宿主都能装;每个 skill 目录也能单独复制走。所有脚本只用 Python 标准库,不联网、不执行项目代码、不需要 API key。
为什么是 1 个仓库:三平台的适配层(安装器、function schema、AGENTS.md、CI)只需要写一份、测一次。拆成 5 个十来个文件的小仓库,只会得到 5 份重复的适配代码。
5 个方向
| Skill | 什么时候触发 | 它替你做什么 | 和已有工具的区别 |
|---|---|---|---|
| repo-brief | 接手陌生仓库 / 「这项目怎么跑」 | 生成项目档案:技术栈、真实可跑命令、入口点、目录职责、环境变量契约、动手前要确认的风险 | tree 和 README 是给人看的;它输出的是给 agent 直接消费的上下文,并指出「别假设 npm test 可用」这类坑 |
| diff-guard | 提交 / push / 开 PR / 说「检查都过了」之前 | 只看新增行,抓凭证、破坏性命令、调试残留、被 skip 的测试、锁文件不同步、DB 迁移 | gitleaks 扫全历史、要装二进制;它扫当前 diff、零配置、按严重度给可执行待办,且从不打印完整密钥 |
| data-probe | CSV/TSV/JSONL 要分析、拼接、入库之前 | 编码、逐列类型、缺失、distinct、重复行、离群、前后空格、疑似 PII、跨文件 schema 漂移 | pandas-profiling 生成上百 MB HTML 还要装一堆依赖;它流式读、输出精简 JSON,且不输出 PII 原值 |
| api-diff | 两版 OpenAPI 要判兼容性 / 发版前 | 找出 breaking changes,给迁移建议和 changelog 片段 | oasdiff 输出机器日志;它输出给人和 agent 看的改动清单,JSON / 常见 YAML 都能读,不需要 PyYAML |
| log-triage | 一坨日志 / 堆栈 / CI 失败输出要解释 | 归一化时间戳、ID、数字,聚成错误签名,给时间线突增和排查顺序 | `grep ERROR |
全部输出 --format md(给人)或 --format json(给 agent / CI),支持 --strict 当门禁。
30 秒安装
git clone https://github.com/Zephyr-Song/agent-skill-pack
cd agent-skill-pack
python install.py # 一次装到三个宿主
python install.py --dry-run # 先看会装到哪,不改文件
python install.py --list # 查看各宿主路径
| 宿主 | 安装路径 | 调用方式 |
|---|---|---|
| WorkBuddy | ~/.workbuddy/skills/<name>/ |
自然语言描述任务,按 description 自动匹配 |
| Codex CLI | ~/.agents/skills/<name>/ |
$repo-brief / /skills,也可隐式匹配 |
| DeepSeek Harness | <project>/.agents/skills/<name>/ |
标准 skill 发现路径(upstream 仓库自身就用这个布局) |
只装某几个:python install.py --skills repo-brief,diff-guard --target codex
卸载:python install.py --uninstall(只删本脚本自己装过的目录,靠 .agent-skill-pack-installed.json 标记识别)
不想装也能直接用,每个 CLI 都是独立的:
python skills/repo-brief/scripts/brief.py /path/to/repo --format md
git diff --cached | python skills/diff-guard/scripts/guard.py --stdin --strict
python skills/data-probe/scripts/probe.py users.csv --format json
python skills/api-diff/scripts/apidiff.py v1.yaml v2.yaml --strict
python skills/log-triage/scripts/triage.py app.log.gz --top 8
真实输出长什么样
以下摘自 examples/ 的真实输出,输入文件也在该目录,可原样复跑。
diff-guard 对 examples/sample.diff:
来源:`file:sample.diff` · 4 个文件 · 8 行新增 · 🔴 1 / 🟡 5 / ⚪ 1
## 🔴 HIGH
- **[SEC-001] 疑似真实凭证** · `src/config.ts:1`
- 证据:`AKIA************2M`(pattern=AWS_AKID)
- 建议:确认不是密钥后再提交;如是真密钥,先轮换再清理历史
## 🟡 MED
- **[HYG-006] 数据库迁移 / schema 改动** · `db/migrations/0042_add_col.sql`
- **[HYG-003] 依赖声明与锁文件不同步** · `package.json`
- **[HYG-001] 破坏性命令** · `scripts/deploy.sh:1` — `rm -rf /var/cache/app`
log-triage 把 41 行日志(时间戳/UUID/耗时都不同)压成 2 个签名:
扫描 41 行 · 归并成 2 个错误签名 · 展示前 2 个
| # | 次数 | 级别 | 首次 | 签名 |
| 1 | 40 | error:40 | 2026-11-07T10:00:12Z | `<TS> <LVL> user <UUID> request <N> failed after <NUM> token=<REDACTED>` |
| 2 | 1 | error:1 | 2026-11-07T10:31:00Z | `<TS> <LVL> RareFailure File "<FILE>", line <N>, in handle` |
设计原则
- 脚本管形式,模型管判断。 解析、计数、正则、格式化交给脚本;「这条发现在此刻要不要紧」交给模型。脚本不假装能评估学术/业务价值。
- 零依赖。 只用 Python 3.10+ 标准库。没有
pip install这一步,也就没有供应链和环境地狱。 - 只读、可逆。 除
install.py外所有 CLI 不改任何文件,不执行项目代码,不联网,不需要 API key。 - 静默失败比误报更危险。 每个规则都有真阳性和假阳性回归测试;无法解析的输入直接报错退出,绝不「假装读成功然后给结论」。
- 不泄漏。 凭证一律脱敏,疑似 PII 只给命中计数、不给样本值;日志里的
token=...会被替换成<REDACTED>。 - 路径跨平台一致。 输出统一用
/,Windows 上不会冒出\。 - 每个 skill 自包含。 可以只把
skills/repo-brief/复制进任何宿主,不依赖仓库其它目录。 - Windows 传统 codepage 下也不崩。 所有 CLI 启动时把 stdout/stderr 强制成 UTF-8;
cp1252/charmap环境下中文报告不会UnicodeEncodeError,有专门的回归测试锁住。
目录结构
agent-skill-pack/
├── SKILL 适配层
│ ├── install.py 三平台安装 / 卸载 / dry-run
│ ├── tools.json 5 个 OpenAI-compatible function schema + CLI 映射
│ ├── AGENTS.md Codex / 通用 agent 的仓库级指令
│ └── .github/workflows/ci.yml
├── skills/
│ ├── repo-brief/ SKILL.md · scripts/ · references/ · tests/ · README.md
│ ├── diff-guard/
│ ├── data-probe/
│ ├── api-diff/
│ └── log-triage/
├── examples/ 可直接查看的真实输出
└── tests/test_pack.py 跨平台契约 + 汇总测试
验证
python tests/test_pack.py -v # 41 个功能测试 + 11 项跨平台契约检查
CI 在 ubuntu / windows × Python 3.10 / 3.12 四个组合上跑同一套测试。
FAQ / 边界
DeepSeek Harness 是 Cordis 插件架构,这算原生插件吗?
不是 Cordis bundle,这一点要说清楚。DSH 官方仓库自己就用 .agents/skills/<name>/SKILL.md 承载了 23 个内建工作流(例如 dsh-pre-push-checks),所以 skill 是它的一等扩展方式。本仓库采用这条标准路径;同时 tools.json 提供 function-calling schema,方便把 5 个 CLI 注册成工具给任何 OpenAI-compatible harness(含 DeepSeek API)调用。如果你要的是能改 UI、加面板的 Cordis bundle,那是另一类插件,不在本仓库范围内。
api-diff 支持所有 YAML 吗?
不支持。内置一个明确定义的最小 YAML 子集解析器:缩进映射、- item 列表、列表里的映射、块标量、基本标量。不支持 anchors/aliases/merge key/多文档流。遇到看不懂的结构会保留为字符串而不是悄悄改坏;复杂 spec 请先转成 JSON。这个限制写在 references/ 里,也有测试覆盖。
会不会误报?
会,所以每条规则都带 --min-severity 过滤和 hint。凭证检测主动排除 example / your_ / <...> / ${...} 等占位符;锁文件改动不会被当成「手改生成物」。但启发式终究是启发式——把它当闸门提醒,不是安全审计结论。
能替代 gitleaks / great_expectations / oasdiff 吗? 不能,也不打算。那些是成熟的全功能工具。本仓库解决的是另一个问题:在 agent 工作流里,用零依赖的确定性脚本,把刚好够用的结构化上下文交给模型。需要合规级扫描时,请用专业工具。
MIT License · 作者 Zephyr-Song
No comments yet. Be the first to write one.