山月刀岚月刀1. 技能创建的核心概念解析
技能（Skill）本质上是一种模块化的能力封装机制，它允许我们将特定领域的专业知识、工作流程和工具集成打包成一个可复用的单元。这种设计理念源于软件工程中的"关注点分离"原则，通过将不同功能解耦为独立模块，实现更高效的开发和维护。
1.1 技能的核心价值
在实际应用中，技能主要解决三个关键问题：
-
知识沉淀：将专家经验转化为可复用的程序性知识。例如，一个财务分析技能可能包含企业特定的报表生成逻辑和合规检查规则。
-
流程标准化：固化最佳实践工作流。比如客户服务场景中的投诉处理流程，可以封装为包含标准响应模板和升级规则的技能。
-
工具集成：统一对接各类API和文件格式。典型的如PDF处理技能，可能集成了多种PDF库的操作方法和常见问题解决方案。
提示：设计技能时始终要问自己——这个封装能否让其他使用者无需了解实现细节就能直接应用？这是判断技能设计是否成功的黄金标准。
1.2 技能与普通代码库的区别
虽然技能也包含代码和文档，但与常规代码库有本质区别：
| 特性 | 技能 | 传统代码库 |
|---|---|---|
| 使用对象 | AI智能体 | 人类开发者 |
| 交互方式 | 自然语言触发 | API调用或命令行 |
| 知识表达 | 示例驱动+启发式指引 | 技术文档+接口说明 |
| 上下文管理 | 渐进式加载 | 全量导入 |
| 错误处理 | 容错性建议 | 严格异常机制 |
| 扩展性 | 动态组合 | 静态依赖 |
这种差异决定了技能设计必须更加注重"可解释性"和"场景适应性"。一个好的技能应该像一位经验丰富的导师，不仅能给出正确答案，还能解释为什么这是最佳方案。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 技能创建全流程详解
2.1 需求分析与场景定义
创建技能的第一步是明确使用场景。以开发一个"自动生成周报"的技能为例，我们需要：
-
收集典型用例：
- 将JIRA任务自动汇总为进展报告
- 从Git提交记录生成技术周报
- 整合多个数据源创建综合汇报
-
识别核心需求：
- 必须支持Markdown输出格式
- 需要处理日期范围筛选
- 应包含进度百分比计算
- 支持多项目合并展示
-
划定能力边界：
- 不处理数据可视化（交由其他技能负责）
- 不涉及敏感信息过滤（由前置技能保证）
- 不包含审批流程（属于后续环节）
实际操作中，可以使用如下模板整理需求：
markdown复制## 场景示例
当用户说："帮我生成上周的技术周报，重点展示A项目的进展和B项目的风险"
### 预期输出
1. 按日期排序的Git提交摘要
2. JIRA任务状态统计
3. 风险项专项说明
4. Markdown格式的层级标题
### 所需能力
- JIRA API查询
- Git日志解析
- 风险关键词识别
- 模板填充
2.2 技能结构设计
标准的技能目录结构应该遵循"核心精简，按需扩展"的原则。以前面的周报技能为例：
code复制weekly-report/
├── SKILL.md
├── scripts/
│ ├── fetch_jira.py
│ ├── parse_git.py
│ └── generate_report.py
├── references/
│ ├── jira_fields.md
│ └── git_cheatsheet.md
└── assets/
├── template.md
└── example_output.md
2.2.1 SKILL.md 编写规范
SKILL.md 是技能的核心描述文件，其头部元数据必须包含：
yaml复制name: weekly-report
description: 自动生成技术周报，支持从JIRA和Git提取数据，输出Markdown格式报告。当需要：(1)汇总多源任务进展 (2)生成标准化技术报告 (3)追踪项目风险时使用。
正文部分应采用"问题-解决方案"的编排方式：
markdown复制## JIRA任务处理
当遇到"展示A项目进展"类请求时：
1. 使用`scripts/fetch_jira.py`查询指定项目
2. 筛选`status changed during [date range]`
3. 按优先级分组统计
> 注意：JIRA字段说明见references/jira_fields.md
## Git提交分析
对于代码相关汇报：
1. 运行`scripts/parse_git.py -p <path> -d <days>`
2. 按类型( feat/fix/docs )分类
3. 识别高频修改文件
使用模板：
```bash
python scripts/generate_report.py -t assets/template.md
code复制
### 2.3 资源文件开发
#### 2.3.1 脚本开发要点
技能中的脚本与传统脚本有显著差异：
1. **强容错性**：每个脚本都应内置输入验证和默认值处理。例如：
```python
def parse_date_range(input_str):
try:
# 支持"last week"/"2023-01-01 to 2023-01-07"等多种格式
return normalized_dates
except Exception:
return get_default_range() # 默认返回最近7天
- 自描述性：通过help文本提供使用示例：
python复制if __name__ == "__main__":
print("""
示例用法:
python parse_git.py -p ./project -d 7
-p 项目路径 (默认当前目录)
-d 回溯天数 (默认7)
""")
- 模块化输出：采用JSON等结构化格式便于后续处理：
python复制print(json.dumps({
"commits_by_type": stats,
"hot_files": top_files
}))
2.3.2 参考资料编写
references/ 下的文档应该：
- 采用"速查表"形式组织
- 包含常见问题解决方案
- 标注信息更新时间
示例片段：
markdown复制## JIRA字段速查
| 字段名 | 类型 | 说明 | 示例值 |
|-------------|--------|---------------------|-------------|
| status | 状态 | 任务当前阶段 | In Progress |
| resolution | 解决结果 | 关闭原因 | Fixed |
> 最近更新：2023-11-20
> 遇到RES-123错误时，检查权限设置
3. 技能优化与迭代
3.1 性能调优策略
-
上下文压缩：
- 将长示例拆分为references/片段
- 使用
grep -A3 -B3 "关键字"式引用 - 对脚本添加
--summary参数返回简化结果
-
触发精准度提升：
- 在description中添加否定用例：
yaml复制description: ...不适用于：(1)单任务状态查询 (2)非技术类报告 - 使用明确触发短语：
yaml复制description: 当用户明确说"生成周报"或"汇总本周工作"时使用
- 在description中添加否定用例：
-
缓存机制：
python复制# scripts/fetch_jira.py if not cache_expired(project): return read_cache() else: data = fetch_from_api() write_cache(data)
3.2 版本管理方案
虽然技能本身不包含版本文件，但可以通过以下方式实现版本控制：
- 在SKILL.md头部添加注释：
markdown复制
<!-- Version: 2023-11-20 --> - 变更日志写入references/changelog.md
- 重大更新时创建副本目录：
code复制skills/ ├── weekly-report-v1/ └── weekly-report-v2/
4. 实战技巧与避坑指南
4.1 常见问题解决
问题1：技能未被正确触发
- 检查description是否包含足够多的触发关键词
- 添加同义词描述："周报|每周报告|工作汇总"
问题2：脚本执行超时
- 添加超时控制：
python复制from func_timeout import func_timeout func_timeout(10, main_func) - 实现分页获取数据
问题3：上下文溢出
- 使用
scripts/代替冗长代码示例 - 在references/中添加"快速参考"章节
- 对长输出添加
--brief参数
4.2 高级技巧
-
技能组合：
markdown复制## 与其它技能协作 1. 先使用`data-clean`技能预处理原始数据 2. 用本技能生成报告初稿 3. 最后通过`format-review`技能美化输出 -
动态配置：
python复制# scripts/config.py def load_config(): return { 'jira_server': os.getenv('JIRA_URL'), 'git_path': os.getenv('GIT_PATH') } -
测试套件：
bash复制# 在技能目录添加test/test_usage.sh echo "生成上周周报" | claude --skill weekly-report
5. 技能创建工具链
5.1 初始化脚本增强版
标准的init_skill.py可以扩展为：
python复制def create_skill(name):
# 基础结构
os.makedirs(f"{name}/scripts")
os.makedirs(f"{name}/references")
# 添加模板文件
with open(f"{name}/SKILL.md", "w") as f:
f.write(f"""---
name: {name}
description: 在此填写技能描述
---
## 核心功能
## 使用示例
""")
# 添加示例脚本
with open(f"{name}/scripts/example.py", "w") as f:
f.write("""#!/usr/bin/env python3
def main():
print("Hello from your skill")
if __name__ == "__main__":
main()
""")
5.2 自动化校验工具
创建validate_skill.py进行完整性检查：
python复制def validate(skill_dir):
# 检查必需文件
assert os.path.exists(f"{skill_dir}/SKILL.md")
# 解析YAML头部
with open(f"{skill_dir}/SKILL.md") as f:
assert "name:" in f.read(100)
# 检查脚本可执行性
for script in glob(f"{skill_dir}/scripts/*"):
assert os.access(script, os.X_OK)
在实际开发中，技能创建不是一次性的工作，而是需要持续迭代的过程。每次使用技能时都应该记录遇到的边界情况，定期更新参考资料和脚本逻辑。我个人的经验是建立一个技能使用日志，记录哪些场景下技能表现良好，哪些情况需要人工干预，这些数据将成为改进技能的最宝贵资源。