Skill 开发指南

什么是 Skill？

Skill 本质上是一个声明式的”能力包”，包含：

一段经过打磨的 System Prompt（角色设定 / 任务约束 / 输出格式）
可选的 工具调用配置（FS / Shell / HTTP / MCP server）
可选的 示例对话（few-shot examples）
元数据（名称、描述、作者、版本、依赖模型能力）

用户只需 claw skill install xiawo/code-reviewer 即可在本地拥有”代码评审专家”角色，而不必自己反复调试 Prompt。

目录结构

一个最小 Skill 仓库长这样：

my-skill/
├── skill.yaml          # 元数据
├── prompt.md           # System Prompt 主体
├── examples/           # 可选：few-shot 对话
│   ├── 01-input.md
│   └── 01-output.md
└── README.md           # 用户可见的说明文档

skill.yaml 模板

name: weekly-report
display_name: 周报生成器
version: 0.2.0
author: yourname
description: 从 git log + 日记片段生成结构化中文周报
tags: [办公, 写作]
icon: "📊"

# 推荐的最低模型能力
requires:
  context_window: 16k
  capabilities: [tool_use]

# 默认开放的工具
tools:
  - fs.read           # 读取本地文件（如日记 markdown）
  - shell.git_log     # 调用 git log 子命令

# 入口 Prompt
prompt: prompt.md
examples: examples/

编写 prompt.md

System Prompt 是 Skill 的灵魂，建议遵循 CRISP 结构：

# Role
你是一名资深技术经理的 AI 助理，专门帮工程师整理周报。

# Task
- 调用 `shell.git_log` 获取本周 commit
- 调用 `fs.read` 读取用户指定的日记文件（若有）
- 整理为结构化周报

# Constraints
- 只输出周报正文，不要寒暄
- 用第一人称中文，避免"本人/笔者"
- 项目超过 5 个时按重要性精简
- 字数控制在 500-800 字

# Output Format
按以下 4 段输出（带标题）：
1. **本周成果**（按项目分组，量化数据）
2. **遇到的问题与解决**
3. **下周计划**（3-5 条）
4. **需要协作的事项**

# Examples
（参见 examples/ 目录）

本地调试

# 在仓库目录下启动本地 dev 模式
claw skill dev .

# 与 Skill 对话调试
claw chat --skill ./

# 查看所有调用的 tool 日志
claw skill dev . --trace

发布到虾窝市场

1. 注册作者账号

在 id.xiawo.ai 注册，进入”开发者中心” → 创建 Publisher，记录 publisher slug（如 yourname）。

2. 提交 PR

把仓库 push 到 GitHub，然后在 github.com/xiawo-ai/skills-registry 提 PR，按模板填写：

仓库地址
默认 commit hash
自我介绍

3. 自动审核 + 人工复核

提交后会触发：

自动审核：扫描 prompt 中的注入 / 越狱模式、敏感词、外链黑名单
人工复核：志愿者运行 Skill 跑通示例，检查是否名副其实

通过后会出现在 Skills 市场，用户可一键安装。

版本与升级

遵循 Semantic Versioning：major.minor.patch
重大行为变更必须升 major，避免老用户突然破功
用户通过 claw skill upgrade <name> 升级，可指定固定版本：claw skill install yourname/[email protected]

Skill 收益分成（规划中）

虾窝计划在 2026 年 Q1 推出 付费 Skill 机制：

作者可设置 price.monthly / price.per_call
平台抽佣 15%，剩余 85% 结算给作者
用户在 token.xiawo.ai 充值后即可订阅

常见问题

Q: Skill 和 MCP server 的关系？

A: Skill 是用户可见的能力包，MCP server 是底层工具协议。Skill 可以引用一个或多个 MCP server，对用户屏蔽配置复杂度。

Q: 能否用 Python / Node 写复杂逻辑？

A: 可以。tools 字段支持声明 mcp.python / mcp.node 类型，仓库内放 tools/*.py 即可被自动加载。

Q: 如何避免 Skill 被滥用做坏事？

A: 虾窝 Skills 市场对 Prompt 越狱检测、外链黑名单有自动扫描；用户安装时会显示”危险等级”，越权工具（如 shell.exec）必须用户确认。