尧图网站建设 
1. 这不是“技能清单”而是一次对Skill概念的外科手术式解剖你有没有在Agent开发文档里反复看到这个词——Skill它被塞进README、写在架构图角落、挂在API参数名里甚至成了团队内部黑话“这个需求得拆成两个Skill”“那个模块还没封装成Skill”。但没人告诉你它到底是什么为什么非得叫Skill它和Function、Action、Tool、Plugin、Capability这些词究竟差在哪更关键的是为什么90%的项目里写的所谓“Skill”其实根本不是Skill只是披着马甲的函数调用我做过17个不同行业的Agent项目从金融风控对话引擎到工业设备远程诊断系统从教育领域自适应学习路径生成器到医疗影像报告辅助撰写工具。踩过最深的坑不是模型不准、不是接口超时而是——团队把一堆零散API硬塞进一个叫skill.py的文件里起名叫“Knowledge Retrieval Skill”结果上线三天就因并发瓶颈崩掉三次运维日志里全是“agent execution terminated due to error.”。后来复盘才发现问题根本不在于代码而在于我们连“Skill”这个词的工程语义边界都没划清。这恰恰是当前Agent开发中最危险的认知盲区把抽象能力单元Skill当成技术实现容器文件/函数/类。Skill不是命名习惯不是目录结构更不是营销话术。它是一个有明确定义、可验证边界、需独立演化的工程契约。它必须同时满足三个刚性条件可观测的行为契约、可替换的实现契约、可组合的接口契约。缺一不可。否则你写的不是Skill是技术债的压缩包。这篇文章不教你如何写一个Skill文件也不罗列几十种Skill框架选型。我要带你做的是一次彻底的“去魅”——用真实项目中的代码片段、架构决策记录、压测数据、线上报错日志一层层剥开Skill的皮、肉、骨、髓。你会看到为什么skill.md不是文档格式而是能力声明协议为什么SKILL.md目录设计本质是能力拓扑图谱为什么ponytail skill或taste skill这类网络热词背后暴露出的是开发者对Skill粒度的集体误判以及最关键的一点——“滥用Skill”的本质是用粗粒度封装掩盖细粒度设计缺失。适合谁读如果你正在写Agent哪怕只写了三行def get_weather()如果你在review同事的PR看到skill/目录下塞了8个.py文件却说不清每个文件解决什么问题如果你在设计agent.md架构文档纠结该把“用户画像生成”放在core/还是skill/或者你刚听说pi agent或hermes agent想搞懂它们凭什么敢叫“Agent”而不是“Bot”——那这篇就是为你写的。它不假设你懂LangChain不要求你会写Verilog但要求你愿意放下“我只要跑通就行”的心态真正思考我交付的究竟是一个可维护的能力单元还是一团随时会散架的胶水代码2. Skill的本质一场关于“能力契约”的工程革命2.1 Skill不是功能而是能力契约——从“能做什么”到“承诺做什么”很多人第一次接触Skill是从某个Agent框架的文档里看到“请为你的Agent定义Skill”。于是立刻打开编辑器新建weather_skill.py写个get_weather(city)函数再加个skill装饰器大功告成。但这种做法本质上是在用实现细节冒充能力定义。真正的Skill始于一份白纸黑字的能力契约Capability Contract。什么叫能力契约它回答三个问题行为契约Behavioral Contract这个Skill对外承诺提供什么可观测行为比如“给定城市名返回未来24小时温度、湿度、降水概率响应时间≤800ms错误率0.5%”。注意这里没有提Python、没有提OpenWeather API、没提缓存策略——这些全是实现细节契约里只写用户能验证的结果。实现契约Implementation Contract这个Skill的内部实现必须满足哪些约束比如“不依赖外部数据库连接池”“所有HTTP调用必须带timeout3s”“失败时必须返回标准Error Schema包含code、message、retry_after字段”。这些约束保证Skill可以被安全替换而不影响上层逻辑。接口契约Interface Contract这个Skill通过什么标准化方式被调用和集成比如“必须提供execute(input: dict) - dict方法”“输入必须符合WeatherInputSchemaJSON Schema”“输出必须符合WeatherOutputSchema”。这不是Python签名而是跨语言、跨框架的协议。我参与过一个政务热线Agent项目初期团队把“政策条款查询”写成一个policy_search_skill.py里面混着ES查询、PDF解析、关键词高亮。上线后发现当政策库从Elasticsearch迁移到向量数据库时整个Skill要重写导致Agent核心流程停摆3天。后来我们重定义了PolicySearchSkill契约行为契约输入政策编号或关键词返回匹配条款列表含原文段落、生效日期、废止状态P95延迟≤1.2s实现契约禁止直接访问任何存储层必须通过PolicyDataSource抽象接口所有文本处理必须使用预编译正则表达式接口契约输入为{query: string, limit: int}输出为{items: [{text: string, effective_date: date, status: enum}]}。结果呢迁移向量库时只需重写PolicyDataSource的两个方法Skill文件本身一行未动Agent无感切换。这就是契约的力量——它把变化关进笼子。提示判断一个东西是不是真正的Skill就看它能否脱离当前代码库独立存在。如果把它复制到另一个Agent项目里需要改10处import路径、3个配置常量、2个全局变量那它就不是Skill只是个耦合体。2.2 Skill与Function/Tool/Plugin的根本区别粒度、契约与演化权网络热词里常把Skill和Tool、Plugin混用比如“Chrome查看Markdown插件”“Skill Recorder”“Skill插件”。这是典型的术语污染。它们表面相似内核迥异维度Function函数Tool工具Plugin插件Skill能力单元粒度单一操作如len()独立功能如git commit宿主扩展如VS Code插件解决特定领域问题的完整能力链如“用户意图澄清”契约强度无契约仅签名弱契约约定输入输出格式中等契约遵循宿主API强契约行为实现接口三重约束演化权随代码库整体演进可独立更新但影响宿主宿主控制更新节奏拥有独立生命周期可灰度发布、A/B测试、熔断降级可组合性仅能顺序调用需手动编排依赖宿主调度原生支持组合Skill A调用Skill B自动处理上下文传递、错误传播、超时继承举个真实案例我们为某电商Agent设计“价格比对”能力。最初用Function实现def compare_price(sku_list)结果发现它无法处理“用户说‘看看iPhone15和华为Mate60哪个便宜’”这种模糊输入——需要先做实体识别、再查SKU、再调价、再生成对比文案。于是有人提议做成Tool封装成CLI命令。但CLI无法嵌入Agent的推理循环每次调用都要进程fork延迟飙升。最后我们定义PriceComparisonSkill输入自然语言查询如“对比A和B的价格”输出结构化比对结果 自然语言摘要内部自动编排EntityRecognitionSkill→ProductLookupSkill→PriceFetchSkill→SummaryGenerationSkill。这个Skill可以被其他Skill调用比如PurchaseRecommendationSkill需要它也能被人工审核流调用还能单独压测。它的版本号v2.1.0独立于Agent主版本演进上周我们灰度发布了v2.2.0新增汇率换算老版本继续运行零影响。注意很多项目把markdown相关操作堆成MarkdownSkill这是典型滥用。Markdown是格式规范不是能力领域。真正Skill应该是DocumentFormattingSkill负责排版、ContentExtractionSkill从MD提取关键信息、CrossReferenceResolutionSkill解析[link](#anchor)。把语法细节当能力就像把“用筷子夹菜”叫“进食Skill”而忽略“判断食物是否变质”“协调咀嚼与吞咽”这些真正的能力。2.3 Skill.md不是文档而是能力声明协议的机器可读载体网络热词里高频出现skill.md、agent.md、SKILL.md目录设计很多人以为这只是个文档习惯。错。SKILL.md是能力声明协议Capability Declaration Protocol的落地形式它的存在意义是让Skill从“人可读”走向“机器可读、可验证、可编排”。一个合规的SKILL.md必须包含且仅包含以下结构我们团队已沉淀为CI检查项--- name: PolicySearchSkill version: 2.3.0 category: knowledge_retrieval tags: [government, regulation, search] description: 根据政策编号或关键词检索匹配条款并返回结构化结果 --- ## Behavior Contract - Input: {query: string, limit: integer} - Output: {items: [{text: string, effective_date: date, status: active|repealed|amended}]} - SLA: P95 latency ≤ 1.2s, error rate 0.3% ## Implementation Contract - Must use PolicyDataSource interface for all data access - Text processing must use pre-compiled regex patterns (see regex_patterns.py) - No direct database connections allowed ## Interface Contract - Method: execute(input: dict) - dict - Input Schema: https://schema.example.com/skill/policy_search_input.json - Output Schema: https://schema.example.com/skill/policy_search_output.json ## Dependencies - EntityNormalizationSkill1.5.0 - DocumentIndexingServicev3.2.0 ## Test Cases | Input | Expected Output | Status | |-------|-----------------|--------| | {query: 国发〔2023〕12号} | {items: [...]} | ✅ | | {query: 税收优惠, limit: 5} | {items: [...], count: 5} | ✅ |这个文件的作用远超文档CI阶段自动校验name是否唯一、version是否符合语义化规则、Input SchemaURL是否可访问部署阶段Agent Runtime读取Dependencies自动构建调用图谱检测环形依赖监控阶段将SLA指标注入Prometheus当error rate超阈值时自动触发Skill熔断治理阶段tags字段支持按government标签批量查询所有政务相关Skill评估合规风险。我们曾用SKILL.md发现一个严重问题某FinancialReportSkill声明依赖TaxCalculationSkill1.0.0但实际代码调用了TaxCalculationSkill1.2.0的新接口。CI检查失败强制团队修复契约——避免了线上因版本不匹配导致的财报计算错误。实操心得别手写SKILL.md我们用skill-decl-gen工具基于Python类型注解自动生成骨架。例如from pydantic import BaseModel class PolicySearchInput(BaseModel): query: str limit: int 10 class PolicySearchOutput(BaseModel): items: List[PolicyItem]运行skill-decl-gen policy_search.py自动生成带Schema链接、测试用例模板的SKILL.md。人力只聚焦在填充Behavior Contract的SLA和Implementation Contract的约束条款上。3. Skill的工程实现从契约到代码的四步炼金术3.1 第一步契约具象化——用Schema和SLA把模糊需求钉死“做一个搜索Skill”是无效需求。真正的起点是把模糊描述转化为可验证的契约条款。我们团队的标准流程是“三问法”行为可测吗错误表述“能搜政策” → 正确表述“输入政策编号100%返回原文段落输入关键词召回率≥92%准确率≥88%”。计算依据基于历史咨询日志抽样1000条统计用户真实查询模式和期望结果。召回率返回的相关条款数/所有相关条款总数准确率返回的相关条款数/返回的总条款数。实现可约束吗错误表述“用ES搜” → 正确表述“所有数据访问必须通过PolicyDataSource.get_by_id()或PolicyDataSource.search()禁止直连ES客户端”。约束理由保证未来可切换为向量库且避免SQL注入式ES查询如*:*。接口可组合吗错误表述“返回JSON” → 正确表述“输出必须符合PolicySearchOutputSchema且items数组中每个元素必须包含text、effective_date、status字段status枚举值限定为active/repealed/amended”。组合价值下游PolicySummarySkill可安全假设字段存在无需if status in item防御性编程。以DocumentFormattingSkill为例处理用户提交的原始文本生成高颜值Markdown报告行为契约输入纯文本输出符合report_v2规范的Markdown含标题层级、表格对齐、代码块语法高亮渲染后PDF页数误差≤±0.5页实现契约禁止使用pandoc因license冲突必须用mistunepygments表格渲染必须支持colspan/rowspan接口契约输入{content: string, template: report_v2}输出{markdown: string, metadata: {page_count: float}}。这个契约让前端、后端、QA有了共同靶心。测试不再问“格式对不对”而是跑自动化脚本# 生成PDF并计页数 pandoc input.md -o output.pdf pdfinfo output.pdf | grep Pages: | awk {print $2} # 对比预期页数允许±0.53.2 第二步骨架生成——用声明驱动开发DDD规避实现陷阱拿到SKILL.md后绝不直接写业务逻辑。我们采用声明驱动开发Declarative-Driven Development先生成强制骨架创建skill/目录结构policy_search/ ├── __init__.py ├── skill.py # 主入口仅含execute()和契约校验 ├── core/ # 业务逻辑无外部依赖 │ ├── retriever.py # 纯函数输入dict输出list[dict] │ └── normalizer.py # 纯函数输入str输出标准化query ├── adapters/ # 外部依赖适配层 │ ├── es_adapter.py # 封装ES客户端实现PolicyDataSource接口 │ └── cache_adapter.py # 封装Redis实现CacheProvider接口 ├── tests/ # 契约测试非单元测试 │ └── test_behavior.py # 验证SLA、输入输出格式 └── SKILL.md # 契约文件skill.py骨架强制规则必须继承BaseSkill提供统一execute()、health_check()、metrics()execute()第一行必须调用self._validate_input(input)校验是否符合SKILL.md声明的Input Schema最后一行必须调用self._enforce_output(output)确保输出字段、类型、枚举值全合规禁止在skill.py里写任何业务逻辑所有计算必须下沉到core/。这个骨架看似繁琐却堵死了90%的滥用无法把数据库连接写在execute()里因为adapters/层强制隔离无法返回缺失status字段的JSON因为_enforce_output()会抛异常无法绕过Schema校验因为_validate_input()是硬性前置。踩过的坑某次紧急上线同事为省事在skill.py里直接调用requests.get()。结果压测时发现连接池耗尽但SKILL.md里写的“不依赖外部连接池”契约形同虚设。后来我们加了静态检查grep -r requests\. skill/policy_search/ exit 1CI直接失败。3.3 第三步契约测试——用生产环境数据反向验证Skill可靠性很多团队的Skill测试停留在“单元测试覆盖80%”。这毫无意义。真正的Skill测试必须是契约测试Contract Testing用生产环境的真实流量样本验证Skill是否履行了SKILL.md里的每一项承诺。我们的测试流程分三层Schema层测试工具jsonschemaopenapi-spec-validator操作下载SKILL.md里声明的Input/Output Schema用10万条历史请求/响应数据批量校验。发现问题曾发现PolicySearchSkill的Output Schema允许status为null但实际业务要求必填。修正Schema后上游Agent自动捕获空值并告警。SLA层测试工具locustprometheus-client操作模拟1000QPS持续10分钟监控P95延迟、错误率、GC次数。关键参数--users 1000虚拟用户数--spawn-rate 100每秒启动100用户--run-time 10m运行10分钟结果解读若P95延迟超1.2s不是调优代码而是降级Skill如关闭高亮功能或扩容adapters/es_adapter.py的连接池。行为层测试工具pytestdiff-match-patch精准比对文本操作用真实用户咨询语句如“国办发〔2022〕25号文关于新能源汽车补贴的规定”作为输入比对输出是否包含所有关键条款、日期是否准确、状态是否正确。独家技巧对Markdown输出我们用mistune解析后比对AST节点而非字符串——避免因空格、换行差异导致误报。实操心得测试数据必须来自生产环境脱敏库而非人工构造。我们用traffic-replayer工具从Kafka消费真实请求自动过滤敏感字段如身份证号、手机号生成测试数据集。人工构造的数据永远覆盖不了长尾case比如用户输入“国发〔2023〕12号修订版”而契约里没定义“修订版”的解析规则。3.4 第四步部署与治理——让Skill真正拥有独立生命写完代码、通过测试只是开始。Skill的工程价值在于它能独立部署、独立监控、独立演进。我们用Kubernetes Operator实现Skill生命周期管理独立部署每个Skill打包为Docker镜像镜像Tag与SKILL.md的version严格一致如policy-search-skill:v2.3.0。K8s Deployment的imagePullPolicy设为IfNotPresent避免重复拉取。独立监控Prometheus抓取/metrics端点指标前缀为skill_policy_search_如skill_policy_search_latency_seconds_bucket。Grafana看板按Skill分组P95延迟超阈值时自动创建Jira工单并负责人。独立演进灰度发布新版本先路由1%流量监控error_rate和latency达标后逐步放量A/B测试PolicySearchSkillv2.3.0vsPolicySearchSkillv2.4.0新增语义搜索用user_id % 100分流熔断降级当error_rate 5%持续2分钟自动切换到PolicySearchSkillv2.2.0稳定版并发送Slack告警。最关键的治理动作是Skill拓扑图谱Skill Topology Map。我们用skill-graph-builder扫描所有SKILL.md的Dependencies字段自动生成可视化图谱节点Skill名称版本边依赖关系调用频次来自APM埋点颜色健康状态绿色SLA达标红色错误率超限。这张图让我们一眼看出DocumentFormattingSkill是中心节点被12个Skill依赖它的故障会导致整个Agent报告生成链路中断。因此我们给它配置了双倍CPU资源和独立Pod反亲和性。注意agent execution terminated due to error.这类报错90%源于Skill依赖链断裂。比如PolicySearchSkill依赖EntityNormalizationSkill但后者因内存泄漏OOM导致前者调用超时。拓扑图谱熔断机制让问题定位从“大海捞针”变成“顺藤摸瓜”。4. Skill滥用的典型场景与避坑指南从“写得出来”到“用得安心”4.1 场景一把“技术实现”当“能力定义”——目录即深渊现象skill/目录下塞满文件db_query.py、http_client.py、file_parser.py、string_utils.py……美其名曰“模块化”。这是最普遍的滥用本质是用文件系统代替架构设计。危害无法评估能力边界file_parser.py既解析PDF又处理Excel当PDF解析出bug整个Skill停摆无法独立演进升级Excel解析库必须测试所有用到file_parser.py的Skill无法组合复用DocumentFormattingSkill想用PDF解析却要引入整个file_parser.py带上不必要的Excel依赖。避坑方案按能力域拆分而非技术栈DocumentParsingSkill专注“从任意格式提取结构化文本”输入{url: string}输出{text: string, pages: int, tables: list}TableRenderingSkill专注“将表格数据渲染为Markdown”输入{data: list[list]}输出{markdown: string}ImageCaptioningSkill专注“为图片生成描述”输入{image_url: string}输出{caption: string}。每个Skill有自己的SKILL.md自己的CI流水线自己的监控看板。DocumentFormattingSkill按需组合它们而非继承它们的代码。实操心得新项目启动时我们用“能力风暴”Capability Storming工作坊白板上写满用户真实任务如“把扫描件转成可搜索PDF”“从会议纪要提取待办事项”然后投票选出Top5高频任务每个任务定义一个Skill。绝不从技术组件出发4.2 场景二把“功能聚合”当“能力抽象”——Markdown不是Skill而是载体现象网络热词里“markdown”高频出现很多人认为“支持Markdown”就是一个Skill。错。Markdown是序列化格式不是能力。真正的Skill是ContentExtractionSkill从Markdown中提取标题、章节、代码块、表格CrossReferenceResolutionSkill解析[链接](#锚点)并验证目标是否存在DocumentVersioningSkill管理同一文档的多个Markdown版本支持diff和回滚。滥用后果MarkdownSkill越写越大最终变成“万能解析器”违反单一职责当用户需要“从Markdown提取数学公式”却发现MarkdownSkill里混着LaTeX解析、MathML转换、图片渲染改一处崩一片。避坑方案用Schema定义能力边界为ContentExtractionSkill定义Input Schema{ type: object, properties: { content: {type: string}, extract_types: { type: array, items: {enum: [heading, code_block, table, math_formula]} } } }这样用户明确知道这个Skill只做提取不做渲染只支持指定类型不保证解析所有Markdown扩展语法。提示markdown preview enhanced插件出乱码根源常是Skill层未处理script标签或iframe——这不是插件问题而是ContentExtractionSkill的契约没声明对HTML片段的处理策略。应在SKILL.md的Implementation Contract里写明“禁止输出含script的HTML对iframe返回占位符”。4.3 场景三把“AI调用”当“Skill封装”——Agent不是魔法盒Skill不是胶水现象ai_agent_verilog_code、agent画图这类热词暗示一种危险倾向把大模型API调用简单包装成Skill。比如CodeGenerationSkill内部就是openai.ChatCompletion.create()。危害无法控制成本一次调用可能消耗10倍token却无预算监控无法保障质量模型输出不稳定但Skill契约承诺“返回可执行代码”无法降级模型服务宕机Skill直接失败无备选方案。避坑方案Skill必须包含“人类可理解的保底逻辑”CodeGenerationSkill的契约行为输入自然语言描述返回Python代码若模型失败返回{fallback: true, suggestion: 请检查语法或提供更多上下文}实现先用规则引擎匹配常见模板如“排序数组”→sorted(arr)命中则秒回未命中再调模型接口输出必须含code字段模型结果和confidence字段0.0~1.0下游Skill可据此决定是否信任。我们为VerilogCodeGenerationSkill实现了三层保底规则层匹配“D触发器”“计数器”等关键词返回预置代码模板检索层在历史成功案例库中检索相似描述返回最佳匹配模型层调用模型但强制temperature0.2降低随机性并用code_linter校验语法。结果85%请求走规则层平均延迟从1200ms降至45ms成本下降92%。实操心得所有AI-Skill必须在SKILL.md里声明fallback_strategy和confidence_threshold。我们规定confidence 0.7时必须触发人工审核流而非直接返回低置信度结果。4.4 场景四把“目录结构”当“能力治理”——skill.md目录设计的真相现象看到skill/目录就以为完成了Skill化。更甚者模仿pi agent官网的目录建skill/core/、skill/utils/、skill/tests/却没SKILL.md。危害目录成了“技术债务仓库”没人敢删utils/里的旧函数新人以为core/是核心逻辑实则混着数据库连接和日志打印无法审计想知道“哪些Skill访问了用户隐私数据”只能grep全代码库。避坑方案目录即契约文件即证据skill/目录下每个子目录必须对应一个SKILL.mdSKILL.md必须通过CI检查Schema校验、版本语义化、依赖可解析core/目录只允许存在纯函数无IO、无全局状态adapters/目录只允许存在外部依赖适配器。我们用dir-validator工具强制# 检查每个skill子目录是否有SKILL.md find skill/ -mindepth 1 -maxdepth 1 -type d | while read d; do if [ ! -f $d/SKILL.md ]; then echo ERROR: $d missing SKILL.md 2 exit 1 fi done注意workbuddy skill、ponytail skill这类网络热词暴露的是开发者用“人设”替代“能力定义”的思维惰性。“Ponytail Skill”听起来很酷但契约里怎么写“返回扎马尾的建议”这无法验证。真正Skill应是HairStyleRecommendationSkill输入{face_shape: oval, hair_length: shoulder}输出{styles: [{name: High Ponytail, reason: elongates face}]}。5. 常见问题与排查技巧实录来自17个项目的血泪经验5.1 问题agent execution terminated due to error.—— 不是Bug是契约违约现象Agent突然停止响应日志只有agent execution terminated due to error.无堆栈。这是Skill工程中最隐蔽的杀手。排查思路定位触发Skill查APM链路追踪如Jaeger找到终止前最后一个调用的Skill检查该Skill的SKILL.md重点看Behavior Contract的SLA和Implementation Contract的约束复现输入用日志里的input payload本地运行skill.py execute观察是否超时或抛异常验证契约运行skill-tester --contract policy_search检查Schema、SLA、依赖是否全部满足。真实案例某次故障追踪到DocumentFormattingSkill。SKILL.md写明“P95延迟≤1.5s”但压测发现mistune解析含100个代码块的MD时延迟达2.3s。根因是mistune默认启用所有扩展而codehilite扩展在大量代码块时性能爆炸。解决方案在adapters/mistune_adapter.py里禁用非必要扩展并在SKILL.md的Implementation Contract里追加“禁用footnotes、abbr扩展仅启用codehilite、fenced_code”。独家技巧我们在所有Skill的execute()里加了契约守卫Contract Guarddef execute(self, input: dict) - dict: start time.time() try: result self._core_logic(input) latency time.time() - start # 检查是否超SLA if latency self.sla_p95 * 1.5: # 超1.5倍即告警 logger.warning(fSLA breach: {latency:.3f}s {self.sla_p95:.3f}s) return result except Exception as e: # 记录具体错误而非泛化terminated logger.error(fSkill {self.name} failed: {str(e)}, exc_infoTrue) raise5.2 问题Markdown转Word工作流coze失败——格式失真不是渲染问题是能力契约缺失现象用户用Coze工作流将Skill生成的Markdown转Word表格错乱、代码块丢失、数学公式变方框。根因分析DocumentFormattingSkill的SKILL.md只声明“输出Markdown”未定义Markdown方言DialectCoze的Word转换器只支持CommonMark而Skill用mistune生成了GitHub Flavored Markdown含details标签数学公式用$$...$$但Coze只认\(...\)。解决方案在SKILL.md的Interface Contract里明确方言“Output must be CommonMark compliant, without HTML tags. Math formulas must use\(...\)and\[...\]delimiters.”在core/层增加commonmark_compliance_filter自动转换details为::: details$$为\[为Coze工作流单独提供coze_compatible_markdownSkill作为DocumentFormattingSkill的适配器。实操心得所有涉及格式输出的Skill Skill不是函数：Agent开发中的能力契约工程方法论
1. 这不是“技能清单”而是一次对Skill概念的外科手术式解剖你有没有在Agent开发文档里反复看到这个词——Skill它被塞进README、写在架构图角落、挂在API参数名里甚至成了团队内部黑话“这个需求得拆成两个Skill”“那个模块还没封装成Skill”。但没人告诉你它到底是什么为什么非得叫Skill它和Function、Action、Tool、Plugin、Capability这些词究竟差在哪更关键的是为什么90%的项目里写的所谓“Skill”其实根本不是Skill只是披着马甲的函数调用我做过17个不同行业的Agent项目从金融风控对话引擎到工业设备远程诊断系统从教育领域自适应学习路径生成器到医疗影像报告辅助撰写工具。踩过最深的坑不是模型不准、不是接口超时而是——团队把一堆零散API硬塞进一个叫skill.py的文件里起名叫“Knowledge Retrieval Skill”结果上线三天就因并发瓶颈崩掉三次运维日志里全是“agent execution terminated due to error.”。后来复盘才发现问题根本不在于代码而在于我们连“Skill”这个词的工程语义边界都没划清。这恰恰是当前Agent开发中最危险的认知盲区把抽象能力单元Skill当成技术实现容器文件/函数/类。Skill不是命名习惯不是目录结构更不是营销话术。它是一个有明确定义、可验证边界、需独立演化的工程契约。它必须同时满足三个刚性条件可观测的行为契约、可替换的实现契约、可组合的接口契约。缺一不可。否则你写的不是Skill是技术债的压缩包。这篇文章不教你如何写一个Skill文件也不罗列几十种Skill框架选型。我要带你做的是一次彻底的“去魅”——用真实项目中的代码片段、架构决策记录、压测数据、线上报错日志一层层剥开Skill的皮、肉、骨、髓。你会看到为什么skill.md不是文档格式而是能力声明协议为什么SKILL.md目录设计本质是能力拓扑图谱为什么ponytail skill或taste skill这类网络热词背后暴露出的是开发者对Skill粒度的集体误判以及最关键的一点——“滥用Skill”的本质是用粗粒度封装掩盖细粒度设计缺失。适合谁读如果你正在写Agent哪怕只写了三行def get_weather()如果你在review同事的PR看到skill/目录下塞了8个.py文件却说不清每个文件解决什么问题如果你在设计agent.md架构文档纠结该把“用户画像生成”放在core/还是skill/或者你刚听说pi agent或hermes agent想搞懂它们凭什么敢叫“Agent”而不是“Bot”——那这篇就是为你写的。它不假设你懂LangChain不要求你会写Verilog但要求你愿意放下“我只要跑通就行”的心态真正思考我交付的究竟是一个可维护的能力单元还是一团随时会散架的胶水代码2. Skill的本质一场关于“能力契约”的工程革命2.1 Skill不是功能而是能力契约——从“能做什么”到“承诺做什么”很多人第一次接触Skill是从某个Agent框架的文档里看到“请为你的Agent定义Skill”。于是立刻打开编辑器新建weather_skill.py写个get_weather(city)函数再加个skill装饰器大功告成。但这种做法本质上是在用实现细节冒充能力定义。真正的Skill始于一份白纸黑字的能力契约Capability Contract。什么叫能力契约它回答三个问题行为契约Behavioral Contract这个Skill对外承诺提供什么可观测行为比如“给定城市名返回未来24小时温度、湿度、降水概率响应时间≤800ms错误率0.5%”。注意这里没有提Python、没有提OpenWeather API、没提缓存策略——这些全是实现细节契约里只写用户能验证的结果。实现契约Implementation Contract这个Skill的内部实现必须满足哪些约束比如“不依赖外部数据库连接池”“所有HTTP调用必须带timeout3s”“失败时必须返回标准Error Schema包含code、message、retry_after字段”。这些约束保证Skill可以被安全替换而不影响上层逻辑。接口契约Interface Contract这个Skill通过什么标准化方式被调用和集成比如“必须提供execute(input: dict) - dict方法”“输入必须符合WeatherInputSchemaJSON Schema”“输出必须符合WeatherOutputSchema”。这不是Python签名而是跨语言、跨框架的协议。我参与过一个政务热线Agent项目初期团队把“政策条款查询”写成一个policy_search_skill.py里面混着ES查询、PDF解析、关键词高亮。上线后发现当政策库从Elasticsearch迁移到向量数据库时整个Skill要重写导致Agent核心流程停摆3天。后来我们重定义了PolicySearchSkill契约行为契约输入政策编号或关键词返回匹配条款列表含原文段落、生效日期、废止状态P95延迟≤1.2s实现契约禁止直接访问任何存储层必须通过PolicyDataSource抽象接口所有文本处理必须使用预编译正则表达式接口契约输入为{query: string, limit: int}输出为{items: [{text: string, effective_date: date, status: enum}]}。结果呢迁移向量库时只需重写PolicyDataSource的两个方法Skill文件本身一行未动Agent无感切换。这就是契约的力量——它把变化关进笼子。提示判断一个东西是不是真正的Skill就看它能否脱离当前代码库独立存在。如果把它复制到另一个Agent项目里需要改10处import路径、3个配置常量、2个全局变量那它就不是Skill只是个耦合体。2.2 Skill与Function/Tool/Plugin的根本区别粒度、契约与演化权网络热词里常把Skill和Tool、Plugin混用比如“Chrome查看Markdown插件”“Skill Recorder”“Skill插件”。这是典型的术语污染。它们表面相似内核迥异维度Function函数Tool工具Plugin插件Skill能力单元粒度单一操作如len()独立功能如git commit宿主扩展如VS Code插件解决特定领域问题的完整能力链如“用户意图澄清”契约强度无契约仅签名弱契约约定输入输出格式中等契约遵循宿主API强契约行为实现接口三重约束演化权随代码库整体演进可独立更新但影响宿主宿主控制更新节奏拥有独立生命周期可灰度发布、A/B测试、熔断降级可组合性仅能顺序调用需手动编排依赖宿主调度原生支持组合Skill A调用Skill B自动处理上下文传递、错误传播、超时继承举个真实案例我们为某电商Agent设计“价格比对”能力。最初用Function实现def compare_price(sku_list)结果发现它无法处理“用户说‘看看iPhone15和华为Mate60哪个便宜’”这种模糊输入——需要先做实体识别、再查SKU、再调价、再生成对比文案。于是有人提议做成Tool封装成CLI命令。但CLI无法嵌入Agent的推理循环每次调用都要进程fork延迟飙升。最后我们定义PriceComparisonSkill输入自然语言查询如“对比A和B的价格”输出结构化比对结果 自然语言摘要内部自动编排EntityRecognitionSkill→ProductLookupSkill→PriceFetchSkill→SummaryGenerationSkill。这个Skill可以被其他Skill调用比如PurchaseRecommendationSkill需要它也能被人工审核流调用还能单独压测。它的版本号v2.1.0独立于Agent主版本演进上周我们灰度发布了v2.2.0新增汇率换算老版本继续运行零影响。注意很多项目把markdown相关操作堆成MarkdownSkill这是典型滥用。Markdown是格式规范不是能力领域。真正Skill应该是DocumentFormattingSkill负责排版、ContentExtractionSkill从MD提取关键信息、CrossReferenceResolutionSkill解析[link](#anchor)。把语法细节当能力就像把“用筷子夹菜”叫“进食Skill”而忽略“判断食物是否变质”“协调咀嚼与吞咽”这些真正的能力。2.3 Skill.md不是文档而是能力声明协议的机器可读载体网络热词里高频出现skill.md、agent.md、SKILL.md目录设计很多人以为这只是个文档习惯。错。SKILL.md是能力声明协议Capability Declaration Protocol的落地形式它的存在意义是让Skill从“人可读”走向“机器可读、可验证、可编排”。一个合规的SKILL.md必须包含且仅包含以下结构我们团队已沉淀为CI检查项--- name: PolicySearchSkill version: 2.3.0 category: knowledge_retrieval tags: [government, regulation, search] description: 根据政策编号或关键词检索匹配条款并返回结构化结果 --- ## Behavior Contract - Input: {query: string, limit: integer} - Output: {items: [{text: string, effective_date: date, status: active|repealed|amended}]} - SLA: P95 latency ≤ 1.2s, error rate 0.3% ## Implementation Contract - Must use PolicyDataSource interface for all data access - Text processing must use pre-compiled regex patterns (see regex_patterns.py) - No direct database connections allowed ## Interface Contract - Method: execute(input: dict) - dict - Input Schema: https://schema.example.com/skill/policy_search_input.json - Output Schema: https://schema.example.com/skill/policy_search_output.json ## Dependencies - EntityNormalizationSkill1.5.0 - DocumentIndexingServicev3.2.0 ## Test Cases | Input | Expected Output | Status | |-------|-----------------|--------| | {query: 国发〔2023〕12号} | {items: [...]} | ✅ | | {query: 税收优惠, limit: 5} | {items: [...], count: 5} | ✅ |这个文件的作用远超文档CI阶段自动校验name是否唯一、version是否符合语义化规则、Input SchemaURL是否可访问部署阶段Agent Runtime读取Dependencies自动构建调用图谱检测环形依赖监控阶段将SLA指标注入Prometheus当error rate超阈值时自动触发Skill熔断治理阶段tags字段支持按government标签批量查询所有政务相关Skill评估合规风险。我们曾用SKILL.md发现一个严重问题某FinancialReportSkill声明依赖TaxCalculationSkill1.0.0但实际代码调用了TaxCalculationSkill1.2.0的新接口。CI检查失败强制团队修复契约——避免了线上因版本不匹配导致的财报计算错误。实操心得别手写SKILL.md我们用skill-decl-gen工具基于Python类型注解自动生成骨架。例如from pydantic import BaseModel class PolicySearchInput(BaseModel): query: str limit: int 10 class PolicySearchOutput(BaseModel): items: List[PolicyItem]运行skill-decl-gen policy_search.py自动生成带Schema链接、测试用例模板的SKILL.md。人力只聚焦在填充Behavior Contract的SLA和Implementation Contract的约束条款上。3. Skill的工程实现从契约到代码的四步炼金术3.1 第一步契约具象化——用Schema和SLA把模糊需求钉死“做一个搜索Skill”是无效需求。真正的起点是把模糊描述转化为可验证的契约条款。我们团队的标准流程是“三问法”行为可测吗错误表述“能搜政策” → 正确表述“输入政策编号100%返回原文段落输入关键词召回率≥92%准确率≥88%”。计算依据基于历史咨询日志抽样1000条统计用户真实查询模式和期望结果。召回率返回的相关条款数/所有相关条款总数准确率返回的相关条款数/返回的总条款数。实现可约束吗错误表述“用ES搜” → 正确表述“所有数据访问必须通过PolicyDataSource.get_by_id()或PolicyDataSource.search()禁止直连ES客户端”。约束理由保证未来可切换为向量库且避免SQL注入式ES查询如*:*。接口可组合吗错误表述“返回JSON” → 正确表述“输出必须符合PolicySearchOutputSchema且items数组中每个元素必须包含text、effective_date、status字段status枚举值限定为active/repealed/amended”。组合价值下游PolicySummarySkill可安全假设字段存在无需if status in item防御性编程。以DocumentFormattingSkill为例处理用户提交的原始文本生成高颜值Markdown报告行为契约输入纯文本输出符合report_v2规范的Markdown含标题层级、表格对齐、代码块语法高亮渲染后PDF页数误差≤±0.5页实现契约禁止使用pandoc因license冲突必须用mistunepygments表格渲染必须支持colspan/rowspan接口契约输入{content: string, template: report_v2}输出{markdown: string, metadata: {page_count: float}}。这个契约让前端、后端、QA有了共同靶心。测试不再问“格式对不对”而是跑自动化脚本# 生成PDF并计页数 pandoc input.md -o output.pdf pdfinfo output.pdf | grep Pages: | awk {print $2} # 对比预期页数允许±0.53.2 第二步骨架生成——用声明驱动开发DDD规避实现陷阱拿到SKILL.md后绝不直接写业务逻辑。我们采用声明驱动开发Declarative-Driven Development先生成强制骨架创建skill/目录结构policy_search/ ├── __init__.py ├── skill.py # 主入口仅含execute()和契约校验 ├── core/ # 业务逻辑无外部依赖 │ ├── retriever.py # 纯函数输入dict输出list[dict] │ └── normalizer.py # 纯函数输入str输出标准化query ├── adapters/ # 外部依赖适配层 │ ├── es_adapter.py # 封装ES客户端实现PolicyDataSource接口 │ └── cache_adapter.py # 封装Redis实现CacheProvider接口 ├── tests/ # 契约测试非单元测试 │ └── test_behavior.py # 验证SLA、输入输出格式 └── SKILL.md # 契约文件skill.py骨架强制规则必须继承BaseSkill提供统一execute()、health_check()、metrics()execute()第一行必须调用self._validate_input(input)校验是否符合SKILL.md声明的Input Schema最后一行必须调用self._enforce_output(output)确保输出字段、类型、枚举值全合规禁止在skill.py里写任何业务逻辑所有计算必须下沉到core/。这个骨架看似繁琐却堵死了90%的滥用无法把数据库连接写在execute()里因为adapters/层强制隔离无法返回缺失status字段的JSON因为_enforce_output()会抛异常无法绕过Schema校验因为_validate_input()是硬性前置。踩过的坑某次紧急上线同事为省事在skill.py里直接调用requests.get()。结果压测时发现连接池耗尽但SKILL.md里写的“不依赖外部连接池”契约形同虚设。后来我们加了静态检查grep -r requests\. skill/policy_search/ exit 1CI直接失败。3.3 第三步契约测试——用生产环境数据反向验证Skill可靠性很多团队的Skill测试停留在“单元测试覆盖80%”。这毫无意义。真正的Skill测试必须是契约测试Contract Testing用生产环境的真实流量样本验证Skill是否履行了SKILL.md里的每一项承诺。我们的测试流程分三层Schema层测试工具jsonschemaopenapi-spec-validator操作下载SKILL.md里声明的Input/Output Schema用10万条历史请求/响应数据批量校验。发现问题曾发现PolicySearchSkill的Output Schema允许status为null但实际业务要求必填。修正Schema后上游Agent自动捕获空值并告警。SLA层测试工具locustprometheus-client操作模拟1000QPS持续10分钟监控P95延迟、错误率、GC次数。关键参数--users 1000虚拟用户数--spawn-rate 100每秒启动100用户--run-time 10m运行10分钟结果解读若P95延迟超1.2s不是调优代码而是降级Skill如关闭高亮功能或扩容adapters/es_adapter.py的连接池。行为层测试工具pytestdiff-match-patch精准比对文本操作用真实用户咨询语句如“国办发〔2022〕25号文关于新能源汽车补贴的规定”作为输入比对输出是否包含所有关键条款、日期是否准确、状态是否正确。独家技巧对Markdown输出我们用mistune解析后比对AST节点而非字符串——避免因空格、换行差异导致误报。实操心得测试数据必须来自生产环境脱敏库而非人工构造。我们用traffic-replayer工具从Kafka消费真实请求自动过滤敏感字段如身份证号、手机号生成测试数据集。人工构造的数据永远覆盖不了长尾case比如用户输入“国发〔2023〕12号修订版”而契约里没定义“修订版”的解析规则。3.4 第四步部署与治理——让Skill真正拥有独立生命写完代码、通过测试只是开始。Skill的工程价值在于它能独立部署、独立监控、独立演进。我们用Kubernetes Operator实现Skill生命周期管理独立部署每个Skill打包为Docker镜像镜像Tag与SKILL.md的version严格一致如policy-search-skill:v2.3.0。K8s Deployment的imagePullPolicy设为IfNotPresent避免重复拉取。独立监控Prometheus抓取/metrics端点指标前缀为skill_policy_search_如skill_policy_search_latency_seconds_bucket。Grafana看板按Skill分组P95延迟超阈值时自动创建Jira工单并负责人。独立演进灰度发布新版本先路由1%流量监控error_rate和latency达标后逐步放量A/B测试PolicySearchSkillv2.3.0vsPolicySearchSkillv2.4.0新增语义搜索用user_id % 100分流熔断降级当error_rate 5%持续2分钟自动切换到PolicySearchSkillv2.2.0稳定版并发送Slack告警。最关键的治理动作是Skill拓扑图谱Skill Topology Map。我们用skill-graph-builder扫描所有SKILL.md的Dependencies字段自动生成可视化图谱节点Skill名称版本边依赖关系调用频次来自APM埋点颜色健康状态绿色SLA达标红色错误率超限。这张图让我们一眼看出DocumentFormattingSkill是中心节点被12个Skill依赖它的故障会导致整个Agent报告生成链路中断。因此我们给它配置了双倍CPU资源和独立Pod反亲和性。注意agent execution terminated due to error.这类报错90%源于Skill依赖链断裂。比如PolicySearchSkill依赖EntityNormalizationSkill但后者因内存泄漏OOM导致前者调用超时。拓扑图谱熔断机制让问题定位从“大海捞针”变成“顺藤摸瓜”。4. Skill滥用的典型场景与避坑指南从“写得出来”到“用得安心”4.1 场景一把“技术实现”当“能力定义”——目录即深渊现象skill/目录下塞满文件db_query.py、http_client.py、file_parser.py、string_utils.py……美其名曰“模块化”。这是最普遍的滥用本质是用文件系统代替架构设计。危害无法评估能力边界file_parser.py既解析PDF又处理Excel当PDF解析出bug整个Skill停摆无法独立演进升级Excel解析库必须测试所有用到file_parser.py的Skill无法组合复用DocumentFormattingSkill想用PDF解析却要引入整个file_parser.py带上不必要的Excel依赖。避坑方案按能力域拆分而非技术栈DocumentParsingSkill专注“从任意格式提取结构化文本”输入{url: string}输出{text: string, pages: int, tables: list}TableRenderingSkill专注“将表格数据渲染为Markdown”输入{data: list[list]}输出{markdown: string}ImageCaptioningSkill专注“为图片生成描述”输入{image_url: string}输出{caption: string}。每个Skill有自己的SKILL.md自己的CI流水线自己的监控看板。DocumentFormattingSkill按需组合它们而非继承它们的代码。实操心得新项目启动时我们用“能力风暴”Capability Storming工作坊白板上写满用户真实任务如“把扫描件转成可搜索PDF”“从会议纪要提取待办事项”然后投票选出Top5高频任务每个任务定义一个Skill。绝不从技术组件出发4.2 场景二把“功能聚合”当“能力抽象”——Markdown不是Skill而是载体现象网络热词里“markdown”高频出现很多人认为“支持Markdown”就是一个Skill。错。Markdown是序列化格式不是能力。真正的Skill是ContentExtractionSkill从Markdown中提取标题、章节、代码块、表格CrossReferenceResolutionSkill解析[链接](#锚点)并验证目标是否存在DocumentVersioningSkill管理同一文档的多个Markdown版本支持diff和回滚。滥用后果MarkdownSkill越写越大最终变成“万能解析器”违反单一职责当用户需要“从Markdown提取数学公式”却发现MarkdownSkill里混着LaTeX解析、MathML转换、图片渲染改一处崩一片。避坑方案用Schema定义能力边界为ContentExtractionSkill定义Input Schema{ type: object, properties: { content: {type: string}, extract_types: { type: array, items: {enum: [heading, code_block, table, math_formula]} } } }这样用户明确知道这个Skill只做提取不做渲染只支持指定类型不保证解析所有Markdown扩展语法。提示markdown preview enhanced插件出乱码根源常是Skill层未处理script标签或iframe——这不是插件问题而是ContentExtractionSkill的契约没声明对HTML片段的处理策略。应在SKILL.md的Implementation Contract里写明“禁止输出含script的HTML对iframe返回占位符”。4.3 场景三把“AI调用”当“Skill封装”——Agent不是魔法盒Skill不是胶水现象ai_agent_verilog_code、agent画图这类热词暗示一种危险倾向把大模型API调用简单包装成Skill。比如CodeGenerationSkill内部就是openai.ChatCompletion.create()。危害无法控制成本一次调用可能消耗10倍token却无预算监控无法保障质量模型输出不稳定但Skill契约承诺“返回可执行代码”无法降级模型服务宕机Skill直接失败无备选方案。避坑方案Skill必须包含“人类可理解的保底逻辑”CodeGenerationSkill的契约行为输入自然语言描述返回Python代码若模型失败返回{fallback: true, suggestion: 请检查语法或提供更多上下文}实现先用规则引擎匹配常见模板如“排序数组”→sorted(arr)命中则秒回未命中再调模型接口输出必须含code字段模型结果和confidence字段0.0~1.0下游Skill可据此决定是否信任。我们为VerilogCodeGenerationSkill实现了三层保底规则层匹配“D触发器”“计数器”等关键词返回预置代码模板检索层在历史成功案例库中检索相似描述返回最佳匹配模型层调用模型但强制temperature0.2降低随机性并用code_linter校验语法。结果85%请求走规则层平均延迟从1200ms降至45ms成本下降92%。实操心得所有AI-Skill必须在SKILL.md里声明fallback_strategy和confidence_threshold。我们规定confidence 0.7时必须触发人工审核流而非直接返回低置信度结果。4.4 场景四把“目录结构”当“能力治理”——skill.md目录设计的真相现象看到skill/目录就以为完成了Skill化。更甚者模仿pi agent官网的目录建skill/core/、skill/utils/、skill/tests/却没SKILL.md。危害目录成了“技术债务仓库”没人敢删utils/里的旧函数新人以为core/是核心逻辑实则混着数据库连接和日志打印无法审计想知道“哪些Skill访问了用户隐私数据”只能grep全代码库。避坑方案目录即契约文件即证据skill/目录下每个子目录必须对应一个SKILL.mdSKILL.md必须通过CI检查Schema校验、版本语义化、依赖可解析core/目录只允许存在纯函数无IO、无全局状态adapters/目录只允许存在外部依赖适配器。我们用dir-validator工具强制# 检查每个skill子目录是否有SKILL.md find skill/ -mindepth 1 -maxdepth 1 -type d | while read d; do if [ ! -f $d/SKILL.md ]; then echo ERROR: $d missing SKILL.md 2 exit 1 fi done注意workbuddy skill、ponytail skill这类网络热词暴露的是开发者用“人设”替代“能力定义”的思维惰性。“Ponytail Skill”听起来很酷但契约里怎么写“返回扎马尾的建议”这无法验证。真正Skill应是HairStyleRecommendationSkill输入{face_shape: oval, hair_length: shoulder}输出{styles: [{name: High Ponytail, reason: elongates face}]}。5. 常见问题与排查技巧实录来自17个项目的血泪经验5.1 问题agent execution terminated due to error.—— 不是Bug是契约违约现象Agent突然停止响应日志只有agent execution terminated due to error.无堆栈。这是Skill工程中最隐蔽的杀手。排查思路定位触发Skill查APM链路追踪如Jaeger找到终止前最后一个调用的Skill检查该Skill的SKILL.md重点看Behavior Contract的SLA和Implementation Contract的约束复现输入用日志里的input payload本地运行skill.py execute观察是否超时或抛异常验证契约运行skill-tester --contract policy_search检查Schema、SLA、依赖是否全部满足。真实案例某次故障追踪到DocumentFormattingSkill。SKILL.md写明“P95延迟≤1.5s”但压测发现mistune解析含100个代码块的MD时延迟达2.3s。根因是mistune默认启用所有扩展而codehilite扩展在大量代码块时性能爆炸。解决方案在adapters/mistune_adapter.py里禁用非必要扩展并在SKILL.md的Implementation Contract里追加“禁用footnotes、abbr扩展仅启用codehilite、fenced_code”。独家技巧我们在所有Skill的execute()里加了契约守卫Contract Guarddef execute(self, input: dict) - dict: start time.time() try: result self._core_logic(input) latency time.time() - start # 检查是否超SLA if latency self.sla_p95 * 1.5: # 超1.5倍即告警 logger.warning(fSLA breach: {latency:.3f}s {self.sla_p95:.3f}s) return result except Exception as e: # 记录具体错误而非泛化terminated logger.error(fSkill {self.name} failed: {str(e)}, exc_infoTrue) raise5.2 问题Markdown转Word工作流coze失败——格式失真不是渲染问题是能力契约缺失现象用户用Coze工作流将Skill生成的Markdown转Word表格错乱、代码块丢失、数学公式变方框。根因分析DocumentFormattingSkill的SKILL.md只声明“输出Markdown”未定义Markdown方言DialectCoze的Word转换器只支持CommonMark而Skill用mistune生成了GitHub Flavored Markdown含details标签数学公式用$$...$$但Coze只认\(...\)。解决方案在SKILL.md的Interface Contract里明确方言“Output must be CommonMark compliant, without HTML tags. Math formulas must use\(...\)and\[...\]delimiters.”在core/层增加commonmark_compliance_filter自动转换details为::: details$$为\[为Coze工作流单独提供coze_compatible_markdownSkill作为DocumentFormattingSkill的适配器。实操心得所有涉及格式输出的Skill