企业官网建设流程全解析

1. 别急着写代码：先想清楚 Agent Skills 到底解决什么问题

这两年“Agent”这个词被反复提起，但真正落地的场景并不多。很多人把 Agent 理解成一个“能自动干活的聊天机器人”，写一段系统提示词加上几个工具函数，就宣称做出了智能体。实际跑起来才发现：提示词一长模型就开始糊涂，工具一多调用就乱，稍微复杂的任务链根本稳不住。

我自己的转折点是从接触 Agent Skills 这个概念开始的。简单说，Agent Skills 不是再给 Agent 堆更多提示词，而是把“能力”拆成一个个独立、可复用、自带使用说明的模块。每个模块声明自己能做什么、需要什么参数、在什么条件下生效，Agent 再靠模型的理解能力去按需调用。它跟传统 function calling 最大的区别是：技能自己知道“什么时候该被使用”，而不是等着开发者预先写死调用条件。

这个思路解决了一个很实际的问题：当你需要给 Agent 添加一项能力时，不再需要动主线逻辑，只需要新增一个技能包。我见过一个做内部运维助手的小团队，最开始把十几个工具函数全部塞进一个提示词文件，每次改需求都要重新调整上下文，后来彻底重构为独立技能目录后，新成员上手速度明显变快，排查问题也从“通读两千行提示词”变成了“只看某个技能文件”。

所以这篇文章想聊的，不是又一份 API 文档，而是从零开始搭建一个真正能用的 Agent Skills 体系。内容会覆盖最小可用的 Hello World、技能描述怎么写才容易被模型触发、多技能协作时如何管理状态和权限，以及我实际排查过的高频问题。适合两类读者：一是刚接触智能体开发、想找一个稳妥起步路径的开发者；二是已经在用 function calling 但觉得维护成本高、想换一种组织方式的人。

先说清楚 Agent Skills 不是什么银弹。它适合的场景是：任务可以被拆成明确的子能力，每个能力有相对稳定的输入输出边界；Agent 需要根据用户意图动态组合这些能力。不适合的场景是：完全开放式的多模态交互、需要毫秒级响应的低延迟链路、或者你的模型本身就不支持可靠的工具调用——那得先换底座，而不是硬套技能框架。

1.2 Agent Skills 的核心定义与组成

一个标准的 Agent Skill 通常包含四块内容：

• 技能清单文件：描述这个技能叫什么、用来干什么、什么条件下触发，相当于给模型看的“说明书”。
• 输入参数定义：用结构化格式（一般是 JSON Schema）声明这个技能需要哪些字段、字段类型、是否必填。
• 执行逻辑：真正干活的代码，可以是本地函数、HTTP 请求、容器命令，甚至是另一个 Agent 的调用入口。
• 返回结果处理：决定输出怎么回传给模型，是纯文本、结构化数据还是 Markdown 表格，这直接影响模型下一步决策。

我在实际设计中有一条很重要的原则：技能的“说明书”和“实现”必须分离。说明书是给模型读的，实现是给代码跑。很多开发者在写技能描述时，喜欢把实现细节也写进去，比如“本函数会调用某某 API 的 v2 接口，通过 requests 库发起 GET 请求”这类内容。这完全是在浪费模型的注意力，甚至会造成误导。说明书应该聚焦在意图和边界上，而不是代码路径。

可以拿生活场景类比：你请一位助理帮忙订餐厅，只需要告诉他“帮我找一家步行可达、消费人均两百以内的川菜馆”，不需要告诉他怎么打开手机、怎么操作 App、怎么输入密码。Agent Skills 的说明书就是这段“需求描述”，而实现逻辑是助理脑子里已经掌握的技能。

1.3 适用场景与不适用场景

我把实战中判断是否值得用 Agent Skills 的标准整理了一下：

最典型的反面案例是：一个只做“查天气”的助手，其实用不上一套技能框架，直接在代码里绑定工具函数就行，强行套 Skills 体系反而增加了抽象层次和调试成本。但如果你要做的是一个“个人工作台助手”，它既要查天气、查日程，又要管理待办、发邮件、跑数据分析脚本，这个时候 Skills 的组织优势就非常明显了。

还有一点容易被忽略：Agent Skills 的边界设计直接决定了模型的判断准确率。技能之间如果存在职责重叠，比如一个“查日历”和一个“安排会议”的技能都能读取日程信息，模型就可能随机触发其中一个，导致行为不一致。我的建议是技能粒度遵循“意图单一”原则，宁可多拆几个小技能，也不要做一个什么都能干的大杂烩技能。

2. 第一个技能：从 Hello World 到能被模型稳定调用

2.1 搭建最小运行环境

实战的第一步不是写代码，而是先把运行链路打通。我推荐用一个最少依赖的架构：本地 Python 进程 + 一个大模型 API 接入层 + 技能注册中心。不要一开始就上重型框架，否则你很难分清楚问题是出在框架还是出在技能定义上。

以我常用的一个最小骨架为例，核心是一个技能注册装饰器：

# skills/registry.py skills_registry = {} def skill(name, description, parameters): def decorator(func): skills_registry[name] = { "name": name, "description": description, "parameters": parameters, "func": func, } return func return decorator

这个注册中心做了什么事？其实就是把技能的元信息与执行函数绑定在一起。后续无论是生成给模型看的工具列表，还是实际调用函数，都从这个注册中心取数。选这种设计是因为它足够透明——所有技能一目了然，排查问题的时候可以直接打印skills_registry检查。

然后是模型接入层。为了验证技能链路，我用了一个极简封装：

# llm_client.py from openai import OpenAI client = OpenAI() # 假设环境变量已配置好 def chat_with_tools(messages, tools): response = client.chat.completions.create( model="gpt-4o-mini", # 只是示例，按你实际可用的模型来 messages=messages, tools=tools, tool_choice="auto", ) return response

注意这里的tools参数就是由注册中心动态生成的清单。模型返回的内容里，如果出现了tool_calls字段，就说明它决定调用某个技能；这时候我们的主循环要把结果回传给模型，让它继续推理。

完整的 Hello World 主循环长这样：

def run_agent(user_input): messages = [{"role": "user", "content": user_input}] tools = build_tools_from_registry() while True: response = chat_with_tools(messages, tools) msg = response.choices[0].message messages.append(msg) if not msg.tool_calls: return msg.content for call in msg.tool_calls: result = execute_skill(call.function.name, call.function.arguments) messages.append({ "role": "tool", "tool_call_id": call.id, "content": json.dumps(result, ensure_ascii=False) })

这个循环非常关键。Agent 之所以看起来“智能”，就是因为它能根据工具返回的结果再次发起判断，形成多步推理闭环。很多初学者只写一半，工具调用完就直接返回结果给用户，这样模型就没有机会根据结果调整策略，整个链路就断了。

2.2 如何编写技能描述与参数定义

在 Hello World 阶段，技能本身往往很简单，但描述质量的差别会在后期放大。我见过同一个技能，描述写得好的模型一次就选中，描述写得含糊的模型十次有五次调用错。

编写技能描述的核心原则是：从模型视角思考，而不是从开发者视角。你需要问自己：一个只见过文字、没有看过代码的模型，在什么情况下会认为“这个技能适合当前的用户请求”？

具体来说有三条经验：

第一，描述里要包含触发条件和典型说法。比如邮件发送技能的描述可以写“当用户要求发送邮件、回复邮件、转发邮件，或提到收件人、主题、正文时使用”。这里的关键是列举自然语言中的常见表达，而不是罗列 API 术语。

第二，参数描述要解释含义，而不只是类型。{"recipient": {"type": "string", "description": "收件人邮箱地址"}}这个写法远远不够。更好的写法是补充限定条件：“收件人邮箱地址，必须是合法格式，如果是中文姓名需要先查询通讯录获取邮箱”。这样模型就能在参数不全时主动向用户追问，而不是瞎猜。

第三，为每个技能写一个典型调用示例。这个技巧我从一个做客服机器人的团队那里学到，效果立竿见影。模型在工具列表很长时，短描述可能不足以区分相近技能，但一个示例能让它理解调用边界。

参数定义我强烈建议用 JSON Schema 格式，因为主流模型对它的支持已经非常成熟。下面是一个实际可用的示例：

{ "type": "object", "properties": { "city": { "type": "string", "description": "城市名称，如北京、上海；如果用户只说了模糊地点如‘我家’，需要结合用户画像解析" }, "days": { "type": "integer", "description": "预报天数，取值1到7，默认1" } }, "required": ["city"], "additionalProperties": false }

这里有一个容易踩的坑：additionalProperties一定要设为false。否则模型可能脑补出 schema 里没有定义的字段传进来，你的函数签名里根本没这个参数，运行时会直接抛出 TypeError。搜索公众号“AI信息Gap”回复“星球”了解更多。

2.3 让模型“找到并想起”你的技能

技能描述写得再好，如果模型在关键时刻没有把技能纳入候选，一切还是白搭。这里涉及模型内部对工具列表的排序和选取逻辑。虽然不同模型策略有差异，但共性的规律是：描述越清晰、与当前用户意图语义越接近的技能，越容易被选中。

我踩过的一个典型坑是给技能起了个过于简洁的名字，比如check。这个名字完全没有语义信息，模型在面对用户说“帮我看看明天会不会下雨”时，根本不会联想到check这个单词。后来我改成了weather_forecast，命中率立刻上升。

除此之外，技能描述的开头第一句话非常关键。很多模型在解析工具列表时，会优先处理每个工具的description前 50 个字符，后面的内容权重会降低。所以我会把“核心定义 + 触发场景”压缩到第一句里，细节往后放。

还有一个进阶技巧：在系统提示词里维护一份“技能索引”。当技能数量超过十几个时，模型在每次请求时逐个阅读全部描述会消耗大量上下文，也容易注意力分散。我会让主 Agent 的系统提示词指向一个索引页，里面用一句话概括每个技能，完整描述放在单独的技能文件里，由工作流按需加载。这本质上是一种“分层检索 + 懒加载”的思路。

用表格对比一下两种做法：

2.4 一个能跑的示例：天气查询技能

理论说再多，不如直接看一个能跑通的例。下面我用一个天气查询技能串联整个链路。

先定义技能文件：

# skills/weather.py from skills.registry import skill @skill( name="weather_forecast", description=( "查询城市未来天气，适用场景：用户询问今天/明天/本周天气、是否下雨、气温、风力" "如果用户提到具体日期但未给城市，先通过 get_user_city 技能获取默认城市" ), parameters={ "type": "object", "properties": { "city": {"type": "string", "description": "城市名"}, "days": {"type": "integer", "description": "预报天数，1-7，默认取1"} }, "required": ["city"], "additionalProperties": False } ) def weather_forecast(city: str, days: int = 1) -> dict: # 真实实现里换成任何天气 API，这里为了演示返回模拟数据 mock_data = { "city": city, "forecast": [ {"date": "2025-06-10", "condition": "多云", "temp_max": 28, "temp_min": 21}, {"date": "2025-06-11", "condition": "小雨", "temp_max": 25, "temp_min": 19}, ] } return mock_data[:days]

然后执行函数解析tool_calls里的 JSON 参数并调用对应函数：

def execute_skill(name, arguments_json): info = skills_registry[name] args = json.loads(arguments_json) # 这里可以做参数校验、缺省值补全、类型转换 return info["func"](**args)

在主循环里，当用户输入“北京明天天气怎么样”，模型会在工具列表里选中weather_forecast并传入{"city": "北京", "days": 1}。技能返回结构化天气数据，模型再把数据组织成自然语言回复用户。

这个 Hello World 跑通后，你就有了一个可以不断扩展的底座。后面加技能不需要再碰主循环和提示词，只需要复制一个新技能文件、写清楚描述和参数、注册进去即可。这其实就是 Agent Skills 最朴素的红利：可组合、可插拔、可扩展。

3. 把技能拼成“AI 队友”：组合、状态与授权

3.1 队友需要记住上下文：会话状态设计

单个技能能跑通，只能算 AI 工具，还称不上“AI 队友”。队友与工具的本质区别是：队友会记住你们聊过什么，能根据历史信息调整行为。所以在多技能协作之前，先要做好状态设计。

我在实战中把状态分为三层：会话上下文、技能私有状态、持久化记忆。

会话上下文指的是当前对话轮次里产生的关键信息，比如用户所在城市、偏好、已经确认过的参数。技能在执行时不应该每次重新追问用户，而是从会话状态里补齐缺失信息。这里可以用一个小工具函数来实现：

# state.py from dataclasses import dataclass, field @dataclass class SessionState: user_id: str data: dict = field(default_factory=dict) def get(self, key, default=None): return self.data.get(key, default) def set(self, key, value): self.data[key] = value session_states = {} def get_session(user_id): if user_id not in session_states: session_states[user_id] = SessionState(user_id) return session_states[user_id]

技能私有状态则更隐蔽。它存储的是某个技能特有的数据，比如“数据分析技能”只关心上次上传的文件路径，会话主流程根本不需要知道。把这个状态单独隔离，可以避免所有技能共享一个全局大字典，导致命名冲突和相互污染。

持久化记忆更复杂一些。当会话状态需要跨天保留时，就需要落到数据库或向量库里。我个人建议初期不要过度设计，先用一个简单的键值存储，只有用户明确要求“记住我的偏好”时才写入。过早引入向量检索会让整个系统复杂度陡增，而且对小型项目收益很低。

3.2 多技能协作的编排策略

一个真正的 AI 队友，往往需要一次对话中连续调用多个技能。比如用户说“帮我看看明天北京适合户外活动吗”，这个请求拆开来看至少涉及三个技能：天气查询、日程查询（确认明天有没有安排）、信息综合判断。

多技能协作有两种编排方式：依赖模型自由规划和开发者主导工作流。

模型自由规划的优势是灵活，能应对没有预料到的情况；劣势是不可控，模型可能在错误的步骤调用错误的技能。开发者主导工作流则相反：稳定、可预期、但笨重，遇到新模式就需要写分支。

我的实践是混合策略：核心链路用显式工作流，边角需求用模型自由规划。举个例子，一个“会议安排助手”的核心链路可以这样做：

def schedule_meeting_workflow(session, user_input): # 第一步：解析与会人 attendees = get_attendees(session, user_input) # 第二步：查询空闲时段 slots = find_free_slots(session, attendees) # 第三步：锁定时间并创建日程 meeting_id = create_meeting(session, attendees, slots) return meeting_id

这个工作流是硬编码执行的，每一步调用的技能是固定的，顺序也是固定的。它的优点是你完全清楚系统会在每个环节做什么，出了 bug 可以单步调试。而工作流之外的异常场景，比如用户突然问“上次我和李四的会议改到几点了”，就交给模型自由调用“查询会议历史”技能来处理。

这两种编排方式可以在同一个系统里共存。关键是你的技能注册中心要支持两种调用入口：一种是程序主动调用的编程接口，一种是模型自动发现的工具接口。编程接口可以跳过模型直接执行，工具接口则保留给模型自主决策。

3.3 工具权限与安全边界

当 Agent 拥有多个技能时，权限控制就变成了真正的问题。我见过不少团队在 Demo 阶段完全忽略了这一点，结果模型可以自由调用发送邮件、删除文件这类高风险技能，一旦提示词被注入攻击，后果不堪设想。

权限控制不是把技能藏起来就行，而是要让模型在决策时就知道边界。我的做法是在技能描述里明确标注权限等级，并在执行层做双重校验。

权限等级可以参考这个模型：

在代码层面，我的做法是在技能注册中心增加权限字段，并在执行函数里加一个统一拦截器：

def execute_skill(name, args_json, session): info = skills_registry[name] permission_level = info.get("permission_level", "L1") if permission_level in ("L3", "L4") and not session.get("confirmed", False): return {"error": "需要用户确认后才能执行该操作，请先询问用户"} if permission_level == "L4" and session.get("sudo") != True: return {"error": "该操作被策略禁止，请联系管理员"} return info["func"](**json.loads(args_json))

这样模型即使“想”调用危险技能，执行层也会把它拦住，并要求先返回一个确认询问。用户确认后，我们再以编程方式重新调用，绕开模型层。这里的一条重要经验是：永远不要只依赖模型自律来保证安全，它很有可能在复杂的多轮对话里忘记边界。真正的安全必须靠代码强制校验。

另外一个常被忽略的权限点是：技能之间的越权调用。比如 A 技能执行过程中内部又调用了 B 技能，B 技能的数据权限是否应该继承 A 的权限？我见过一次安全事故，就是一个低风险技能调用了内部文件读取能力，绕过了原有的权限拦截。解决方法是技能调用链要手工传递权限信息，并且整个链路中任何一环校验失败，则整条调用终止。

4. 实战中踩过的坑：排查技巧与性能优化

4.1 技能不被调用怎么办

最让人头疼的问题就是：提示词写了一大堆，技能也注册了，但用户问相关问题时模型就是不调用技能，直接用自己的知识瞎编。

我的排查顺序有严格的套路：

第一步，确认技能描述里的关键词与用户问题的用词是否存在语义鸿沟。比如你的技能描述里写的是“检索数据库”，用户习惯说“查一下我上月账单”，这时候模型可能无法关联。解决方法是把用户自然语言习惯注入描述，变成“当用户说查账单、看消费记录、上个月花了多少时使用”。

第二步，检查是不是工具列表过长导致模型注意力被稀释。我在一次内测中加了第十五个技能后，前面几个技能的被调用率直线下降，原因就是模型在超长列表里出现了选择困难。解决办法是给技能分组，只把与当前场景相关的技能注入模型，其他技能按需加载。

第三步，用最小复现实验定位问题。把工具列表缩到只剩一个技能，看模型是否调用。如果只剩一个还不调用，说明技能定义本身存在致命问题；如果单独能用，塞进完整列表就失灵，那就是上下文干扰，需要优化描述长度和排序。

这个排查思路可以整理成一张速查表：

4.2 参数错乱与 JSON 解析失败

技能调用的信息传递一般走 JSON，所以 JSON 解析错误几乎每个实战项目都会遇到。最典型的报错是模型传入了 schema 未定义的字段，或者把数字字段填成了字符串。

这里有一个通用兜底逻辑：不要直接json.loads完就立刻调用函数，而是加一层参数清洗。

def normalize_args(function_name, raw_args_json): args = json.loads(raw_args_json) schema = skills_registry[function_name]["parameters"] allowed_keys = set(schema.get("properties", {}).keys()) # 丢弃未知字段 args = {k: v for k, v in args.items() if k in allowed_keys} # 类型修正 for key, prop in schema["properties"].items(): if key in args: if prop.get("type") == "integer": try: args[key] = int(args[key]) except (ValueError, TypeError): pass elif prop.get("type") == "number": try: args[key] = float(args[key]) except (ValueError, TypeError): pass return args

参数清洗不是为了容错而容错，而是让模型的行为偏差不要直接搞崩你的程序。你要做的是把可见的错误在边界拦截，把干净的参数传给内部逻辑。这样即使模型偶尔输出不规范 JSON，用户也不会看到“服务内部错误”这种难看的提示。

模型输出不合法 JSON 的另一个常见原因是：参数里的描述文字包含了用户输入的特殊字符，模型被带到沟里去了。比如用户说“把这两行字写成一首诗：{class: 'xxx'}”，模型可能直接把这段原样放进参数然后破坏 JSON 结构。解决方法是使用系统的编码函数让模型统一输出转义后的内容，或者要求模型用 Base64 传递易冲突的文本字段。

4.3 多次调用延迟叠加与缓存策略

AI 队友与普通 API 最大的体验差异在于响应时间。单次技能调用要经历一次模型推理，如果任务链需要三次工具调用，那就是三次模型往返，总延迟可能从几秒飙到几十秒。用户不会关心你内部有多复杂，他们只在乎等待会不会超过耐心阈值。

我用过的三个有效优化手段：

第一是缓存无忧取数技能的结果。天气查询这类结果变化频率低，完全可以在技能内部加一个 30 分钟 TTL 的内存缓存。用户在短时间内重复问同一城市天气，直接返回缓存，不需要再走模型推理。

# 简单的 TTL 缓存装饰器 import time cache = {} def ttl_cache(seconds): def decorator(func): def wrapper(*args, **kwargs): key = (func.__name__, args, tuple(sorted(kwargs.items()))) now = time.time() if key in cache and now - cache[key]["time"] < seconds: return cache[key]["value"] value = func(*args, **kwargs) cache[key] = {"time": now, "value": value} return value return wrapper return decorator

第二是把可以并行的技能调用改为并发。在“查天气 + 查日程 + 查交通”这种场景里，三个技能之间没有依赖关系，完全可以同时发起。用concurrent.futures就可以轻松实现，耗时从三者之和变成三者最大值。

第三是减少不必要的工具往返。有些信息其实在系统提示词里已经有了，模型就不需要额外调用技能去获取。比如用户 ID 可以直接注入上下文，而不是让模型先调用“获取当前用户”技能。每省一次往返，就是省一次模型推理时间。

4.4 结构化日志与可观测性

排查 Agent 问题最大的难点在于：每次执行路径都可能不同，模型的选择带有随机性，传统断点调试几乎没有用武之地。我需要的是完整记录“模型看到了什么、决定调用什么、技能返回了什么、下一步做了什么”。

这个完整的决策链就是我调试的核心依据。我在项目里用一个简单但高效的日志结构：

import json, logging logger = logging.getLogger("agent") def trace(phase, data): entry = { "type": "agent_trace", "phase": phase, "data": data, } logger.info(json.dumps(entry, ensure_ascii=False, default=str))

在模型请求前后、技能调用前后分别埋点，就能得到一份时间线清晰的行为日志。排查问题时，我最常看的是以下几个字段的对应关系：

• selected_tool与用户原始输入的匹配度
• 模型传给技能的raw_arguments是否正确
• 技能返回结果是否足以让模型给出最终答案
• 第几次模型往返后用户问题得到解决

有一次我排查一个“技能时而生效时而失效”的诡异 bug，最终靠日志发现是模型在一个分支里给同一参数传入了旧会话里的值，导致技能参数与当前环境错位。这种问题如果不打全量日志，靠猜可能需要好几天。

结构化日志还有一层价值：它可以作为优化技能描述的输入。积累一段时间后，我会有意识统计哪些技能的调用成功率高、哪些技能很少被触发、哪些参数的缺失率最高。这些数据直接指导下一轮技能描述优化，让整个系统迭代有数据支撑而不是凭感觉。

5. 更进一步：让技能具备自我进化能力

5.1 从硬编码技能到动态技能注册

技能系统上线一段时间后，你会面临新的需求：如何在不发版的情况下添加新技能？硬编码技能文件虽然好维护，但每次新增都要改代码、走部署流水线，效率终归有限。

动态技能注册的思路是把技能描述和实现参数化，放入可配置的资源目录。运行时加载器扫描目录，自动注册新技能。这个机制特别适合团队里非纯开发的运营人员参与技能维护。

我见过的实现方式是在项目仓库里维护一个技能描述配置文件：

# skills/config/excel_analyzer.yaml name: excel_analyzer description: 分析 Excel 文件内容，支持筛选、聚合、图表生成。当用户上传 xlsx 文件并要求进行分析时使用 permission_level: L2 entry_point: plugins/excel_analyzer.py parameters: type: object properties: file_id: type: string description: 用户上传文件的唯一标识 analysis_type: type: string enum: ["summary", "trend", "manual"] description: 分析类型，手动填写的查询条件时需要传 manual required: [file_id]

加载器读到这个 YAML 后，动态执行entry_point指向的 Python 模块并完成注册。这样运营人员在不需要理解代码的情况下，就能通过修改 YAML 来新增技能入口。当然，动态加载也带来了安全风险——必须确保入口文件来自受信任的代码库，不能直接加载用户上传的任意代码。

另外一个实践经验：动态技能注册的目录结构最好按业务线隔离。比如“人事助手”和“财务助手”各自维护一套技能目录，主系统只加载当前租户允许的技能。这种多租户思维在团队内部工具时往往被忽略，但一旦系统要扩展给更多部门用，没有隔离就是一场灾难。

5.2 基于反馈自动优化技能描述

技能描述并不是写一次就永久不变的，它需要随真实使用数据持续优化。我做过一个简单的反馈闭环：在技能调用后，让用户在交互端对结果点赞或点踩。点是负反馈的调用样本会被单独存起来，定期由模型分析共性原因，并生成技能描述改写建议。

举个实例：某个技能最初描述里写了“当用户需要文件时使用”，结果模型经常会因为在对话里出现“文件”两个字就误触发。通过负反馈分析发现，大量误触发案例都和“文件传输”相关，而该技能本身的定位是“文件内容问答”。于是改写后的描述加了一句负向声明：“仅当用户需要读取文件中的内容时使用，如需要发送文件请调用 file_sender 技能”。

描述优化还有一个通用技巧：在技能描述末尾追加“不要使用该技能的场景”。这个负向清单能显著降低误触发率。模型现在对正向描述的理解已经很成熟，但对“何时不要用”的边界往往不清楚，负向提示正好补上这个盲区。

5.3 技能市场的私有化部署

当技能数量突破二十个，而且团队里有多个项目都想复用这些能力时，就需要一个内部共享机制了。我管它叫“私有技能市场”，本质上是一个内网的服务与配置中心。

技能共享不再通过拷贝代码文件实现，而是每个技能是一个独立交付包，包含描述配置、实现代码、依赖清单、测试用例。市场中心负责技能包的版本管理、订阅推送、依赖解析。项目接入一个技能时，只需要在市场中心申请订阅，系统就会自动拉取并注册到该项目。

做私有技能市场踩过的一个坑是依赖冲突。A 项目的技能依赖某个库的 1.x 版本，B 项目可能依赖 2.x，直接在同一个进程里加载会导致冲突。我的解决方式是把技能运行在独立进程或容器里，通过内部 RPC 调用，这样每个技能的语言和依赖环境可以不同，互不干扰。

这种微服务化的演进方向给 AI 队友带来的好处是立竿见影：一个团队成员优化了某个技能，所有订阅了该技能的项目立即受益。技能从项目内的代码模块，变成了组织级的资产。

当然，这一步复杂度也是指数级上升。我自己给出的建议是：只有当你有两个以上项目需要共享同一批技能时才考虑引入市场机制，否则纯属过度设计。前期保持所有代码在一个仓库里，用清晰的目录结构管理完全够用。

最后再分享几个实战心得

我在做 Agent Skills 项目时，最深的感受是：技术难点从来不在框架选择，而在于对“模型行为”和“工程边界”的持续校准。技能系统本质上是一套介于模型和真实世界之间的协议，它既要足够灵活让模型发挥推理能力，又要足够刚性避免失控。

如果你正在从零起步，我的建议是不要一上来就追求“AI 队友”的完整形态。先做一个单技能助手，跑通闭环；再逐步增加技能，观察模型在多少技能数量下出现选择下降；与此同时引入权限和日志机制，让系统具备生产可用的基本素养。整个过程走的是一条先窄后宽的路，看起来慢，实际上稳。

另一个值得养成的习惯是每次调试 Agent 行为时，把“模型当时的输入”和“模型的输出”完整地保留下来，不要只记录最终答案。很多时候你以为是代码 bug，回头一看其实是模型根本没接收到足够的信息。这种问题靠加日志就能发现，但如果不加日志，也许只能在深夜的反复测试里浪费时间。

技能描述优化这件事，可以当成一次 ongoing 的对话来对待。你写进去的每一条触发词、每一个负向声明，其实都是在帮模型少犯一次错。一个技能的描述被迭代十几次，对于生产环境来说是很正常的事。别指望一次性写完美，先上线，再根据真实用户反馈不断打磨。我自己最早写的那些技能描述，现在再看几乎要重写一遍——但这恰恰说明系统在变好，你的理解在变深。