# Agent-Skills：跨平台智能体技能统一分发框架

> 一个支持 Claude Code、Codex、OpenCode 等多平台的智能体技能插件框架，实现一次编写、多平台分发的技能生态。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-05-17T13:16:21.000Z
- 最近活动: 2026-05-17T13:23:51.782Z
- 热度: 141.9
- 关键词: agent skills, multi-platform, Claude Code, Codex, OpenCode, TypeScript, plugin framework, vercel-labs/skills
- 页面链接: https://www.zingnex.cn/forum/thread/agent-skills
- Canonical: https://www.zingnex.cn/forum/thread/agent-skills
- Markdown 来源: ingested_event

---

# Agent-Skills：跨平台智能体技能统一分发框架\n\n## 背景：智能体技能的碎片化困境\n\n随着 AI 编程助手（如 Claude Code、Codex、OpenCode、Cursor 等）的普及，智能体技能（Agent Skills）成为提升开发效率的重要工具。然而，当前市场呈现高度碎片化状态：每个平台都有自己的技能定义格式、安装机制和执行环境。开发者为 Claude Code 编写的技能无法直接在 Codex 中使用，反之亦然。\n\n这种碎片化带来了显著的成本：\n\n- **重复开发**：同一功能需要在多个平台上重复实现\n- **生态割裂**：技能无法跨平台共享，限制了优秀实践的扩散\n- **维护负担**：多平台支持意味着多倍的维护工作量\n- **用户体验不一致**：用户在不同工具间切换时需要重新学习技能的使用方式\n\nAgent-Skills 项目正是为解决这一痛点而诞生的。它提出了一种"一次编写，多平台分发"的架构，让开发者能够用统一的 TypeScript 接口定义技能，然后自动生成适配不同平台的插件包。\n\n## 核心架构：仓库即交付物\n\nAgent-Skills 的核心理念是"The repo IS the deliverable"（仓库即交付物）。开发者无需发布到多个应用商店或维护多个分发渠道，只需维护一个 GitHub 仓库，用户即可通过四种不同的安装方式获取适合自己平台的插件版本。\n\n### 多平台安装方式\n\n| 平台 | 安装命令 | 说明 |\n|------|---------|------|\n| Claude Code | `claude plugin marketplace add github:mikestopcontinues/agent-skills` | 通过 Claude Code 插件市场安装 |\n| Codex | `codex plugin marketplace add mikestopcontinues/agent-skills` | 通过 Codex 插件市场安装，需在 TUI 中启用或配置 `~/.codex/config.toml` |\n| OpenCode | 在 `opencode.json` 中添加 `"plugin": ["@mikestopcontinues/agent-skills"]` | npm 包方式安装 |\n| 通用（47+ 工具） | `npx skills add mikestopcontinues/agent-skills` | 通过 vercel-labs/skills 安装到 `~/.agents/skills/` |\n\n这种设计意味着一个技能仓库可以同时服务 Claude Code、Codex、OpenCode、Cursor、Gemini CLI 等 47 种以上的智能体产品。\n\n## 项目结构解析\n\nAgent-Skills 采用清晰的分层架构，将技能定义与平台适配分离：\n\n### 规范定义层（Canonical Sources）\n\n`generator/canonical-sources/` 目录是技能编写的核心区域。开发者在这里使用 `defineSkill`、`defineAgent`、`defineHook`、`defineProjectContext` 等工厂函数定义技能。文件系统本身就是注册表——每个 `.ts` 文件及其配套的 `.md` 和 `.sh` 文件构成一个完整的技能定义。\n\n### 工厂层（Factories）\n\n`generator/factories/` 包含 `define*` 工厂函数的实现、类型定义和 Valibot 模式验证。这一层确保技能定义的一致性和类型安全。\n\n### 发射层（Emitters）\n\n`generator/emit/` 包含针对不同平台的代码生成器：\n\n- `claudeCode.ts`：生成 Claude Code 插件包\n- `codex.ts`：生成 Codex 插件包\n- `opencode.ts`：生成 OpenCode npm 包内容\n- `marketplaces.ts`：生成市场配置文件\n\n### 构建产物层\n\n- `claude/`：Claude Code 插件包（已提交到仓库，由构建脚本重新生成）\n- `codex/`：Codex 插件包（已提交到仓库）\n- `opencode/`：OpenCode npm 包内容（`package.json#main` 指向 `./opencode/src/plugin.ts`）\n- `.claude-plugin/marketplace.json`：Claude Code 市场配置（同时被 vercel-labs/skills 读取）\n- `.agents/plugins/marketplace.json`：Codex 市场配置\n\n## 开发工作流\n\nAgent-Skills 提供了完整的开发工具链：\n\n### 环境要求\n\n- Node.js ≥ 24（支持原生 TypeScript 类型剥离，`.ts` 文件可直接运行，无需编译步骤）\n- pnpm 10\n\n### 安装依赖\n\n```bash\npnpm install\n```\n\n### 构建\n\n```bash\npnpm run build\n```\n\n此命令重新生成 `claude/`、`codex/`、`opencode/` 目录以及两个 `marketplace.json` 文件。\n\n### 代码检查\n\n```bash\npnpm run check\n```\n\n执行以下检查：\n- `tsc --noEmit`：TypeScript 类型检查\n- `eslint`：代码风格检查\n- `vitest`：单元测试\n- drift check：验证构建产物与源码的一致性\n\n### 产物一致性保证\n\n```bash\npnpm run check:bundles\n```\n\n此命令先执行 `pnpm build`，然后检查 Git 差异。如果已提交的构建产物与新生成的产物不一致，命令会失败。这确保了仓库中的 `claude/`、`codex/`、`opencode/` 目录和两个 `marketplace.json` 文件始终与规范源码保持同步。CI 流程会运行 `pnpm run check` 来保证这一点。\n\n### 添加或修改技能\n\n要添加或修改技能、智能体或钩子：\n\n1. 编辑 `generator/canonical-sources/` 下的 `.ts` 文件（及其配套的 `.md` / `.sh` 文件）\n2. 运行 `pnpm build` 重新生成插件包\n3. 提交更改（包括重新生成的构建产物）\n\n## 技术亮点\n\n### 原生 TypeScript 支持\n\n项目利用 Node.js ≥ 24 的原生 TypeScript 支持（类型剥离），`.ts` 文件可以直接运行，无需编译步骤。这简化了开发流程，减少了构建配置的复杂性。\n\n### 类型安全\n\n使用 Valibot 进行运行时模式验证，确保技能定义在编译时和运行时都符合预期结构。\n\n### 跨平台一致性测试\n\n`tests/` 目录包含：\n- 往返测试（Round-trip tests）：验证技能定义到构建产物再到运行时行为的完整性\n- 跨平台测试（Cross-harness tests）：验证同一技能在不同平台上的行为一致性\n- 产物一致性测试（Bundle-coherence tests）：验证构建产物的正确性\n\n### 版本管理\n\n项目采用语义化版本控制（SemVer），当前版本为 v0.1。Claude Code 路径已通过与 vercel-labs/skills 规范的对比验证，并在真实代码库（labyrinth-life、svgbro）和合成种子仓库上进行了测试。Codex 路径已完成构建产物测试，安装流程已文档化。OpenCode 路径已完成发射测试（尚未进行实时 OpenCode 评估）。\n\n## 技能/智能体/钩子清单\n\n完整的技能、智能体和钩子清单位于 `generator/canonical-sources/` 目录。这些规范定义了：\n\n- **生命周期技能（Lifecycle Skills）**：管理项目从创建到归档的全生命周期\n- **人格智能体（Persona Agents）**：具有特定角色和职责的智能体\n- **治理钩子（Governance Hooks）**：在关键决策点介入的审计和控制机制\n\n## 生态关联\n\n- **vercel-labs/skills**：Agent-Skills 兼容 vercel-labs/skills 规范，支持 `npx skills add` 安装方式\n- **Claude Code / Codex / OpenCode**：作为目标平台，提供插件运行时环境\n\n## 局限与展望\n\n### 当前局限\n\n- OpenCode 路径尚未进行实时评估\n- 技能生态系统尚处于早期阶段，需要更多贡献者加入\n\n### 未来方向\n\n- 扩展支持更多智能体平台\n- 建立技能审核和评分机制\n- 开发技能可视化工具\n- 构建技能依赖管理系统\n\n## 总结\n\nAgent-Skills 为智能体技能生态提供了一个关键的"中间层"解决方案。它不试图取代任何现有的智能体平台，而是通过统一的抽象层让技能能够跨平台流动。这种架构既保留了各平台的差异化优势，又解决了技能碎片化带来的开发和维护成本。\n\n对于技能开发者而言，Agent-Skills 意味着一次编写即可触达 47+ 种智能体工具的用户。对于用户而言，这意味着可以在不同工具间无缝使用相同的技能，获得一致的体验。对于整个智能体生态而言，Agent-Skills 提供了一个开放、可扩展的技能共享基础设施。\n\n随着 AI 编程助手的普及，技能生态将成为竞争的关键战场。Agent-Skills 的跨平台分发能力，使其有望成为这一生态的重要基础设施。