使用 Skilo
Skilo 是一款用于开发代理技能（Agent Skills）的 CLI 工具。
安装
curl -sSfL https://raw.githubusercontent.com/manuelmauro/skilo/main/install.sh | sh
快速开始
skilo new my-skill # 从模板创建
skilo add owner/repo # 从 Git 安装
skilo lint . # 根据规范验证
skilo fmt . # 格式化 SKILL.md 文件
运行 skilo -h 查看所有命令和选项。
始终验证技能
在提交任何技能更改之前，务必运行 skilo lint 和 skilo fmt。 这些命令强制执行代理技能规范并捕获常见问题。
# 一条命令完成验证和格式化
skilo check .
# 严格模式用于 CI（警告视为错误）
skilo check --strict .
技能结构
my-skill/
├── SKILL.md # 必需：包含 YAML 前置数据的清单
├── scripts/ # 可选：可执行代码
├── references/ # 可选：附加文档（按需加载）
└── assets/ # 可选：静态资源
前置数据要求
必填字段
name（1-64 个字符）
- 仅限小写字母数字和连字符（
a-z、0-9、-） - 不能以
-开头/结尾，也不能包含-- - 必须与父目录名称匹配
description（1-1024 个字符）
- 描述技能做什么以及何时使用
- 包含有助于代理匹配用户请求的关键词
可选字段
license- 保持简短，详细内容请参考 LICENSE 文件compatibility（最多 500 字符）- 环境需求（例如Requires git, docker）metadata- 用于自定义属性的键值对allowed-tools- 以空格分隔的预批准工具列表（实验性）
最佳实践
编写有效的描述
描述是代理决定何时激活技能的依据。要具体明确。
# 好——具体且包含关键词
description: 从 PDF 文件中提取文本和表格、填写 PDF 表单以及合并多个 PDF 文件。当处理 PDF 文档或用户提到 PDF、表单或文档提取时使用。
# 差——模糊，缺乏触发提示
description: 帮助处理 PDF。
保持正文内容简洁
整个 SKILL.md 正文在技能激活时加载。请保持在 500 行以内。
- 包含分步说明
- 添加输入输出示例
- 涵盖常见边缘情况
- 将详细资料移至
references/
使用渐进式披露
构建技能以最小化上下文消耗：
- 元数据（约 100 Tokens） - 所有技能启动时加载
name+description - 指令（<5000 Tokens） - 技能激活时加载完整正文
- 资源（按需加载） - 仅在需要时加载
scripts/、references/、assets/
编写自包含脚本
scripts/ 中的脚本应：
- 保持自包含或清晰记录依赖关系
- 包含有用的错误消息
- 优雅地处理边缘情况
有效组织参考文档
references/ 中的文件按需加载：
- 保持文件聚焦（一个文件 = 一个概念）
- 使用从技能根目录出发的相对路径
- 避免深层嵌套的引用链
检查规则
Skilo 强制执行以下规则（可在 .skilorc.toml 中配置）：
| 代码 | 规则 | 默认值 |
|---|---|---|
| E001 | name_format | 启用 |
| E002 | name_length | 64 个字符 |
| E003 | name_directory | 启用 |
| E004 | description_required | 启用 |
| E005 | description_length | 1024 个字符 |
| E006 | compatibility_length | 500 个字符 |
| E009 | references_exist | 启用 |
| W001 | body_length | 500 行 |
| W002 | script_executable | 启用 |
| W003 | script_shebang | 启用 |
CI 集成
- name: 验证技能
run: |
curl -sSfL https://raw.githubusercontent.com/manuelmauro/skilo/main/install.sh | sh
skilo check --strict skills/