huangwb8/skills

Bensz Agent Skills 项目把 Skill 的创建、测试、文档、安装与发布连成可复用的工程流程；更进一步，执行内核bensz-skill-kernel（简称BSK）尝试回答：当 Skill 成为 Agent 系统的长期组成部分时，该用的时候它用上了吗？该做的步骤漏掉了吗？改动之后变差了吗？出错时，能查到是哪一步吗？

项目在做什么

项目由三部分组成：

• 可直接使用的通用 Skills：覆盖自动测试、多 Agent 协作、并行工作区、Prompt 优化、科研绘图、Git 操作、安装、文档和缺陷反馈。
• Skills 开发与维护流水线：用统一约定串起开发 → 测试 → 文档化 → 安装 → 使用 → 反馈 → 迭代。
• Skill 执行与检查工具：bensz-skill-kernel 正在提供任务阶段管理、自动检查、工作区、证据记录、事件账本、审计和执行记录重放。

这些工具不试图把 Skill 变成传统程序，而是让复杂 Agent 工作流中的关键阶段、检查和证据更明确、更容易追踪。

为什么做这个项目

当 Skill 数量和流程复杂度增长，仅靠更长的 SKILL.md 很难回答：Skill 是否正确触发、是否遗漏步骤、修改后是否退化、协作过程是否可追踪、结果经过了哪些检查，以及失败发生在哪里。本项目因此尝试把关注点从“编写单个 Skill”推进到更完整的 系统化建设 Skill。

设计原则

• 开放标准优先，尽量不绑定单一平台。
• Skill 与通用工具分离：具体工作流程留在 Skill，通用的执行、检查和记录功能放在 Kernel。
• 显式状态优于隐式猜测，检查优于默认信任，可重放优于不可追踪。
• 渐进增强：普通 Skill 保持简单，仅在需要时使用更强的执行和检查功能。

30 秒开始

无需克隆仓库即可安装 skills/alpha 中的生产 Skill（需要 Python 3.8+ 与网络）：

python3 -c "import urllib.request; exec(urllib.request.urlopen('https://raw.githubusercontent.com/huangwb8/skills/main/skills/alpha/install-bensz-skills/scripts/bootstrap_install.py').read())" --source general

已克隆仓库、需要本地开发时：

python3 skills/alpha/install-bensz-skills/scripts/install.py --codex

安装器默认把 Skill 复制到 ~/.codex/skills/ 和 ~/.claude/skills/；只安装某个 Skill 可追加 --skill git-commit。skills/beta/ 仅在显式传入 --source 时处理。

这个仓库提供什么

• 可直接安装的 Skill：位于 skills/alpha/，每个目录都有面向使用者的 README.md 和面向 AI 的 SKILL.md。
• 开发流水线：覆盖初始化、Prompt 优化、文档生成、批判性测试、多代理协作、Git 发布和缺陷反馈。
• 任务执行内核：packages/bensz-skill-kernel/ 提供 bsk CLI，用来管理任务阶段、执行检查、保存证据、记录事件，并重放执行记录。
• 可审计协作：任务过程材料进入 .bensz-api/，贡献记录进入 docs/contribution.bac。

Skill 导航

当前 skills/alpha/ 包含 16 个生产 Skill：

选择 Skill 后，阅读对应目录的 README.md 获取触发方式、最小 Prompt、输入输出和 FAQ；维护者同时阅读 SKILL.md、config.yaml 与 CHANGELOG.md。

当然，我觉得最好的方式是：在你的Codex/Claude Code里把本项目的地址粘贴上，然后开始用ai来探索它！

安装方式

远程引导安装

bootstrap_install.py 只依赖 Python 标准库，最低 Python 3.8；它是仓库唯一兼容 Python 3.8、3.9 和 3.10 的首次/应急入口，该兼容范围不代表本地完整安装器或 Kernel 支持这些版本。默认远程源由 skills/alpha/install-bensz-skills/config.yaml 定义：

常用参数：

# 预览，不写入文件
python3 -c "import urllib.request; exec(urllib.request.urlopen('https://raw.githubusercontent.com/huangwb8/skills/main/skills/alpha/install-bensz-skills/scripts/bootstrap_install.py').read())" --check

# 只安装到 Codex 或 Claude Code
python3 -c "import urllib.request; exec(urllib.request.urlopen('https://raw.githubusercontent.com/huangwb8/skills/main/skills/alpha/install-bensz-skills/scripts/bootstrap_install.py').read())" --codex
python3 -c "import urllib.request; exec(urllib.request.urlopen('https://raw.githubusercontent.com/huangwb8/skills/main/skills/alpha/install-bensz-skills/scripts/bootstrap_install.py').read())" --claude

# 创建或更新统一的 benszapi Conda 运行时与 BSK
python3 -c "import urllib.request; exec(urllib.request.urlopen('https://raw.githubusercontent.com/huangwb8/skills/main/skills/alpha/install-bensz-skills/scripts/bootstrap_install.py').read())" --ensure-runtime

本地安装与开发

本地完整安装器与仓库标准开发环境统一使用 Python 3.11+，支持 --source、--skill、--force 和 --legacy-source 等参数：

git clone https://github.com/huangwb8/skills.git
cd skills
python3 skills/alpha/install-bensz-skills/scripts/install.py
python3 skills/alpha/install-bensz-skills/scripts/install.py --skill write-readme

安装记录、MD5 清单和远程缓存位于用户目录的 ~/.bensz-skills/installation/；安装器不会把 beta Skill 混入默认源。

更新已安装的技能

本地安装器提供静默增量更新入口：--silent-update 在 72 小时 TTL 到期后维护统一的 benszapi Conda 运行时并更新已安装技能，不能与安装/检查/筛选参数组合使用。远程安装可改用快速版本检查脚本：它并发读取远端版本，仅在远程版本更高或本地缺失时才调用远程安装器，支持 --check-only、--skill、--source-contains 等参数。

# 静默增量更新（TTL 到期后执行）
python3 skills/alpha/install-bensz-skills/scripts/install.py --silent-update

# 显式创建或更新托管运行时；只读检查可改用 --runtime-status
python3 skills/alpha/install-bensz-skills/scripts/install.py --ensure-runtime

# 只检查远程版本差异，不安装
python3 skills/alpha/install-bensz-skills/scripts/update_remote_skills.py --check-only

Kernel

bensz-skill-kernel 当前发布版本为 2.1.6，要求 Python 3.11+，运行所需的依赖只有 PyYAML 和 Python 标准库。普通使用由安装器托管在 ~/.bensz-skills/envs/benszapi，并通过 ~/.bensz-skills/bin/bsk 固定入口调用，不依赖项目 Python、PATH 中的其它 bsk 或 conda activate。

它提供 bsk 命令，帮助你管理任务阶段与分层运行身份、授权阶段内动作、执行检查、保存证据和重放执行记录。普通使用者可以直接使用上面的命令；内部的 State、Verifier、Workspace 等概念主要面向维护者，详细说明见 docs/state-id-naming.md、docs/verifier-id-naming.md、docs/state-identity-protocol.md 与 packages/bensz-skill-kernel/README.md。

2.1.4 新增业务证据哈希与引用绑定；2.1.5 让 bsk state transition 显式消费 source Gate，并提供 Gate/result/transition 的只读绑定查询；2.1.6 让原子 workspace initialize 的首个 State identity 可直接进入声明的领域初始 State。历史无绑定事件仍可读取，但不会获得严格完成资格。

源码开发仍使用仓库自己的隔离环境：

python3 -m venv .bensz-api/.venv
.bensz-api/.venv/bin/python -m pip install -e packages/bensz-skill-kernel
.bensz-api/.venv/bin/bsk --version
.bensz-api/.venv/bin/bsk verifier list

常用入口：

BSK="$HOME/.bensz-skills/bin/bsk"
"$BSK" capabilities
"$BSK" state list
"$BSK" verifier list --tag citation
"$BSK" workspace init . --description citation-review
"$BSK" workspace status .bensz-api/task-YYYYMMDD-HHMM-citation-review

目录与工作区

skills/alpha/                  # 可发布、默认安装的 Skill
skills/beta/                   # 候选 Skill，必须显式指定源
packages/bensz-skill-kernel/   # 独立 Python 内核包
docs/                          # 现行文档、教程与设计记录
tests/                         # 仓库公开入口与跨包测试
tmp/                           # 测试报告和临时产物
.bensz-api/                    # AI 任务工作区与工具缓存

每个需要落盘的逻辑任务使用一个 .bensz-api/task-{yyyymmdd-hhmm}-{描述}/；正式 README、源代码和计划仍写入项目约定目录，不放入隐藏工作区。

开发与验证

# 根级测试（缓存写入 .bensz-api）
python3 -m pytest

# 检查中英文 README 标题、代码块、链接和命令 token 是否对齐
python3 skills/alpha/write-readme/scripts/check_readme_pair.py README.md README_EN.md

# 报告所有 alpha/beta Skill 的正文规范缺项；迁移后的 Skill 可加 --mode strict
python3 tests/check_skill_structure.py --mode report

# 查看 BAC 贡献账本
bac --root . --bac-file docs/contribution.bac inspect

修改 Skill 时保持 SKILL.md、config.yaml、README 和 CHANGELOG 同步；重要仓库变更先记录到 CHANGELOG.md 的 [Unreleased]。

兼容性与边界

• Agent Skills 文件格式遵循开放标准；实际触发能力取决于宿主对 Skill 目录的支持。
• 仓库开发、本地完整安装器和 Kernel 统一要求 Python 3.11+；仅远程 bootstrap 为首次/应急安装保留 Python 3.8+ 兼容。
• Kernel 的进程级超时、输入输出限制和 fail-closed 选项不是容器或操作系统沙箱；不可信代码仍应在独立环境运行。
• 远程安装需要访问 GitHub；网络失败时可改用本地安装器或已有缓存，并检查安装退出码。

贡献与许可证

请先阅读 AGENTS.md 和 CLAUDE.md。本项目暂不接受未经沟通的普通 PR；如需贡献，请先联系 huangwb8。

项目采用 MIT License，见 LICENSE。

更多入口

下面这些入口分别介绍版本变化、结果检查、任务阶段和 Skill 安装；按你的目标选择即可。

• CHANGELOG.md：这是项目的更新日志，记录每次版本的新增功能、修复问题和重要调整；想了解最近改了什么，可以先看这里。
• Gitee 镜像：如果访问 GitHub 不便，也可以从 Gitee 镜像获取本项目。
• docs/bsk-tutorial.md：这是 bsk 的总教程，用通俗例子和 Mermaid 图介绍 State、Verifier、Gate、Contract Pack 四种重要抽象，以及它们如何协作。
• skills/alpha/install-bensz-skills/README.md：这是 Skill 安装器的使用指南，介绍安装方式、参数和常见用法；准备安装 Skill 时，可以按这份指南操作。
• docs/templates/skill-body.md：这是新建或修改 Skill 时使用的四段式正文骨架。
• docs/templates/verifier-body.md：这是新建或修改 VERIFIER.md 时使用的五段轻量骨架，覆盖判断目标、输入证据、执行、输出判定和失败边界。
• docs/templates/skill-common-constraints.md：这是工作区、BAC、隐私和缺陷协作的公共约束长版本。