自定义技能开发
发现团队反复执行某种专业流程时，把它封装成 Skill：
- 复用 — 团队成员都能按同一方式触发
- 一致性 — 流程 / 规范 / 约束固化
- 演进 — 升级 Skill 版本，所有使用者统一生效
- 治理 — 安全审计、权限管控、使用统计
my-skill/
├── SKILL.md ← 必须：元数据 + prompt 片段（描述 + 使用规则）
├── skill.manifest.json ← 可选：安装配置 / 版本 / 依赖
├── tools/ ← 可选：技能专属 Python 工具
│ └── my_tool.py
├── references/ ← 可选：规则 / 模板 / 参考文档（按需懒加载）
│ └── checklist.md
├── tests/ ← 可选：契约测试
│ └── test_contract.py
└── scripts/ ← 可选：安装 / 升级钩子
---
name: my-skill
description: 用一两句话描述「什么情况下触发这个技能」。这是 Agent 决定是否调用的关键依据。
execution_mode: balanced # precise | balanced | creative
tags: [domain, usecase]
version: 1.0.0
license: proprietary # proprietary | mit | apache-2.0
entrypoints:
- name: main
tools: [tools/my_tool.py:do_it]
---
正文部分会被注入到 Agent 的 system prompt 或 tool hint 里：
# my-skill
## 使用时机
- 用户说"做 X"、"处理 Y 文档"时触发
- 不要在只是询问概念时触发
## 操作步骤
1. 先读输入文件
2. 调 tools/my_tool.py:do_it
3. 输出结果到指定路径
## 严格约束
- 不能修改输入文件
- 超过 10MB 的输入要拒绝并提示
description 决定 Agent 是否触发这个 Skill。写得越精准，误触发越少。
/skill-architect 帮我设计一个"从 Excel 生成测试报告"的技能
skill-architect 会问 5 个阶段的问题：目标、触发时机、输入输出、约束、风险，生成骨架。
combo-cli skill init my-skill
# 交互式填写 name / description / entrypoints
核心是 description。参考已有 Skill（比如 AgentFlow/src/skills/builtin/docx/SKILL.md）。
在 tools/ 下写 Python 函数。函数签名会自动被 Agent 识别：
def do_it(input_path: str, output_path: str, mode: str = "fast") -> dict:
"""Process a document.
Args:
input_path: Source file.
output_path: Destination.
mode: fast | accurate.
Returns:
{"status": "ok", "duration_ms": ...}
"""
...
# tests/test_contract.py
def test_happy_path():
result = do_it("fixtures/sample.xlsx", "/tmp/out.xlsx")
assert result["status"] == "ok"
def test_too_large():
# should raise
...
combo-cli skill run ./my-skill --input "处理 fixtures/sample.xlsx"
combo-cli skill publish ./my-skill --visibility tenant
| 建议 | 说明 |
|---|
| description 精准 | 写明"触发"与"不触发"两种情况 |
| 最小权限 | 只暴露必要工具 |
| 可回滚 | 写操作留下 dry-run 开关和快照 |
| 防滥用 | 输入大小、频率、权限做上限 |
| 引用而非内联 | 大段规则放 references/，运行时按需加载，节省 token |
| 幂等 | 同样输入重复运行结果一致 |
| 测试覆盖 | happy path + 至少 2 个异常 path |
- 把大量业务逻辑写在 SKILL.md 正文里（太占 token）
- 在 Skill 里硬编码凭据
- 工具函数副作用不可控（写全局、改环境）
- Skill 之间深度耦合，缺一不可
Nox-Lumen Auto