企业官网建设流程全解析

1. 项目概述：一个被严重低估的“技能容器”概念

“agent-skills”这个词组乍看像技术黑话，但拆开来看——它既不是某个具体开源库的官方命名，也不是某家大厂刚发布的API产品名，而是一个正在快速凝聚共识的设计范式代号。我在过去两年里参与过三个不同领域的智能体（Agent）落地项目：某高校实验室的科研助手系统、某电商公司的客服意图增强模块、还有一个面向中小企业的自动化文档处理流水线。这三个项目在技术栈、团队规模、交付周期上差异极大，但最后都卡在同一个地方：当基础的LLM调用、工具编排、记忆管理都跑通后，真正决定系统能否“活起来”的，是那一层薄薄的、却极难标准化的“技能层”。

所谓 agent-skills，说白了就是让一个智能体能“做事情”的最小可复用能力单元。它不是Prompt模板，不是一段Python函数，更不是封装好的REST接口——它是三者的交集与升华。比如“从PDF中提取发票金额并校验格式”，这个动作背后需要PDF解析能力、正则匹配能力、数值合法性判断能力、错误重试逻辑、以及与用户对话状态的上下文绑定。把这些能力打包成一个带明确输入/输出契约、可独立测试、可版本管理、可被多个Agent按需调用的单元，才是真正的 agent-skills。

这个词之所以突然热起来，是因为大家终于意识到：光堆算力、调模型、写Prompt，解决不了工程化落地的“最后一公里”。你不能每次遇到新需求就重写一遍整个Agent流程；你也不能把所有逻辑都塞进一个巨型提示词里，指望大模型自己理解“先查数据库、再比对税率、最后生成Excel”。agent-skills 就是那个“螺丝钉”——它不耀眼，但没有它，整台机器转不起来。它适合两类人深度关注：一类是正在从Demo走向生产环境的AI工程师，另一类是想把AI真正嵌入业务流程的产品负责人。如果你还在用“让大模型直接回答”来应付所有需求，那这篇文章值得你花20分钟读完——因为接下来要讲的，不是怎么写更好的Prompt，而是怎么构建一套可持续演进的技能基础设施。

2. 核心设计思路：为什么必须放弃“单体Agent”，转向“技能驱动架构”

2.1 传统Agent开发的三大死循环

我见过太多团队在Agent项目初期信心满满，三个月后集体沉默。问题不出在模型能力上，而出在架构选择上。几乎所有踩坑的项目，都曾陷入以下三个典型死循环：

• Prompt膨胀陷阱：初始版本用5行Prompt搞定“查天气”，两周后变成87行，包含城市纠错、单位转换、多日预报摘要、用户偏好记忆等逻辑。一旦某条规则出错，整段Prompt要重测；新增一个“空气质量指数解读”功能，就得在87行里找位置插入，还可能破坏原有逻辑。实测下来，超过60行的Prompt，维护成本呈指数级上升，且无法做单元测试。

• 函数即技能的幻觉：有团队把每个工具调用封装成一个Python函数，比如get_weather(city)、summarize_pdf(pdf_path)。听起来很干净？问题在于：这些函数没有输入校验（传入空字符串怎么办？）、没有失败兜底（API超时后是重试三次还是降级返回“暂无数据”？）、没有可观测性（谁在什么时候调用了它？耗时多少？成功率如何？）。它们只是裸函数，不是可管理的技能。

• 状态耦合灾难：当Agent需要“先查订单，再判断是否可退货，最后生成退款话术”时，很多实现会把这三步写在一个长链条里，中间状态全靠全局变量或上下文字典传递。结果就是：退货逻辑一改，整个链条要回归测试；想单独测试“判断是否可退货”这个环节？得模拟前两步的所有输出，成本高到没人愿意做。

提示：这三个问题的本质，都是把“能力”和“流程”混在了一起。就像造汽车，不能把发动机、变速箱、方向盘焊死成一块铁疙瘩，再指望它能灵活适应越野、高速、城市拥堵等不同场景。

2.2 技能驱动架构的四个核心原则

基于上述教训，我们提炼出构建 agent-skills 的四条铁律，每一条都对应一个可验证的设计决策：

1. 契约先行（Contract-First）
   每个技能必须定义清晰的输入Schema（JSON Schema格式）和输出Schema。例如extract_invoice_amount技能的输入必须包含{"pdf_bytes": "base64_string", "page_range": "list"}，输出必须是{"amount": "float", "currency": "string", "confidence": "float"}。这个契约不是文档，而是运行时强制校验的约束。我们用Pydantic V2实现，启动时自动校验所有技能注册表，契约不匹配直接报错退出——宁可启动失败，也不让模糊契约埋下隐患。

2. 副作用隔离（Side-Effect Isolation）
   技能内部可以调用外部API、读写文件、执行SQL，但所有这些操作必须通过统一的“能力适配器”（Capability Adapter）进行。比如PDF解析不直接调用pypdf.PdfReader，而是调用adapter.pdf.parse(bytes)；数据库查询不写session.query(...)，而是调用adapter.db.query(sql, params)。这样做的好处是：测试时可轻松注入Mock适配器，生产环境可统一添加重试、熔断、日志埋点；更重要的是，当某天要迁移到新PDF库时，只需重写pdf.parse这一个适配器，所有依赖它的技能零修改。

3. 可观测性内建（Observability by Design）
   每个技能执行时，自动记录结构化日志：skill_name、input_hash（输入内容的SHA256）、duration_ms、status（success/error/time_out）、error_type（如果失败）。这些日志不走console，而是发往专用的OpenTelemetry Collector。我们用Grafana搭了个看板，能实时看到“validate_tax_id技能在过去1小时失败率突增至12%，错误类型集中为InvalidFormatError”，立刻就能定位是上游OCR识别质量下降，而不是技能本身bug。

4. 组合优于继承（Composition over Inheritance）
   绝对不用“继承BaseSkill类”这种设计。技能之间通过显式依赖声明关联。比如generate_refund_statement技能的元数据里声明"requires": ["get_order_details", "calculate_refund_amount"]。运行时调度器会自动检查依赖是否已注册、版本是否兼容。这带来两个关键优势：一是技能可独立升级（calculate_refund_amountv2.1修复了小数点精度问题，不影响其他技能）；二是支持动态技能加载——新上线的send_sms_notification技能，只要符合契约，老Agent无需重启就能发现并调用。

2.3 为什么不是微服务？也不是Serverless Function？

常有人问：“这不就是把技能做成微服务吗？”或者“直接用AWS Lambda部署每个技能不就行了？”答案是否定的。原因很实在：

• 微服务太重：为一个parse_date_string技能单独起一个Docker容器？启动延迟200ms+，网络调用开销50ms，还要搞服务发现、负载均衡、健康检查。而实际业务中，80%的技能执行时间在10ms以内，网络开销反而成了瓶颈。我们实测过，纯进程内调用 vs gRPC调用，P95延迟差4倍。

• Serverless冷启动不可控：Lambda的冷启动时间波动极大（100ms~3s），而Agent响应要求端到端<2s。更致命的是，冷启动期间无法执行任何逻辑，意味着你得预热、得保活、得设计降级策略——这些复杂度完全违背了“技能应简单可靠”的初衷。

我们的方案是：所有技能以Python包形式发布（pip install agent-skills-finance==1.2.0），Agent运行时动态加载。包内包含技能代码、契约定义、适配器绑定、测试用例。部署时，Agent镜像里只装基础框架，技能包按需pip install。这样既保持了进程内调用的极致性能，又获得了包管理带来的版本控制、依赖隔离、灰度发布能力。

3. 核心细节解析：一个真实技能的诞生全过程

3.1 从需求到契约：如何定义一个不可妥协的技能边界

我们以一个真实项目中的技能为例：enrich_customer_profile。背景是某SaaS公司想在销售线索分配前，自动补充客户官网、员工规模、行业分类等信息，提升销售跟进效率。

第一步不是写代码，而是开一场15分钟的“契约对齐会”。参会者只有三人：AI工程师、销售运营负责人、数据合规顾问。目标是敲定这个技能的输入输出，且必须达成书面共识。

• 输入：销售系统传来的原始线索数据，字段包括company_name（必填）、website（可选）、country_code（可选）。注意：这里明确约定website是“可选”，意味着技能必须能处理空值；country_code用ISO 3166-1 alpha-2标准（如"US"、"CN"），不是自由文本。

• 输出：一个严格结构化的对象，包含：

  { "enriched_fields": { "official_website": "string | null", "employee_count_range": "string (e.g. '1-10', '50-200') | null", "industry_category": "string (from predefined taxonomy) | null", "last_enriched_at": "ISO8601 timestamp" }, "confidence_score": "float (0.0-1.0)", "sources_used": ["crunchbase", "linkedin", "manual_input"] }

  关键点在于：industry_category必须来自预定义分类树（如["Technology", "Healthcare", "Finance"]），不允许返回"IT Services"这种自由文本；confidence_score要求算法可解释（比如基于数据源数量、字段匹配度加权计算）；sources_used必须精确记录实际调用的数据源，不能笼统写"public_data"。

注意：这个契约文档最终成为测试用例的唯一依据。任何偏离契约的实现，哪怕功能“看起来更聪明”，也会被CI流水线拒绝合并。我们吃过亏——早期有个技能返回了"estimated_revenue"字段，销售团队很喜欢，但三个月后发现该字段来源不稳定，导致大量误判。现在规则是：契约之外的字段，一律禁止返回。

3.2 技能实现：三层结构与适配器绑定

enrich_customer_profile的代码结构严格遵循三层：

• 顶层：技能入口（skill.py）
  只做三件事：校验输入契约、调用核心逻辑、格式化输出契约。不包含任何业务逻辑。

  from pydantic import BaseModel from agent_skills.core import Skill, register_skill class InputModel(BaseModel): company_name: str website: str | None = None country_code: str | None = None class OutputModel(BaseModel): enriched_fields: dict confidence_score: float sources_used: list[str] @register_skill( name="enrich_customer_profile", input_model=InputModel, output_model=OutputModel, version="1.3.0" ) def enrich_customer_profile(input_data: InputModel) -> OutputModel: # 1. 输入校验（由@register_skill自动完成） # 2. 调用核心逻辑 result = _core_enrich( company_name=input_data.company_name, website=input_data.website, country_code=input_data.country_code ) # 3. 输出格式化（确保符合OutputModel契约） return OutputModel(**result)

• 中层：核心逻辑（_core.py）
  纯业务逻辑，无I/O。所有外部依赖通过参数注入，便于单元测试。

  def _core_enrich( company_name: str, website: str | None, country_code: str | None, db_adapter=None, # 适配器注入点 web_adapter=None, crunchbase_adapter=None ) -> dict: # 步骤1：标准化公司名（去噪、补全缩写） normalized_name = _normalize_name(company_name) # 步骤2：并行查询多个数据源（适配器调用） sources = [] if crunchbase_adapter: cb_result = crunchbase_adapter.search_company(normalized_name, country_code) if cb_result: sources.append(("crunchbase", cb_result)) if web_adapter and website: # 从官网HTML中提取结构化信息 html = web_adapter.fetch(website) web_result = _parse_html_for_info(html) if web_result: sources.append(("manual_input", web_result)) # 步骤3：融合结果（加权投票+冲突解决） final_result = _fuse_sources(sources) return final_result

• 底层：适配器实现（adapters/）
  每个适配器是独立模块，负责与具体外部系统交互。

  # adapters/crunchbase.py class CrunchbaseAdapter: def __init__(self, api_key: str, timeout: int = 5): self.client = httpx.Client(timeout=timeout) self.api_key = api_key def search_company(self, name: str, country_code: str | None) -> dict | None: # 实际HTTP调用，含重试、熔断、日志 try: response = self.client.post( "https://api.crunchbase.com/api/v4", json={"query": {"name": name, "country": country_code}}, headers={"Authorization": f"Bearer {self.api_key}"} ) response.raise_for_status() return _transform_crunchbase_response(response.json()) except Exception as e: logger.warning(f"Crunchbase API failed for {name}: {e}") return None

这种分层让测试变得极其简单：

• 单元测试：Mock掉所有适配器，专注验证_core_enrich的融合逻辑；
• 集成测试：用真实适配器连接沙箱环境，验证端到端流程；
• 合约测试：用契约定义生成随机输入，验证技能是否始终返回合法输出。

3.3 版本管理与灰度发布：如何让技能升级不再提心吊胆

技能不是写完就扔，而是持续演进的。enrich_customer_profile从v1.0到v1.3，经历了三次重要升级：

• v1.0 → v1.1：增加对LinkedIn数据源的支持。改动仅限于adapters/linkedin.py和_core.py中的调用逻辑。由于契约未变（输入输出结构一致），所有下游Agent自动获得新能力，无需任何修改。

• v1.2：优化confidence_score计算算法，引入数据源可信度权重。这次契约变更了：输出中新增confidence_reasoning字段，说明得分依据。按照语义化版本规则，这是向后兼容的次要版本升级。Agent运行时检测到新版本，会自动启用，旧版仍保留供回滚。

• v1.3：因合规要求，移除对某第三方数据源的调用，并将industry_category分类树从12个扩展到37个。这是不兼容变更（breaking change），版本号升至2.0。此时，Agent不会自动升级，而是记录告警日志：“技能enrich_customer_profile v2.0已发布，但当前配置要求v1.x，请检查兼容性”。运维人员需手动确认并更新Agent配置。

灰度发布的实现非常轻量：我们在Agent配置中加入技能路由规则：

skills: enrich_customer_profile: default_version: "1.2.0" # 对10%的流量启用v1.3.0 canary_rules: - traffic_percentage: 10 version: "1.3.0" conditions: ["user_tier == 'enterprise'"]

所有技能调用都经过这个路由层，无需修改技能代码本身。实测下来，一个新技能版本从发布到全量，最快可在15分钟内完成，且全程可监控各版本的P95延迟、错误率对比。

4. 实操过程：从零搭建你的第一个agent-skills环境

4.1 环境准备：最小可行开发套件

别被“架构”二字吓住。搭建一个可运行的agent-skills环境，只需要5个命令。我们用Python 3.10+作为基础，所有依赖都控制在20MB以内，连Docker都不需要。

1. 初始化项目目录

   mkdir my-agent-skills && cd my-agent-skills python -m venv venv source venv/bin/activate # Windows用 venv\Scripts\activate pip install --upgrade pip

2. 安装核心框架
   我们使用自研的轻量框架agent-skill-core（已开源，MIT协议），它只做四件事：契约校验、适配器管理、技能注册、可观测性埋点。

   pip install agent-skill-core==0.8.2

3. 创建技能骨架
   框架自带CLI工具，一键生成标准结构：

   skill-init --name extract_email_from_text --version 1.0.0

   这会生成：

   skills/ └── extract_email_from_text/ ├── __init__.py ├── skill.py # 技能入口 ├── _core.py # 核心逻辑 ├── adapters/ # 适配器目录 │ └── __init__.py └── tests/ # 测试目录 └── test_skill.py

4. 编写你的第一个技能
   编辑skills/extract_email_from_text/skill.py：

   from pydantic import BaseModel from agent_skill_core import register_skill class InputModel(BaseModel): text: str class OutputModel(BaseModel): emails: list[str] count: int @register_skill( name="extract_email_from_text", input_model=InputModel, output_model=OutputModel, version="1.0.0" ) def extract_email_from_text(input_data: InputModel) -> OutputModel: import re # 简单正则，生产环境请用更健壮的邮箱验证库 pattern = r'\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b' emails = re.findall(pattern, input_data.text) return OutputModel(emails=emails, count=len(emails))

5. 运行测试与验证
   框架内置测试运行器，自动发现并执行所有技能测试：

   skill-test --verbose

   输出会显示：

   ✅ extract_email_from_text v1.0.0: PASSED (input: {'text': 'Contact us at support@example.com'}, output: {'emails': ['support@example.com'], 'count': 1})

实操心得：很多新手卡在第一步——纠结“该用FastAPI还是gRPC暴露技能”。记住：agent-skills 的本质是进程内能力复用，不是网络服务。除非你有跨语言调用刚需（比如Python Agent调用Go写的图像识别技能），否则永远优先选择进程内加载。网络层是给Agent对外提供服务用的，不是给技能之间通信用的。

4.2 技能注册与Agent集成：三行代码接入现有系统

假设你已有一个基于LangChain的Agent，现在想让它能调用我们刚写的extract_email_from_text技能。不需要重写Agent，只需三处修改：

1. 在Agent启动时加载技能包

   from agent_skill_core import load_skills_from_path # 加载本地技能目录 load_skills_from_path("./skills") # 或者从PyPI安装的包 # load_skills_from_package("agent-skills-text-utils==1.2.0")

2. 将技能注册为Tool（LangChain兼容）
   框架提供自动转换器：

   from agent_skill_core.langchain import SkillAsTool from langchain.agents import Tool # 自动将技能包装为LangChain Tool email_tool = SkillAsTool( skill_name="extract_email_from_text", description="Extract all email addresses from input text. Returns list of emails and count." ) tools = [email_tool, ...] # 其他工具 agent = initialize_agent(tools=tools, ...)

3. 在Prompt中声明技能能力
   LangChain的Agent Prompt需要明确告知LLM“你能调用哪些工具”。我们用框架的元数据自动生成这部分：

   from agent_skill_core import get_skill_descriptions # 获取所有已注册技能的描述列表 tool_descriptions = get_skill_descriptions() # 输出类似：["extract_email_from_text: Extract all email addresses from input text..."] # 注入到Agent Prompt中 prompt = ChatPromptTemplate.from_messages([ ("system", f"You are a helpful assistant. You have access to these tools: {tool_descriptions}"), ("human", "{input}"), MessagesPlaceholder("agent_scratchpad"), ])

整个过程，你没写一行HTTP代码，没配一个端口，没启一个服务进程。技能就像Python内置函数一样，被自然地编织进Agent的能力网络里。我们在线上环境实测，一个包含12个技能的Agent，从启动到就绪平均耗时1.2秒，内存占用稳定在85MB左右。

4.3 生产就绪配置：日志、监控与安全加固

开发环境跑通只是开始。生产环境必须考虑三件事：可观测性、稳定性、安全性。

• 日志结构化
  所有技能日志必须是JSON格式，包含固定字段：

  { "timestamp": "2024-06-15T08:23:45.123Z", "level": "INFO", "skill_name": "extract_email_from_text", "version": "1.0.0", "input_hash": "a1b2c3...", "duration_ms": 12.4, "status": "success", "output_size_bytes": 64 }

  我们用structlog替换默认logging，配置一行即可：

  import structlog structlog.configure( processors=[ structlog.processors.TimeStamper(fmt="iso"), structlog.stdlib.filter_by_level, structlog.stdlib.add_logger_name, structlog.stdlib.add_log_level, structlog.stdlib.PositionalArgumentsFormatter(), structlog.processors.StackInfoRenderer(), structlog.processors.format_exc_info, structlog.processors.UnicodeDecoder(), structlog.processors.JSONRenderer() # 关键：输出JSON ] )

• 监控指标暴露
  框架内置Prometheus指标收集器，暴露/metrics端点：

  • skill_execution_duration_seconds_bucket{skill="extract_email_from_text",le="0.01"}
  • skill_execution_total{skill="extract_email_from_text",status="success"}
  • skill_cache_hit_total{skill="get_order_details"}（如果技能启用了缓存）

  只需在Agent启动时启用：

  from agent_skill_core.metrics import start_metrics_server start_metrics_server(port=8000) # 暴露/metrics

• 安全加固要点
  技能虽小，但也是攻击面。我们强制三条红线：

  1. 输入长度限制：所有技能默认输入总长度≤1MB，超长则截断并记录告警。在@register_skill中可覆盖：max_input_size=5_000_000。
  2. 沙箱执行：对可能执行任意代码的技能（如execute_python_code），用pysandbox限制CPU/内存/网络访问。
  3. 敏感信息过滤：所有日志自动扫描常见敏感模式（身份证号、银行卡号、邮箱），匹配则替换为[REDACTED]。框架提供可插拔的过滤器链。

5. 常见问题与排查技巧实录

5.1 技能执行缓慢：不是模型慢，是适配器在“摸鱼”

现象：get_weather技能P95延迟突然从200ms飙升到3.2s，但LLM推理时间没变。

排查步骤：

1. 先看指标：打开Prometheus，筛选skill_execution_duration_seconds_bucket{skill="get_weather"}，确认是整体延迟升高，而非某次异常峰值。
2. 查日志：搜索get_weather.*duration_ms > 2000，发现大量日志中sources_used字段为空，且status为error。
3. 定位根源：查看错误日志详情，发现adapter.weather_api.call报错ReadTimeout。进一步检查，发现天气API服务商在凌晨2点例行维护，但我们的适配器没配置超时重试。
4. 修复方案：在adapters/weather.py中为HTTP客户端添加重试策略：

   from tenacity import retry, stop_after_attempt, wait_exponential @retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=1, max=10)) def call(self, city: str) -> dict: # 原有HTTP调用逻辑

实操心得：90%的技能性能问题，根源都在适配器层，而非核心逻辑。养成习惯：每次新增适配器，必须配置超时、重试、熔断三件套。我们用tenacity库，5行代码搞定企业级容错。

5.2 技能返回结果不稳定：契约松动引发的雪崩

现象：parse_date_string技能在测试环境100%成功，上线后部分用户收到空结果，且无错误日志。

根因分析：

• 技能契约定义output: {"parsed_date": "string | null"}，但未规定null的语义。
• 测试用例只覆盖了“能解析”的场景，没覆盖“完全无法解析”的边界。
• 上线后，遇到date_string="Q3 FY2024"这种非标准格式，技能返回{"parsed_date": null}，但下游Agent把它当作有效日期参与计算，导致业务逻辑错乱。

解决方案：

• 收紧契约：将输出改为{"parsed_date": "string", "is_parsed": "bool"}，强制要求即使失败也返回占位符（如"1970-01-01"）并设is_parsed=False。
• 补充边界测试：在tests/test_skill.py中加入：

  def test_parse_invalid_format(): result = extract_email_from_text({"text": "Q3 FY2024"}) assert result.is_parsed is False assert result.parsed_date == "1970-01-01"

• 上线前强制校验：CI流水线增加契约合规检查，用jsonschema验证所有测试输出是否符合最新契约。

5.3 多技能协同失败：依赖关系没理清的代价

现象：generate_report技能调用fetch_sales_data和calculate_kpi，但偶尔calculate_kpi收到空数据，导致报告生成失败。

深入排查：

• 查看generate_report的调用日志，发现它确实传入了数据。
• 再查calculate_kpi日志，发现其输入sales_records字段为空。
• 追溯fetch_sales_data输出日志，发现它返回了{"records": []}，但没记录“为什么是空”。

根本原因：fetch_sales_data技能的契约中，records字段定义为list，但没说明空列表的业务含义——是“今天没数据”，还是“查询失败”？下游技能无法区分。

修复路径：

• 升级契约：fetch_sales_datav2.0 输出增加status字段：

  { "records": [], "status": "no_data_today | query_failed | rate_limited", "error_message": "string | null" }

• 改造调用方：generate_report在调用fetch_sales_data后，必须检查status：

  sales_data = fetch_sales_data(...) if sales_data.status == "query_failed": raise RuntimeError(f"Failed to fetch data: {sales_data.error_message}")

注意：技能间的契约必须像API接口一样严谨。我们建立了一条铁律：任何返回集合（list/dict）的技能，必须同时返回状态码和错误详情。这增加了10%的开发量，但节省了90%的线上排查时间。

5.4 技能版本混乱：一次“小升级”引发的全线崩溃

现象：某天凌晨，所有Agent突然大量报错ValidationError: field required (type=value_error.missing)，错误指向enrich_customer_profile。

事故还原：

• 运维同学为修复一个低优先级bug，悄悄发布了enrich_customer_profile v1.2.1，并配置为default_version。
• 但v1.2.1的契约中，industry_category字段从string | null改为string（强制要求非空）。
• 所有依赖它的Agent，因输入数据中该字段为空，触发Pydantic校验失败。

亡羊补牢措施：

• 立即回滚：将default_version切回1.1.0。
• 建立发布门禁：CI流水线增加契约变更检测脚本，若检测到不兼容变更（如字段从可选变必填），自动阻断发布，并邮件通知架构师。
• 推行“契约变更评审制”：任何影响输入/输出结构的修改，必须提交PR，由至少两名资深工程师评审，并附带迁移方案（如“v1.1.0用户需在调用前确保industry_category有默认值”）。

这张表总结了我们踩过的坑与对应防护措施：

6. 进阶实践：让agent-skills真正成为你的核心竞争力

6.1 技能市场：内部复用的终极形态

当团队技能积累到50+个，手动管理就成了噩梦。我们搭建了一个轻量级“技能市场”（Skill Marketplace），它不是另一个平台，而是一套标准化工作流：

• 自动发现：每天凌晨，扫描所有Git仓库的skills/目录，提取@register_skill元数据，生成技能卡片。
• 智能推荐：当工程师在写新技能时，IDE插件自动提示：“检测到您在处理PDF文本，已有3个相关技能：parse_pdf_text（v2.1）、extract_tables_from_pdf（v1.4）、ocr_pdf_if_scanned（v3.0）”。
• 血缘追踪：点击任一技能，可查看“谁在用我”（下游Agent列表）和“我依赖谁”（上游适配器及技能）。

最实用的功能是“一键克隆”：看到validate_tax_id技能很赞，点一下“Clone to My Project”，框架自动：

• 创建本地技能目录
• 复制源码（不含测试）
• 修改@register_skill中的name为my_company_validate_tax_id
• 更新version为1.0.0
• 生成空白测试文件

这避免了“复制粘贴改名”带来的版本混乱。目前，我们内部技能复用率达67%，新项目平均节省2.3人日的重复开发。

6.2 技能即文档：用契约自动生成交互式文档

每个技能的契约（Pydantic Model）本身就是最好的文档。我们用pydantic-cli工具，自动生成三样东西：

• Markdown文档：skill-docs.md，包含输入/输出字段说明、示例、错误码。
• Postman Collection：可直接导入Postman，用于手工测试。
• TypeScript接口定义：供前端调用Agent时做类型检查。

更进一步，我们把技能文档嵌入到Agent的/health端点：

{ "status": "healthy", "skills": [ { "name": "extract_email_from_text", "version": "1.0.0", "description": "Extract all email addresses from input text...", "input_schema": { "type