Clawhub Skill Creator

核心用法

Clawhub Skill Creator 是一套面向 AI Agent 的技能开发规范与工具链，核心使用场景包括：创建新技能、更新现有技能元数据、优化技能结构、验证发布前检查、理解 Clawhub 特有要求。

使用流程遵循 13 个阶段：需求澄清（明确问题、用户、资源）→ 结构规划（根据复杂度选择简单/中等/复杂模式）→ 初始化目录 → 编写 SKILL.md（YAML frontmatter + Markdown 正文）→ 配置 _meta.json → 添加 LICENSE.txt → 编写参考资料 → 本地验证 → Agent 测试 → 迭代优化 → 版本检查 → 打包 → 发布。

显著优点

1. AI 优先设计：技能专为 AI Agent 消费优化，禁止交互式提示，采用命令模板而非平台特定脚本，Agent 根据检测到的平台自主选择变体。
2. 渐进式信息披露：三级加载策略（元数据始终加载 → SKILL.md 触发时加载 → 参考资料按需加载），有效控制上下文 Token 预算。
3. 严格的 Token 优化：SKILL.md 限制 300 行以内，参考资料单文件 <5K 词，总计控制在 10K Token 以内。
4. 跨平台原生支持：同一命令提供 Linux/Mac、Windows CMD、PowerShell 三种写法，消除平台碎片化。
5. 完整的验证体系：内置 validate.sh 检查清单，覆盖命名一致性、JSON 有效性、文件规范性、引用完整性等 7 项关键检查。

潜在局限

• 语言强制要求：所有描述字段必须使用英语，对非英语开发者存在门槛。
• 版本管理严格：禁止版本降级，必须遵循 Semver 规范，小团队可能增加维护负担。
• 无动态调试能力：技能本身不提供运行时调试或日志分析功能，需依赖外部工具链。
• 生态锁定：设计深度耦合 Clawhub 注册表，迁移至其他平台需重写元数据和结构。

适合人群

• 需要将内部工具/知识封装为 AI 可调用技能的开发团队
• 构建企业级 Agent 平台的工程师
• 追求上下文效率、有 Token 成本敏感度的 AI 应用架构师
• 熟悉命令行工作流、习惯 Infrastructure as Code 的 DevOps 从业者

常规风险

• 触发失效风险：若 description 未包含 "Use when:" 触发条件或语言非英语，技能将无法被 Agent 正确识别。
• 版本冲突风险：未查询当前注册表版本直接发布，可能导致版本号冲突或覆盖他人更新。
• Token 溢出风险：忽视行数限制导致上下文膨胀，影响 Agent 推理质量与响应成本。
• 引用断链风险：参考资料未在 SKILL.md 中明确链接，Agent 无法按需加载深层内容。

核心用法

Clawhub Skill Creator 是一套专为 ClawHub 技能注册表设计的完整开发指南与配套工具。其核心使命是标准化技能创建流程，确保产出的技能能够被 AI 代理高效理解和执行。

使用场景覆盖五个维度：创建新技能发布、更新现有技能元数据、优化技能结构以适应 AI 代理、发布前验证，以及理解 ClawHub 特定规范。用户通过运行 ./scripts/init-skill.sh 初始化项目结构，随后遵循 13 阶段工作流逐步完成：需求澄清 → 结构规划 → 初始化目录 → 编写 SKILL.md → 配置 _meta.json → 添加许可证 → 编写参考文档 → 本地验证 → 代理测试 → 迭代优化 → 版本检查 → 打包 → 发布。

关键交付物包括 SKILL.md（指令与元数据）、_meta.json（注册表元数据）、LICENSE.txt 及可选的 references/、scripts/、assets/ 目录。特别强调的是"Agent-First Design"原则——技能专为 AI 代理而非人类设计，避免交互式提示，提供跨平台命令模板，采用渐进式信息披露（元数据→主体→资源），并严格控制令牌预算（总计不超过 10K tokens）。

显著优点

该技能的突出价值在于其系统性与规范性。首先，它提供了业界罕见的端到端技能开发方法论，将模糊的创作过程转化为可复制的 13 阶段流水线，显著降低新手入门门槛。其次，严格的技术规范具有前瞻性：英语描述强制要求确保国际化兼容；Token 预算管理（元数据 50 词、SKILL.md 200 行、参考资料 3K 词）直接优化 AI 代理的上下文效率；跨平台命令模板（Bash/CMD/PowerShell）让代理自主适配运行环境，而非依赖开发者编写平台特定脚本。

文档质量尤为出色。通过"快速开始"示例、明确的工作流编号、指令式写作风格（"Open file"而非"You should open"），以及丰富的反模式警示（专门章节列出 10 项禁止做法），大幅降低沟通歧义。配套的验证脚本（validate.sh、package-skill.sh）实现自动化质量门禁，减少人工疏漏。此外，安全设计内置其中：无外部 API 调用、无敏感信息硬编码、无动态代码执行，从架构层面消除常见攻击面。

潜在缺点与局限性

尽管设计周全，仍存在若干局限。第一，平台锁定风险。该技能深度耦合 ClawHub 生态（特定的 _meta.json 格式、clawhub CLI 工具、注册表版本查询机制），技能包无法直接迁移至其他 Agent 框架（如 LangChain Tools、OpenAI Functions、MCP Servers），跨平台复用需人工转换。第二，语言壁垒。虽然英文描述有利于国际化，但对非英语母语开发者构成一定门槛，且代码示例虽允许多语言，但缺乏系统性的本地化支持策略。第三，规模瓶颈。硬性规定的 300 行 SKILL.md 上限和 5K 词参考资料限制，可能难以承载极度复杂的领域知识（如企业级 ERP 集成、多步骤合规审计），迫使开发者拆分技能，增加维护复杂度。

工具链方面，脚本依赖 bash 环境，Windows 用户需额外配置 WSL 或 Git Bash；缺乏 IDE 插件或 VS Code 扩展，无法提供实时语法检查、自动补全等现代化开发体验。测试环节依赖"Phase 9: Test with Agent"的人工验证，无自动化测试框架或模拟代理环境，难以实现 CI/CD 集成。

适合的目标群体

该技能精准服务于四类用户：一是ClawHub 生态开发者，无论是个人创作者还是企业团队，需快速产出符合注册表规范的 AI 技能；二是AI 代理架构师，负责设计可被 LLM 可靠调用的工具体系，需要理解 Agent-First 设计范式的底层逻辑；三是技术写作者与文档工程师，希望借鉴其结构化写作方法（渐进披露、令牌优化、指令式风格）改进技术文档质量；四是开源项目维护者，计划将现有工具包装为标准化技能包并发布至公共注册表。

对纯终端用户（非开发者）价值有限，因其不提供可直接消费的"功能"，而是生产"生产工具"的元能力。对寻求跨框架通用技能方案的团队，需评估迁移成本。

使用风险

综合安全报告与功能特性，常规风险集中于以下维度：

性能风险：技能创建过程中的本地验证脚本（validate.sh）对大文件（如超大 assets/ 目录）执行可能产生 I/O 瓶颈；打包阶段（package-skill.sh）的 zip 操作在包含大量引用的复杂技能时可能消耗显著内存。

依赖项风险：脚本依赖系统标准工具（mkdir、cat、zip、jq），在精简容器环境或 Alpine Linux 中可能缺失 jq 等工具；bash 版本差异（如 macOS 默认 bash 3.2 vs Linux 4.0+）可能导致脚本行为不一致。

版本管理风险：semver 版本号需人工维护，若开发者未严格遵循 Phase 11 的版本检查流程，可能发生版本回退（1.1.0 → 1.0.2）或冲突，导致注册表拒绝发布或覆盖他人版本。

生成内容风险：工具本身安全（S+ 评级），但其生成的 SKILL.md 内容由开发者编写，若输入恶意指令（如诱导权限提升的提示词），工具不会拦截，需结合外部安全扫描（如报告推荐的 CLS-Certify）进行二次审查。

生态演进风险：ClawHub 平台规范可能迭代，当前 1.0.0 版本技能未来可能需要结构性迁移，建议关注官方 references/versioning.md 更新。