从Skill使用者到创造者：手把手教你编写规范的AI Agent技能

1. 项目概述：从“用”到“造”的认知跃迁

最近和不少做AI Agent的朋友聊天，发现一个挺普遍的现象：大家谈起LangChain、AutoGen这些框架，或者某某大模型的最新API，都头头是道，各种现成的Skill（技能）用得飞起。但当我问起“你自己写过几个Skill？”或者“这个Skill的内部原理是啥？”时，场面往往就安静了。这让我想起一个老梗——“别光会用，不会写等于白搭”。这话放在AI Agent开发里，再贴切不过了。

我们正处在一个AI Agent爆发的时代，无论是自动化办公助手、智能客服，还是复杂的游戏NPC，其核心能力都依赖于一个个精心设计的Skill。你可以把Skill理解为Agent的“肌肉记忆”或“专业工具箱”。市面上有大量开源的、封装好的Skill，让你能快速搭建一个能对话、能查天气、能订餐的Agent。这很好，极大地降低了入门门槛。但问题也随之而来：当你的业务场景稍微特殊一点，比如需要Agent根据你公司内部的CRM数据生成客户报告，或者需要它按照一套复杂的工艺规范去解析图纸时，你会发现，现成的Skill库瞬间失灵。这时，如果你只停留在“调用者”的层面，项目就会立刻卡壳。

所以，这个内容的核心，就是想和你一起，完成从“Skill使用者”到“Skill创造者”的转变。我们不只讲怎么调用一个weather.get，更要深挖下去：一个规范的Skill文件（比如常说的SKILL.md）到底长什么样？为什么需要这些结构？大模型是如何理解并执行这个Skill的？背后涉及的提示工程（Prompt Engineering）、工具调用（Function Calling）乃至更底层的规划（Planning）原理是什么？我将结合具体的代码示例和项目经验，手把手带你走完从构思、规范编写、代码实现到集成测试的全流程。无论你是想为自己的副业项目添加一个独特功能，还是在工作中需要定制企业级Agent，掌握“造轮子”的能力，都将让你从人群中脱颖而出。

2. 核心概念辨析：Skill、Tool、Action与规范文件

在动手之前，我们必须把几个容易混淆的概念理清楚。这在社区讨论和不同框架的文档中经常混用，但理解它们的细微差别对设计一个健壮的Skill至关重要。

2.1 Skill vs. Tool：能力单元与执行端点

很多人会把Skill和Tool划等号，但在一个设计良好的Agent系统中，它们通常是分层的关系。

• Tool（工具）：是最原子的操作单元。它是一个具体的、可执行的函数或API接口，有明确的输入和输出。例如，“发送HTTP GET请求”、“查询数据库”、“调用文本转语音API”。一个Tool通常对应代码中的一个函数，其描述（名称、描述、参数schema）用于让大模型理解何时以及如何调用它。
• Skill（技能）：是一个更高层次的、面向任务的能力单元。一个Skill封装了完成一个特定目标所需的知识、逻辑以及一个或多个Tools。它更接近人类理解的“技能”。例如，“预订会议室”这个Skill，内部可能包含了“查询会议室空闲状态”、“验证用户权限”、“向日历系统发送创建事件请求”等多个Tools的协调调用，还可能内置了处理时间冲突、权限不足等异常情况的逻辑。

简单类比：Tool是螺丝刀、锤子、尺子这些单一工具；而Skill是“组装一个书架”这项能力，它需要你规划步骤（先量尺寸，再拧螺丝），并懂得在何时使用何种工具，甚至处理“螺丝滑丝了怎么办”这样的问题。

2.2 Action：Skill的执行实例

当Agent在推理过程中，决定要激活某个Skill来推进任务时，就产生了一个Action（行动）。你可以认为Action是Skill在特定上下文（Context）中的一次具体执行。例如，用户说“帮我订明天下午两点的会议室”，Agent规划后，决定触发“预订会议室”这个Skill，并生成了一个具体的Action，其参数是{date: “明天”， time: “14:00”， duration: “1小时”}。

2.3 SKILL.md：技能的“说明书”与“契约”

这就是我们今天要重点攻克的对象。SKILL.md是一个Markdown格式的文件，它是一个Skill的标准化描述文档。它为什么如此重要？

1. 对人（开发者）的文档：它清晰定义了Skill的功能、输入、输出、使用示例和注意事项，是团队协作和后续维护的基石。
2. 对模型（AI）的指令：在运行时，Agent系统（或框架）会将SKILL.md中的关键部分（特别是描述、参数定义）作为系统提示词（System Prompt）的一部分，注入给大模型，从而让模型“学会”这个技能。它是人机之间关于“这个技能能做什么、怎么做”的契约。

一份规范的SKILL.md，是连接开发者意图与AI模型理解的桥梁。写得好，模型调用精准；写得模糊，模型就会“胡言乱语”或无法调用。

3. 手把手编写一份规范的SKILL.md

理论说再多，不如动手写一份。我们以一个相对复杂但贴近实际场景的Skill为例：“分析Git仓库提交历史并生成代码贡献报告”。这个Skill需要调用Git命令，解析数据，并进行一定的文本总结。

3.1 文件结构与核心组成部分

一份完整的SKILL.md通常包含以下部分，我们逐一拆解：

# Skill: GitCommitAnalyzer ## Description 该技能用于分析指定Git代码仓库的提交历史，并生成一份可读性高的代码贡献分析报告。它可以统计指定时间段内所有贡献者的提交次数、添加/删除行数，识别出主要的文件变更类型，并总结代码库的活跃趋势。适用于项目负责人进行周期性的代码回顾、贡献度评估，或新成员快速了解项目历史。 ## Prerequisites - 目标机器上必须安装有 `git` 命令行工具，并且版本 >= 2.20。 - 执行Agent的进程必须对目标Git仓库目录具有读取权限。 - 如果需要分析远程仓库，需确保网络连通性。 ## Input Parameters (JSON Schema) 技能被调用时，需要提供以下格式的输入参数： ```json { "repo_path": "字符串，本地Git仓库的绝对路径。例如：/home/user/projects/my-app", "since": "字符串，可选。分析起始日期，格式为 YYYY-MM-DD。默认为30天前。", "until": "字符串，可选。分析截止日期，格式为 YYYY-MM-DD。默认为当前日期。", "branch": "字符串，可选。要分析的分支名，默认为 'main' 或 'master'。", "output_format": "字符串，可选。报告输出格式，可选 'markdown'、'html' 或 'json'。默认为 'markdown'。" }

Output Specification

技能执行成功后，将返回一个对象，包含报告内容和原始数据摘要。

{ "success": true, "report": "字符串，根据指定格式生成的详细报告文本。", "summary": { "total_commits": "整数，总提交数", "contributors": "数组，贡献者列表，每个元素包含姓名、提交数、行数增减", "most_changed_file": "字符串，变更最频繁的文件路径", "period": "字符串，分析的时间范围" }, "artifact_path": "字符串，可选。如果报告生成了文件（如HTML），则提供文件路径。" }

如果执行失败，则返回：

{ "success": false, "error": "字符串，错误描述信息", "code": "字符串，可选的错误代码，如 'REPO_NOT_FOUND', 'GIT_COMMAND_ERROR'" }

Function Signature (For LLM)

以下是为大模型（LLM）识别和调用而设计的结构化描述，通常由框架自动从上述Schema提取或需手动维护：

# 这是一个示例性的伪代码描述，实际框架（如LangChain）有自己的定义方式。 def git_commit_analyzer( repo_path: str, since: str = “30 days ago”, until: str = “today”, branch: str = “main”, output_format: str = “markdown” ) -> str: “”” 分析Git仓库提交历史并生成贡献报告。 参数： repo_path: 仓库本地路径。 since: 开始日期。 until: 结束日期。 branch: 目标分支。 output_format: 输出格式。 返回：格式化的报告字符串。 “””

Implementation Logic & Steps (简述)

1. 参数验证与默认值填充：检查repo_path是否存在，处理默认日期。
2. 执行Git命令：使用subprocess或gitpython库执行一系列命令，如：
   • git log --since=<since> --until=<until> --oneline --numstat：获取提交概览和文件变更行数。
   • git shortlog -sn --since=<since> --until=<until>：获取贡献者排名。
3. 数据解析与聚合：解析上述命令的输出，将文本数据转换为结构化的字典或对象，按作者、文件进行聚合计算。
4. 报告生成：根据output_format选择模板，将聚合后的数据填充，生成最终的报告字符串。可能使用Jinja2等模板引擎。
5. 结果封装与返回：将报告和摘要封装成预定义的输出JSON格式。

Example Usage

场景：分析过去一个月项目my-project在develop分支上的活跃情况。

调用请求（示例）:

{ "repo_path": "/Users/me/workspace/my-project", "since": "2024-03-01", "until": "2024-03-31", "branch": "develop", "output_format": "markdown" }

预期输出报告片段（Markdown）:

# Git 代码贡献分析报告 **仓库**：my-project (develop分支) **分析周期**：2024-03-01 至 2024-03-31 ## 概览 - 总提交数：**142** 次 - 活跃贡献者：**8** 人 - 共增加代码 **12,450** 行，删除 **4,780** 行。 ## 贡献者排名 1. **张三**：58次提交 (+5,200, -1,800) 2. **李四**：42次提交 (+4,100, -1,200) 3. **王五**：20次提交 (+1,550, -980) ... ## 最活跃文件 - `src/core/engine.py`: 被修改了 **35** 次。 - `docs/api_reference.md`: 被修改了 **28** 次。 ...

Error Handling & Edge Cases

• 仓库路径错误：检查路径是否存在以及是否为有效的Git仓库。
• 日期格式无效：提供清晰的错误信息，并建议正确的格式。
• Git命令执行失败：捕获subprocess.CalledProcessError，并返回标准错误输出。
• 分支不存在：尝试回退到默认分支（main/master）。
• 无提交记录：生成一个友好的报告，说明在指定时间段内无活动。

Dependencies

• 外部命令：git
• Python库：gitpython(推荐，更安全易用)，jinja2(用于报告模板)

Version

1.0.0

### 3.2 编写要点与避坑指南 1. **Description要具体且包含意图**：不要只写“分析Git日志”。要说明“为谁”（项目负责人）、“解决什么问题”（贡献度评估、项目回顾）、“产出什么”（可读性高的报告）。这能帮助LLM更好地判断何时调用此技能。 2. **Input Parameters的Schema要严谨**： * **类型必须明确**：`string`, `integer`, `boolean`, `array`等。 * **可选与必选**：用 `“required”: [“repo_path”]` 或通过是否提供默认值来区分。 * **示例值（Example）是黄金**：为每个参数提供一个典型的示例值，能极大减少LLM调用时的参数格式错误。 * **描述清晰**：`since`参数写“起始日期”不够，要写“分析起始日期，格式为YYYY-MM-DD”。 3. **Output Specification是承诺**：明确成功和失败的不同返回结构。这关乎到Agent的后续流程控制（如根据`success`字段决定是否继续）。 4. **Function Signature是为LLM准备的“接口文档”**：很多框架（如OpenAI的Function Calling）需要这种严格的函数签名定义。确保参数名、类型、描述与上面的JSON Schema一致。 5. **Example Usage至关重要**：这是Few-Shot Learning的实例。提供一个从输入到输出的完整、典型的调用案例，能直接作为提示词的一部分，让LLM进行模仿学习，显著提升调用准确性。 6. **明确错误处理**：提前思考可能出错的环节，并在文档中说明。这既是开发指南，也能让最终用户（或集成者）了解如何应对异常。 > **避坑提示**：切忌在`Description`或参数描述中使用模糊、歧义的词汇。例如，避免“处理一些数据”、“在必要时”这样的表述。要使用“解析JSON格式的日志文件”、“当用户明确请求详细输出时”这样精确的描述。 ## 4. 从规范到代码：Skill的实现原理与核心逻辑 有了详细的`SKILL.md`作为蓝图，接下来我们深入实现层。一个Skill的实现，本质上是创建一个可靠的、可供AI调用的函数或服务。我们以Python为例，分解`GitCommitAnalyzer`的核心实现。 ### 4.1 技能实现的三种常见模式 根据技能复杂度，主要有三种实现模式： 1. **纯函数模式**：技能逻辑完全封装在一个Python函数内。适用于无状态、计算型的简单技能，如数据格式转换、简单计算。 ```python def calculate_metrics(data_list): # ... 计算逻辑 return metrics ``` 2. **类封装模式**：技能被封装在一个类中，适合需要维护内部状态、配置或复杂初始化的技能。 ```python class GitCommitAnalyzer: def __init__(self, git_bin_path=‘git’): self.git_bin = git_bin_path self.template_env = jinja2.Environment(...) # 初始化模板引擎 def analyze(self, repo_path, since, until, branch): # 使用self.git_bin执行命令 # 使用self.template_env渲染报告 return report ``` 3. **微服务API模式**：技能作为一个独立的HTTP服务（如FastAPI、Flask应用）运行。Agent通过发送HTTP请求来调用。这种模式解耦彻底，适合资源密集型、独立升级或跨语言调用的技能。 ```python # 在FastAPI中 @app.post(“/analyze”) async def analyze_git(request: GitAnalysisRequest): # 调用核心分析逻辑 return analysis_result ``` 对于我们的`GitCommitAnalyzer`，考虑到可能需要执行外部命令和模板渲染，使用**类封装模式**是一个平衡了组织性和复杂度的好选择。 ### 4.2 核心逻辑分解与安全实践 我们聚焦最关键的“执行Git命令并解析”部分。这里**安全性和鲁棒性**是首要考虑。 **不安全的做法（直接使用`os.system`或简单`subprocess.run`）：** ```python import subprocess # 危险！用户控制的输入直接拼接进命令 cmd = f“git -C {repo_path} log --since={since} --until={until}” result = subprocess.run(cmd, shell=True, capture_output=True, text=True) # 使用shell=True是高风险行为

安全且推荐的做法：

import subprocess import shlex from pathlib import Path class GitCommitAnalyzer: def _run_git_command(self, repo_path: Path, *args): “”” 安全地执行Git命令。 Args: repo_path: 仓库路径的Path对象。 *args: Git命令的参数列表，如 [‘log’， ‘--oneline’， ‘--numstat’] “”” # 1. 验证仓库路径是否存在且为目录 if not repo_path.exists() or not repo_path.is_dir(): raise ValueError(f“仓库路径不存在或不是目录： {repo_path}”) # 2. 构建命令列表，避免shell注入。使用‘git -C <path>’指定工作目录。 cmd = [‘git’， ‘-C’， str(repo_path.absolute())] + list(args) # 3. 执行命令，不启用shell try: result = subprocess.run( cmd, capture_output=True, text=True, encoding=‘utf-8’, timeout=30， # 设置超时，防止命令挂起 check=True # 如果命令返回非零状态码，抛出CalledProcessError ) return result.stdout except subprocess.CalledProcessError as e: # 这里可以记录更详细的错误日志 self.logger.error(f“Git命令执行失败。命令：{cmd}， 错误：{e.stderr}”) # 根据错误类型，抛出更具体的业务异常 if “not a git repository” in e.stderr.lower(): raise NotAGitRepositoryError(f“路径 {repo_path} 不是Git仓库”) else: raise GitCommandError(f“Git命令执行错误： {e.stderr}”) except subprocess.TimeoutExpired: raise TimeoutError(“Git命令执行超时”) def get_log_stats(self, repo_path, since, until): “””获取详细的日志和统计信息。””” # 使用安全的参数传递 log_args = [‘log’， f’--since={since}’， f’--until={until}’， ‘--oneline’， ‘--numstat’， ‘--pretty=format:%H|%an|%ae|%ad’] output = self._run_git_command(Path(repo_path)， *log_args) # ... 后续解析output return parsed_data

关键安全实践解读：

• 禁用shell=True：永远不要使用shell=True，它将命令字符串交给系统shell解释，如果repo_path被恶意注入为/dev/null; rm -rf /，后果不堪设想。使用列表形式传递命令和参数。
• 参数化构建命令：将动态部分（如路径、日期）作为列表的元素传递，而不是字符串拼接。
• 输入验证：在执行前验证repo_path的合法性和存在性。
• 超时控制：防止恶意或异常命令无限期运行。
• 精细化异常处理：捕获特定异常，并转换为对上层调用者友好的业务异常，而不是暴露底层的系统错误。

4.3 数据解析与报告生成

获取到原始的Git命令输出后，我们需要进行文本解析。这是一个典型的文本处理任务，需要严谨处理边界情况。

def parse_numstat_output(self, log_output: str): “”” 解析`git log --oneline --numstat`的输出。 输出格式通常为： 提交哈希 提交信息 文件1增加行数 文件1删除行数 文件1路径 文件2增加行数 文件2删除行数 文件2路径 ...（空行分隔下一个提交） “”” commits = [] current_commit = None for line in log_output.split(‘\n’): if not line.strip(): if current_commit: commits.append(current_commit) current_commit = None continue # 判断是否是提交概要行（包含‘|’分隔的元信息） if ‘|’ in line and len(line.split()) < 5: # 简单启发式判断 hash_part， author， email， date = line.split(‘|’， 3) current_commit = { ‘hash’: hash_part.split()[0]， # 取哈希部分 ‘author’: author， ‘date’: date， ‘files’: [] } elif current_commit is not None: # 处理文件变更行，例如 ‘10 5 src/main.py’ parts = line.split(‘\t’) if len(parts) == 3: add， delete， filepath = parts # Git用‘-’表示二进制文件 add_int = int(add) if add.isdigit() else 0 delete_int = int(delete) if delete.isdigit() else 0 current_commit[‘files’].append({ ‘file’: filepath， ‘additions’: add_int， ‘deletions’: delete_int }) # 处理最后一个提交 if current_commit: commits.append(current_commit) return commits

实操心得：解析命令行输出时，不要假设格式永远完美。添加足够的if判断和try-except来处理不规则的行（例如合并提交、重命名文件产生的特殊行）。使用split(‘\t’)比split()更可靠，因为Git的numstat默认用制表符分隔。对于二进制文件，additions和deletions字段会是‘-’，必须做类型转换处理，否则后续聚合计算会出错。

报告生成部分，可以使用Jinja2模板引擎，将数据与展示分离，使得支持markdown、html等不同格式变得非常容易。

from jinja2 import Environment， FileSystemLoader class ReportGenerator: def __init__(self, template_dir): self.env = Environment(loader=FileSystemLoader(template_dir)) def generate_markdown(self, summary_data, contributor_list): template = self.env.get_template(‘report.md.j2’) return template.render(summary=summary_data， contributors=contributor_list) # report.md.j2 模板文件示例 # # Git 代码贡献分析报告 # **仓库**：{{ summary.repo_name }} # **分析周期**：{{ summary.period }} # ## 概览 # - 总提交数：**{{ summary.total_commits }}** 次 # - 活跃贡献者：**{{ summary.total_contributors }}** 人 # ...

5. 技能集成与Agent框架协同原理

写好Skill的实现代码和SKILL.md后，下一步是让它能被AI Agent“看见”和“调用”。这里涉及到与Agent框架（如LangChain、AutoGen、Semantic Kernel等）的集成。其核心原理是工具调用（Function Calling）。

5.1 技能注册：让框架知晓技能的存在

无论哪个框架，都需要一个“注册”过程，将你的技能函数和它的描述（来自SKILL.md）告知框架的“工具管理模块”。

以LangChain为例（概念类似）：

from langchain.tools import Tool from my_skills.git_analyzer import GitCommitAnalyzer # 实例化你的技能类 analyzer = GitCommitAnalyzer() # 将技能函数包装成LangChain Tool git_analysis_tool = Tool( name=“GitCommitAnalyzer”， func=analyzer.analyze， # 指向实际的函数或方法 description=“”” 分析指定Git仓库的提交历史，生成代码贡献报告。 输入需要包含仓库本地路径(repo_path)，以及可选的起始时间(since)、结束时间(until)、分支(branch)和输出格式(output_format)。 “””， # 这里的描述会直接作为提示词给LLM args_schema=GitAnalysisInputSchema # 一个Pydantic模型，定义了输入参数的JSON Schema ) # 将Tool加入Agent的执行工具列表 agent_tools = [git_analysis_tool， ...其他工具...]

关键点：description和args_schema是LLM理解该工具的关键。description应简洁、准确地说明工具的功能和适用场景，args_schema则严格定义了参数的名称、类型和约束。这些信息最终会被框架组装到发送给大模型的系统提示词中。

5.2 大模型如何理解与调用技能：Function Calling流程拆解

当用户对Agent提出一个请求，如“帮我分析一下上个月项目A的代码提交情况”，背后发生的事是一个精妙的协作过程：

1. 意图识别与规划：Agent的“大脑”（通常是LLM，如GPT-4）接收到用户请求。LLM根据当前的对话历史和所有已注册工具的description，判断是否需要调用工具，以及调用哪个工具。它发现“分析代码提交情况”与GitCommitAnalyzer的描述匹配。
2. 参数提取与结构化：LLM根据args_schema，从用户的自然语言请求中提取结构化参数。它需要推断出repo_path（可能从上下文或项目配置中获取）、since（“上个月”需要被计算为具体的日期范围，如“2024-03-01”）、until（默认为今天）。这个过程依赖于LLM强大的上下文理解和推理能力。
3. 生成工具调用请求：LLM不会直接执行代码，而是输出一个格式化的请求，例如一个符合特定框架约定的JSON对象：

   { “action”: “GitCommitAnalyzer”， “action_input”: { “repo_path”: “/path/to/project-a”， “since”: “2024-03-01”， “until”: “2024-03-31” } }

4. 框架执行与返回：Agent框架（如LangChain的Agent Executor）接收到这个JSON，根据action找到对应的Tool对象，然后用action_input作为参数调用Tool.func（即我们的analyzer.analyze方法）。
5. 结果处理与回复生成：技能执行完毕后，将结果（我们定义的成功JSON）返回给框架。框架将这个结果作为新的上下文，再次喂给LLM。LLM综合工具返回的结果和原始问题，生成最终面向用户的自然语言回答，例如：“已为您分析项目A在上个月（3月1日至31日）的提交情况。期间共有42次提交，主要贡献者是张三...这是详细的报告。”

注意事项：LLM的参数提取并非100%准确。如果用户说“看看我们项目的近期动态”，LLM可能无法确定具体的since日期。因此，在Skill实现中，参数的默认值和容错性设计非常重要。同时，在description里给出清晰的示例（如“请提供类似/home/user/project的路径”）能显著提升提取准确率。

5.3 调试与验证：技能是否被正确调用

在集成阶段，最常见的两个问题是：1) LLM不调用你的技能；2) 调用时参数错误。

• 问题1：LLM不调用技能

  • 检查description：是否清晰、无歧义地描述了技能的功能和适用场景？是否包含了可能触发该技能的关键词（如“分析”、“报告”、“Git”、“提交”）？尝试让description更贴近用户可能使用的自然语言。
  • 检查工具列表：是否成功将工具注册到了Agent？可以在初始化后打印工具列表确认。
  • 简化测试：使用一个非常明确、直接的提示词测试，如“请使用GitCommitAnalyzer技能分析路径/test的仓库”。如果这样都不调用，说明集成或描述可能有根本问题。

• 问题2：参数提取错误

  • 检查args_schema：参数类型定义是否正确？string、integer要分清。可选参数是否设置了合理的默认值？
  • 提供更丰富的上下文：如果repo_path经常出错，考虑在对话开始时就让用户指定，或让Agent主动询问。
  • 使用Pydantic模型进行验证：在Skill函数的入口处，用Pydantic模型对输入参数进行强制验证和类型转换，将LLM可能提供的“昨天”这样的字符串，转换为具体的日期对象，增强鲁棒性。

  from pydantic import BaseModel， Field， validator from datetime import datetime， timedelta import dateparser # 一个强大的日期解析库 class GitAnalysisInputSchema(BaseModel): repo_path: str = Field(..., description=“Git仓库的本地绝对路径”) since: str = Field(default=“30 days ago”， description=“起始日期，如‘2024-01-01’或‘last Monday’”) until: str = Field(default=“today”， description=“结束日期，格式同上”) @validator(‘since’， ‘until’， pre=True) def parse_date_string(cls, v): if v in [“today”， “now”]: return datetime.now().strftime(“%Y-%m-%d”) if v in [“yesterday”]: return (datetime.now() - timedelta(days=1)).strftime(“%Y-%m-%d”) # 尝试用dateparser解析复杂字符串 parsed = dateparser.parse(v) if parsed: return parsed.strftime(“%Y-%m-%d”) # 如果已经是YYYY-MM-DD格式，直接返回 # 否则，让框架返回验证错误 return v

6. 高级话题：技能设计模式与性能优化

当你能熟练创建基础技能后，可以进一步思考如何设计更强大、更高效的技能系统。

6.1 复合技能（Meta-Skill）与技能编排

单一技能能力有限，真正的威力来自技能的组合与编排。你可以创建一个“周报生成技能”，它内部并不直接处理数据，而是像一个指挥家，依次调用多个底层技能：

1. 调用GitCommitAnalyzer获取代码提交摘要。
2. 调用JiraIssueFetcher（另一个技能）获取本周关闭的任务单。
3. 调用CalendarMeetingFetcher获取本周会议记录。
4. 最后，调用ReportSynthesizer技能，将上述所有输入整合，生成一份格式优美的Markdown周报。

这种模式将复杂任务分解，每个子技能职责单一，易于开发和测试。在Agent的规划（Planning）能力支持下，甚至可以实现动态的、基于目标的技能链自动组合。

6.2 技能的性能与缓存策略

一些技能可能执行耗时较长（如分析大型仓库），或者调用外部API有频率限制和成本。此时，引入缓存机制至关重要。

• 内存缓存：对于短时间内参数相同的重复请求，可以直接返回缓存结果。可以使用functools.lru_cache装饰器。

  from functools import lru_cache from datetime import datetime class GitCommitAnalyzer: @lru_cache(maxsize=128) def analyze(self, repo_path: str, since: str, until: str, branch: str): # 缓存键是 (repo_path， since， until， branch) 的元组 # 注意：repo_path必须是绝对路径，且since/until需要标准化（如都转为YYYY-MM-DD） normalized_since = self._normalize_date(since) # ... 实际分析逻辑

  注意：使用缓存时，要确保缓存键（函数参数）能够准确反映结果的唯一性。对于GitCommitAnalyzer，如果仓库有新的提交，缓存的结果就会过时。因此，需要设置合理的缓存过期时间（TTL），或者提供让用户强制刷新的参数（如force_refresh=True）。

• 持久化缓存：对于非常耗时的分析结果，可以存入数据库或文件系统。下次请求时，先检查是否有未过期的缓存结果。这尤其适用于那些基于固定时间范围（如“上周”、“上月”）的报表类技能。

6.3 技能的版本管理与依赖管理

当Skill数量增多，就需要像管理代码库一样管理它们。

• 版本化：在SKILL.md中明确Version字段。当技能接口（输入/输出）或行为发生不兼容变更时，必须升级主版本号（如从1.x.x到2.0.0）。这能让依赖该技能的Agent或工作流明确知晓升级风险。
• 依赖声明：在SKILL.md的Dependencies部分，不仅要写Python库，如果依赖特定版本的系统命令（如ffmpeg >= 4.3），也要写明。这有助于部署环境的准备。
• 集中注册与发现：可以建立一个内部的“技能市场”或注册中心，所有Skill的SKILL.md和入口函数在此注册。Agent系统启动时，从中心加载所需的技能，实现技能的动态发现和热更新。

从“会用”到“会写”，再到“写好”，是一个不断深入理解AI Agent运作原理、软件工程规范和具体业务需求的过程。一个设计精良的Skill，不仅是功能的实现，更是人机协作中一份清晰的契约。它要求开发者同时具备产品思维（明确功能边界和用户体验）、工程思维（确保代码健壮和安全）以及AI思维（如何让LLM更好地理解和使用）。当你开始为自己的Agent亲手打造技能时，你就真正掌握了驱动智能体行为的核心开关，能够解锁无限可能的应用场景。