4人并行 · 50 Skill · 10字段描述 · SKILL.md目录结构 · Repair Loop · should-not-trigger · 三级上下文 · 产出防偏
2Skill描述模板
2.1 Skill描述10字段(注册时必填)
对标Agent Skills规范(agentskills.io),在原7字段基础上新增 allowed-tools / compatibility / version 三个字段:
{
"skill_id": "SK-01",
"skill_name": "项目自动建档",
"skill_name_en": "auto-archive",
"description": "100-200字,三要素:做什么+何时触发+不做什么(见2.1.1)",
"triggers": [见第8节触发词规范],
"boundary": "A", // A/B/C
"owner_fde": "FDE-1",
"sop_stage": "S1-B00",
"allowed_tools": ["erp.route-search"], // 工具白名单:只允许调这些工具
"compatibility": "requires: erp-module>=1.0; network: yes", // 环境依赖声明
"version": "1.0.0", // 语义化版本号
"dependencies": {
"external_api": null, "mcp_tools": null,
"upstream_skills": null, "downstream_skills": ["SK-02", "SK-05"],
"parallelizable_with": null
}
}
2.1.1 description三要素规范(对标Agent Skills best practices)
description是AI路由Skill的唯一触发机制,必须包含三要素,100-200字:
| 要素 | 说明 | 示例(SK-10 公开工商查询) |
| 做什么 | Skill的核心功能和输入→输出 | "查询企业的工商注册信息,输入公司名/统一社会信用代码,输出注册资本、法定代表人、经营状态等" |
| 何时触发 | 什么场景下应该调用此Skill,含关键词 | "当用户需要查工商信息、核验企业资质、尽调阶段查询合作方工商状态时使用" |
| 不做什么 | 明确边界,防止误触发 | "不查询司法记录(→SK-11)、不搜舆情(→SK-12)、不做风险评分(→SK-14)" |
完整示例:"查询企业的工商注册信息,输入公司名/统一社会信用代码,输出注册资本、法定代表人、经营状态等。当用户需要查工商信息、核验企业资质、尽调阶段查询合作方工商状态时使用。不查询司法记录(→SK-11)、不搜舆情(→SK-12)、不做风险评分(→SK-14)。"
为什么从50字扩到100-200字:对标Agent Skills规范(description 1-1024字符,必须包含what AND when)。50字太短,AI路由时缺少足够语义信息做匹配,是调错Skill的首要原因。
2.1.2 allowed-tools工具白名单
对标Agent Skills规范的 allowed-tools 字段。每个Skill声明只能调用哪些工具,防止越权调用:
| Skill | allowed_tools | 说明 |
| SK-10 工商查询 | ["ext.scenic-query"] | 只能调企查查API,不能调MCP的order/fin工具 |
| SK-27 合同生成 | [] | 纯LLM生成,不需要外部工具 |
| SK-37 商品上架 | ["ec.product-create", "ec.product-search"] | 只能调电商域的2个工具 |
| SK-43 对账单生成 | ["erp.dispatch-query", "order.query"] | 只能调ERP调度查询和订单查询 |
空数组[]表示纯LLM Skill,不需要外部工具。白名单外的工具调用一律拒绝。
2.1.3 compatibility环境依赖声明
声明Skill运行所需的环境条件,Hermes/工作台启动时自动检测:
"compatibility": "requires: asr-service>=1.0; network: yes; mcp: ec.*,erp.*"
// 格式:requires: 依赖项>=版本; network: yes/no; mcp: 工具域
// 示例:
// SK-19 录音转写 → "requires: asr-service>=1.0; network: yes"
// SK-37 商品上架 → "requires: mcp: ec.product-create; network: yes"
// SK-01 自动建档 → "requires: none"
2.2 System Prompt 5段式结构
## 角色定义
你是{角色名称},负责{职责描述}。当前执行SK-{编号} {中文名}。
## 职责边界
你做什么:{列举}
你不做什么:{列举相邻Skill,用"→ SK-xx"标注路由}
## 输入规范
- {参数1}({类型},{必填/选填}):{说明}
## 输出规范
必须输出JSON,结构如下:
{输出JSON Schema}
## 执行边界
- 级别:{A/B/C}
- 执行后行为:{描述}
- 禁止事项:{≥1条}
- 输出前自检:格式/事实/范围/边界/语言 5项
"不做什么"必须列出所有易混淆的相邻Skill,用"→ SK-xx"标注正确路由。AI在边界模糊时据此自动路由。
3输入输出格式
3.1 输出公共信封(所有Skill必须遵守)
{
"skill_id": "SK-24",
"skill_name": "尽调报告生成",
"exec_status": "success", // success | partial | failed | cancelled
"exec_boundary": "B",
"need_confirm": true, // A=false, B/C=true
"confirm_message": "尽调报告已生成,请确认",
"data": { /* 业务数据 */ },
"progress": { // 进度提示(见第12节)
"current_step": "B12 · 尽调报告生成",
"current_stage": "S1 商机与尽调",
"overall_progress": "12/31",
"next_step": "B13 · 谈判问题清单 (SK-18)",
"blocked": false
},
"downstream_hint": { // 提示下游可消费的数据
"for_skills": ["SK-25"],
"key_fields": ["report_id", "risk_level"]
},
"errors": null,
"timestamp": "2026-09-04T10:30:00+08:00"
}
3.2 文档类Skill输出双结构
生成文档的Skill(报告/合同/材料)输出分structured(给下游Skill)+ document(给用户查看):
"data": {
"structured": { "risk_level": "medium", "risk_score": 72 },
"document": { "format": "markdown", "content": "# 尽调报告\n..." }
}
4Prompt工程规范
4.1 Prompt长度控制
| Skill类型 | 上限 | 示例 |
| 简单型(查询/检索/归类) | ≤500 token | SK-03/04/06/10 |
| 中等型(生成/检查/计算) | ≤1,200 token | SK-05/07/24/27 |
| 复杂型(报告/合同/对账) | ≤2,000 token | SK-24/25/43 |
超过2,000 token必须拆分。拆为2-3个串联小Skill,每个≤1,200 token。或使用references/引用文件模式(见4.5节)。
4.2 Prompt中必须包含的5类约束
| 约束 | 说明 | 示例 |
| 格式 | 输出必须是什么格式 | "必须输出JSON,不输出任何其他内容" |
| 事实 | 禁止编造数据 | "只使用输入或API返回的数据,不可自行编造" |
| 行为 | 禁止越权 | "不评估风险等级(→SK-14)" |
| 质量 | 可检验标准 | "摘要≤6条""关键风险≤5条" |
| 语言 | 语言和风格 | "中文,正式商务语气" |
第6类约束——默认值原则(对标Agent Skills "Provide defaults, not menus"):Prompt中应为可选参数提供合理默认值,而不是让AI/用户在多个选项中选择。例如SK-17额度测算应写"默认使用中等风险情景(profit_margin=0.15),用户未指定时按默认值执行",而不是"请选择风险情景:高/中/低"。减少决策负担,减少交互轮次。
4.3 Few-shot示例
| Skill类型 | 示例数 | 说明 |
| 格式严格型 | 1个 | 输出格式固定,1个够 |
| 判断有弹性型 | 2-3个 | 需正反例 |
| 生成文档型 | 1个模板 | 给模板不给完整示例,避免照抄 |
4.4 输出长度控制
| 输出类型 | 上限 | 控制方式 |
| 结构化数据(JSON) | ≤2,000 token | Schema限制≤20字段 |
| 摘要/列表 | ≤500 token | 限制条数(摘要≤6,风险≤5) |
| 文档(报告/合同) | ≤3,000 token | 分section输出,每section≤800 |
| 确认卡片 | ≤300 token | 摘要≤6条,每条≤30字 |
4.5 复杂Skill的references/引用文件模式
对标Agent Skills规范的Progressive Disclosure。复杂Skill(SK-24尽调报告、SK-27合同初稿、SK-43对账单)如果规则太多塞不进2,000 token,使用引用文件拆分:
## SKILL.md(核心流程,≤1,000 token)
你是尽调报告生成助手。按照以下步骤生成报告:
1. 读取尽调数据包(上游交接1)
2. 按 references/report_template.md 的模板结构生成
3. 评分规则见 references/scoring_rules.md
4. 风险等级判定见 references/risk_matrix.md
## references/report_template.md(报告模板,按需加载)
# 尽调报告模板
## 一、企业基本信息
## 二、工商与司法查询结果
## 三、财务勾稽分析
## 四、风险评级与纳入建议
## references/scoring_rules.md(评分规则,按需加载)
| 维度 | 权重 | 评分标准 |
| 工商状态 | 20% | 注销=0, 存续=80, 异常=40 |
...
## references/risk_matrix.md(风险矩阵,按需加载)
| 评分区间 | 风险等级 | 纳入建议 |
| 0-30 | high | 不建议纳入 |
| 31-60 | medium | 有条件纳入 |
| 61-100 | low | 建议纳入 |
| 文件 | 加载时机 | 说明 |
| SKILL.md | L3执行层 | 核心流程指令,≤1,000 token,AI调用时加载 |
| references/*.md | 按需 | 详细规则/模板/矩阵,AI需要时才读取 |
| scripts/* | 按需 | 程序化计算脚本(如评分计算),运行后只输出结果不进上下文 |
引用原则:SKILL.md只放"做什么+怎么做"的流程指令,详细规则全部放references/。AI先加载SKILL.md执行,遇到需要详细规则时按需读references。这样2,000 token的Prompt限制下也能承载复杂业务逻辑。
6人工确认卡片
6.1 统一格式(B/C级Skill执行后弹出)
{
"card_type": "confirm",
"skill_id": "SK-24",
"title": "尽调报告已生成,请确认",
"summary": [ // ≤6条
{"label": "风险评级", "value": "中风险", "highlight": true},
{"label": "纳入建议", "value": "建议纳入,需追加担保"}
],
"actions": [
{"id": "confirm", "label": "确认采纳", "primary": true},
{"id": "modify", "label": "我要修改", "primary": false},
{"id": "reject", "label": "不采纳", "primary": false}
],
"next_hint": { // 接力棒(见第12节)
"message": "确认后可进入谈判阶段,需要出谈判问题清单吗?",
"suggested_skill": "SK-18",
"auto_trigger": false // 不自动触发
},
"timeout": 86400, "on_timeout": "cancel"
}
6.2 卡片设计规则
| 规则 | 说明 |
| 摘要≤6条 | 人能一眼扫完 |
| 高风险标红 | highlight=true的字段红色高亮 |
| 三按钮 | 确认/修改/不采纳,不是二选一 |
| 超时取消 | B/C级超时一律cancel,不可auto_pass |
| 修改入口 | 点击后进入编辑模式,改完重新确认 |
| 拒绝有因 | 点击"不采纳"后必填拒绝原因 |
7错误处理与降级
7.1 错误分类与处理
| 错误类型 | status | 处理策略 | 重试 |
| 输入缺失/格式错误 | failed | 返回错误信息+正确格式示例 | 否 |
| 外部API超时 | partial | 返回已获取部分+标注缺失,提示手动补充 | 1次 |
| 外部API报错 | failed | 返回错误信息+API错误详情 | 否 |
| LLM生成异常 | failed | 自动重试1次(温度降0.3) | 1次 |
| MCP工具不可用 | failed | 切换手工模式(见第11节) | 否 |
| 用户拒绝确认 | cancelled | 保存草稿,不触发下游 | 否 |
写操作不自动重试:涉及资金/合同/商品的写操作失败后不自动重试,必须人工确认后手动重试。
7.2 Repair Loop(错误反馈修复循环)
对标LangChain ToolArgValidationMiddleware。Schema校验失败时,不是简单重试,而是把错误信息喂回LLM让它自修正:
## Repair Loop流程
1. LLM输出 → Schema校验
2. 校验失败 → 把错误信息+原始输出喂回LLM:
"你上次的输出存在以下问题:{错误详情}。
请根据错误信息修正后重新输出。"
3. LLM修正输出 → 再次Schema校验
4. 通过 → 返回结果
5. 仍然失败 → 标记failed+返回原始输出供人工查看
// 最多2轮repair,超过则降级
// 温度策略:第1轮原温度,第2轮降0.3
// 示例:
// 第1次输出:{"risk_level": "中风险", ...} ← 枚举值错误,应为"medium"
// 反馈给LLM:"risk_level字段值'中风险'不在允许枚举[low,medium,high]内,请修正"
// 第2次输出:{"risk_level": "medium", ...} ← 校验通过
| 场景 | Repair | 说明 |
| 格式错误(非JSON/字段缺失) | 2轮 | 把具体错误喂回LLM,通常1轮就能修好 |
| 枚举值错误 | 2轮 | 把允许的枚举值列出来让LLM选 |
| 类型错误(string vs int) | 2轮 | 把期望类型告诉LLM |
| 语义错误(内容不对) | 不repair | 语义错误不是格式问题,repair无法解决,直接标记failed |
| 写操作失败 | 不repair | 资金/合同/商品操作不自动重试 |
Repair Loop vs 简单重试:简单重试是"再来一次"(同样温度同样Prompt,大概率犯同样错);Repair Loop是"告诉你错在哪了,改过来"(错误信息+原始输出一起喂回,修正率高得多)。
7.3 错误信封
{
"skill_id": "SK-11", "exec_status": "failed",
"errors": [{
"code": "API_TIMEOUT",
"message": "裁判文书网API请求超时",
"detail": "请求耗时15s,超过5s阈值",
"suggestion": "可稍后重试,或手动查询后录入",
"retryable": true
}],
"data": null
}
8触发词防冲突
8.1 触发词三段式
所有触发词按 [动作]+[业务对象]+[限定词] 注册,禁止单动词:
// 正确
SK-07: "检查资料完整性" // 动作=检查 对象=资料 限定=完整性
SK-08: "检查主体一致性" // 动作=检查 对象=主体 限定=一致性
SK-24: "出尽调报告" // 动作=出 对象=尽调报告
// 禁止
SK-07: "检查" // 单动词,8个Skill冲突
SK-24: "出报告" // 单动词,4个Skill冲突
8.2 触发词注册规则
| 规则 | 说明 |
| 每Skill ≤5条 | 3-5条为最佳,太多增加冲突 |
| 主触发词唯一 | 50个Skill主触发词两两不同,Day 1对齐会统一分配 |
| 带SOP阶段标签 | AI按当前阶段过滤,跨阶段时提示用户 |
{"skill_id":"SK-07","triggers":[
{"phrase":"检查资料完整性","type":"primary","sop_stage":"S1"},
{"phrase":"核对资料是否齐全","type":"secondary","sop_stage":"S1"}
]}
8.3 高频冲突词消解表
| 冲突词 | 涉及Skill | 消解方案 |
| "检查" | SK-07/08/14/22/29/34/42/44 | 加业务对象:检查资料/主体/偏离/材料/签署/差异/发票 |
| "生成/出" | SK-05/24/25/27/43/48 | 加产出物名称:出清单/出尽调报告/出上会材料/生成合同 |
| "查询/查" | SK-03/10/11/12/39 | 加对象:查案例/查工商/查司法/搜舆情/查核销 |
| "算" | SK-14/17/41 | 加对象:算评分/算额度/复算公式 |
| "监控" | SK-38/47 | 加对象:监控履约/监控风险变化 |
11断档兜底机制
11.1 三种断档与兜底
| 断档类型 | 场景 | 兜底 |
| MCP未就绪 | B24-B28共6步 | 手工模式(下方) |
| API不可用 | SK-10/11/12/19/30/36 | 返回空数据+标注"待补充"+手动录入入口 |
| 上游缺失 | 下游Skill的上游未执行 | null填充缺失字段+卡片高亮"数据缺失" |
11.2 MCP手工模式规范
## 手工模式(MCP未就绪时自动切换)
1. 不执行实际业务操作(不创建商品/不导入核销/不开票)
2. 生成操作指引:目标系统+操作步骤+预填数据+确认方式
3. 告知用户:"当前为手工模式,我已生成操作指引和预填数据,请在ERP中操作后告诉我。"
4. 用户确认手工操作完成后,Skill继续下游
// 手工模式输出
{
"mode": "manual",
"reason": "MCP_TOOL_UNAVAILABLE",
"instruction": {
"target_system": "ERP-商品中心",
"steps": ["1.登录ERP→商品管理→新建", "2.填写以下字段..."],
"prefill_data": {"product_name":"...", "price":950000},
"confirm_method": "user_manual_confirm"
}
}
核心原则:断档不等于停摆。Skill跑不了实际操作,也要告诉用户"该干什么、怎么干、数据帮你填好了"。
11.3 上游检查(每个Skill执行前必须做)
1. 检查上游Skill是否已执行(project_id + upstream skill_id 有无输出)
2. 检查关键字段是否存在且非null
3. 关键字段缺失 → exec_status="partial" + 卡片高亮"数据缺失"
4. 关键字段全缺(上游未执行)→ exec_status="failed" + "请先完成XX步骤"
12进度提示与接力棒
12.1 进度提示(输出公共信封中的progress字段)
"progress": {
"current_step": "B12 · 尽调报告生成",
"current_stage": "S1 商机与尽调",
"overall_progress": "12/31",
"next_step": "B13 · 谈判问题清单 (SK-18)",
"blocked": false
}
12.2 接力棒(确认卡片中的next_hint)
Skill执行完成后主动提示下一步,但不自动触发(auto_trigger=false),用户点击才执行。
不自动触发的原因:用户可能要先讨论/等指示。auto_trigger=true仅限A级Skill间的纯自动链(如SK-10→SK-13→SK-14风险筛查链)。
17跨FDE交接格式(6个)
Day 1开工前对齐会确认。格式变更必须通知全员并升大版本号。
交接1:尽调数据包 FDE-1 → FDE-2
SK-08+SK-14 → SK-24
{
"package_type": "due_diligence_pack",
"project_id": "PRJ-2026-0904-001",
"entity_info": {"company_name":"xxx旅游开发有限公司","credit_code":"91520...","legal_person":"张三","registered_capital":10000000},
"risk_screening": {"business_status":"normal","judicial_records":["..."],"disambiguation":"confirmed"},
"risk_score": 72, "risk_level": "medium",
"completeness": {"total":15,"provided":13,"missing":["近三年审计报告"]}
}
交接2:尽调报告 FDE-2 → FDE-3
SK-24 → SK-25
{
"package_type": "dd_report", "report_id": "DD-2026-0904-001",
"risk_level": "medium", "risk_score": 72,
"inclusion_advice": "recommend_with_conditions",
"conditions": ["需追加担保", "需季度对账"],
"key_findings": [{"finding":"存在2条被执行记录","severity":"medium"}],
"document_ref": "DD-2026-0904-001.md"
}
交接3:商务条件 FDE-2 → FDE-3
SK-23 → SK-27
{
"package_type": "business_terms", "business_type": "package_ticket",
"terms": {
"pricing": {"purchase_price":800000,"selling_price":950000},
"payment": {"method":"prepay_50_pct","prepay_amount":400000},
"guarantee": {"type":"deposit","amount":200000},
"non_standard_clauses": ["..."]
},
"four_flow_check": "passed", "deviations": ["..."]
}
交接4:合同结构化 FDE-3 → FDE-4
SK-27 → SK-45
{
"package_type": "contract_structured", "contract_id": "CT-2026-0904-001",
"clauses": [
{"clause_id":"CL-001","type":"refund","title":"退票及退款条款","key_terms":{"refund_rate":0.8}},
{"clause_id":"CL-002","type":"payment","title":"付款条款","key_terms":{"prepay_rate":0.5}}
],
"document_ref": "CT-2026-0904-001.md"
}
交接5:风险基线 FDE-1 → FDE-4
SK-10~14 → SK-47
{
"package_type": "risk_baseline", "baseline_date": "2026-09-04",
"snapshot": {"business_status":"normal","judicial_count":2,"opinion_sentiment":"neutral","risk_score":72},
"monitor_fields": ["business_status","judicial_count","opinion_sentiment"]
}
交接6:全链路执行记录 F1+F2+F3 → FDE-4
全部Skill → SK-48+SK-50
{
"package_type": "execution_log",
"timeline": [{"skill_id":"SK-01","exec_time":"2026-09-04T10:00:00+08:00","duration_sec":15,"confirm_result":"auto"}],
"statistics": {"total":31,"auto":17,"confirmed":10,"modified":3,"rejected":1}
}
格式变更协议:①每日站会提出 ②全体确认 ③当天18:00前更新文档并通知全员。禁止单方面修改。
19冲突检测矩阵(交付前必跑)
19.1 触发词冲突检测
| 触发词 | SK-07 | SK-08 | SK-14 | SK-22 | SK-29 | SK-34 | SK-42 | SK-44 |
| 检查 | 冲突 | 冲突 | 冲突 | 冲突 | 冲突 | 冲突 | 冲突 | 冲突 |
| 检查资料完整性 | ✓主 | — | — | — | — | — | — | — |
| 检查主体一致性 | — | ✓主 | — | — | — | — | — | — |
| 算评分 | — | — | ✓主 | — | — | — | — | — |
| 检查条款偏离 | — | — | — | ✓主 | — | — | — | — |
| 检查材料一致 | — | — | — | — | ✓主 | — | — | — |
| 检查签署要件 | — | — | — | — | — | ✓主 | — | — |
单动词"检查"8路冲突,加业务对象后全部消解。交付前对50个主触发词跑一遍冲突检测。
19.2 交付前必跑8项检测
| 检测项 | 方式 | 通过标准 |
| 触发词冲突检测 | 脚本 | 50个主触发词两两不冲突 |
| 职责重叠检测 | 人工 | 每对相似Skill有区分原则 |
| SOP覆盖检测 | 矩阵 | B00-B30+2隐性步骤,每步有Skill |
| Prompt长度检测 | 脚本 | 全部≤2,000 token |
| Schema一致性 | 脚本 | 6个交接格式字段一致 |
| 上下文模拟 | 手动 | 50个Skill安装后常驻≤15K |
| 包票前6步串联 | 手动 | Hermes上对话走通B00-B23 |
| should-not-trigger | 脚本 | 每个Skill的"不该触发"用例全部通过 |
19.3 自动验证脚本(skill-validator)
对标Agent Skills社区的 skill-validator 和 skills-ref CLI。开发一个Node.js验证脚本,自动检测以下项目,减少人工验收时间:
# 运行验证(在skills/根目录执行)
node _shared/validate.js
// 验证项目:
1. 结构检测:每个Skill目录是否有SKILL.md
2. 字段检测:SKILL.md frontmatter 10字段是否齐全
3. 命名检测:目录名==skill_name_en,kebab-case
4. 描述检测:description 100-200字,含"做什么+何时触发+不做什么"
5. 触发词冲突:50个主触发词两两编辑距离和语义相似度
6. Prompt长度:SKILL.md body ≤2,000 token(按1 token≈1.5字估算)
7. allowed_tools:白名单字段格式合法
8. 测试文件:tests/下有should_trigger.json和should_not_trigger.json
9. 交接格式:6个交接Schema字段名/类型/枚举值一致
10. CHANGELOG:每个Skill目录有CHANGELOG.md
// 输出:
✓ SK-01: 10/10 passed
✗ SK-07: 9/10 failed — description仅82字(需100-200字)
✗ SK-24: 8/10 failed — references/目录缺失,Prompt 2,400 token超限