Agent Skills 入门：把“公司 SOP + 工具脚本”封装成可复用技能，让 Agent 真正在你团队里干活（并对比 MCP）

Agent Skills 入门：把"公司 SOP + 工具脚本"封装成可复用技能，让 Agent 真正在你团队里干活（并对比 MCP）

一句话结论：

Agent Skills 解决的是"模型拿到信息后该怎么做"（流程、规则、格式、脚本）；MCP 解决的是"模型怎么安全拿到信息/调用系统"（数据与工具连接）。两者组合，才是企业里真正能落地的 Agent 形态。

---

1）为什么 2025 之后 Agent Skills 变成"行业通用设计模式"？

如果你做过 Agent 落地，会发现最痛的不是模型不聪明，而是两件事：

• 每次都要重复贴一堆要求（格式、禁忌、审批口径、语气、字段表...）
• Prompt 越写越长，越不稳定、越贵、越难维护（上下文被吃光）

Anthropic 在 2025-10-16 的工程文章里把这个问题抽象成一个清晰的答案：把"可复用的流程知识"打包成 Skill 文件夹，由 Agent 动态发现 + 按需加载，把通用模型变成贴合你工作方式的专用 Agent。

之后又把这一机制推进为开放标准（规范与 SDK 放到 agentskills.io / GitHub），强调"写一次，到处用"。

---

2）Agent Skill 是什么？别把它只当"长 Prompt"

官方定义非常工程化：Skill = 一个文件夹，里面包含：

• SKILL.md（必选）：YAML 元数据 + 规则正文（写清"何时触发/如何输出/禁止什么"）
• reference/*.md（可选）：更长的制度、手册、条款、模板，需要时才读（省 token）
• scripts/*（可选）：让 Agent 执行脚本完成确定性动作（上传、校验、转换等），脚本通常不需要被"读进上下文"。

你可以把它理解成：给 Agent 的「入职手册 + 参考资料库 + 工具箱」。

---

3）核心机制：渐进式披露（Progressive Disclosure）------为什么它省 token 又更稳？

Claude Code/Agent 采用三层加载策略：

1. 元数据层（总加载）：只加载每个 Skill 的 name + description（像目录）
2. 指令层（命中才加载）：如果模型判断该 Skill relevant，才把 SKILL.md 正文读进上下文
3. 资源层（按需中的按需）：reference 仅在需要时读取；scripts 仅在需要时执行

用一张图记住它：
Model(Claude) Client(Claude Code/IDE) User Model(Claude) Client(Claude Code/IDE) User 请求：总结会议，并标出预算风险，最后上传 请求 + 所有Skills的(name/description) 命中：meeting-notes-skill 读取SKILL.md正文 + 用户输入 生成纪要，判断需要财务规则与上传动作 读取reference/finance.md（仅此时） 执行scripts/upload.py（仅此时） 返回：纪要 + 财务提醒 + 上传结果

官方建议：SKILL.md 正文尽量控制在 500 行以内，超过就拆 reference。

---

4）5 分钟实战：做一个"会议纪要 + 财务提醒 + 自动上传"的完整 Skill（可直接拷贝）

下面给你一个可发布到 CSDN 的 Demo 级工程：既有基础用法，也覆盖 reference 与 scripts。

4.1 目录结构（建议这样组织）

meeting-notes-pro/
├── SKILL.md
├── reference/
│   ├── finance-policy.md
│   └── style-examples.md
└── scripts/
    ├── check_budget.py
    └── upload.py

Claude Code 文档给了类似的 multi-file skill 结构：SKILL.md 做导航，reference 按需加载，scripts 直接执行。

---

4.2 SKILL.md（核心：写清"何时用/怎么写/什么时候读 reference/什么时候跑脚本"）

---
name: meeting-notes-pro
description: 会议纪要/行动项生成 + 预算合规提醒 + 可选上传。用于会议录音转写、周会纪要、站会总结。用户提到"纪要/总结/会议记录/行动项"时使用。
---

目标

把用户提供的会议内容整理成可执行的纪要，并在需要时：

• 触发【财务合规提醒】（仅在提到预算/采购/费用/金额等时）
• 触发【上传】（仅在用户明确说上传/同步/发送到服务器/保存到XXX时）

输出格式（必须遵守）

1) 基本信息

• 会议主题：
• 时间：
• 参会人：未提供则写"未提供"

2) 议题列表（按出现顺序）

• 议题1：
• 议题2：

3) 结论（每条一句话）

• ...

4) 行动项（必须结构化）

行动项	Owner	截止时间	验收标准
...	...	...	...

缺失字段一律写"待确认"，禁止臆测。

5) 风险与待确认（<=5条）

• ...

质量规则

• 不要发明不存在的人名/金额/时间
• 原文含糊时：写"待确认"并列出要问的问题
• 语气：简洁、可执行、偏工程化

进阶能力：按需加载（Progressive Disclosure）

A. 财务合规提醒（仅在触发词出现时）

触发词包含：预算/采购/报销/费用/金额/合同/发票/付款

当触发时：

1. 读取并参考 <reference/finance-policy.md>
2. 把会议里出现的金额与规则对照，输出"是否超标/需要谁审批/缺哪些材料"

B. 风格示例（仅当用户要求"按某格式/按某风格"时）

读取 <reference/style-examples.md>

C. 自动化脚本（仅在用户明确要求时）

• 若用户要求"检查预算是否超标/自动校验金额"，执行 scripts/check_budget.py
• 若用户要求"上传/同步/发送到服务器/保存到某处"，执行 scripts/upload.py
  执行脚本后，把脚本输出（成功/失败原因/返回链接等）写入最终答复。

关键点：description 要具体，包含"做什么 + 什么时候用"，官方也明确反对"does stuff"这类模糊描述。

---

4.3 reference/finance-policy.md（把"低频但重要"的规则拆出去）

财务合规简表（示例）

注意：这是示例模板，请按你公司的真实制度替换。

1) 采购/外包

• 单笔 <= 5,000：业务负责人审批
• 5,000 ~ 50,000：部门负责人 + 财务审批

• = 50,000：需要走采购流程 + 法务合同审核

2) 报销

• 交通/餐饮需提供发票
• 跨城差旅需说明出差事由 + 行程

---

4.4 scripts/check_budget.py（确定性校验交给代码：更可靠）

# scripts/check_budget.py
import re
import sys
from typing import List, Tuple

THRESHOLDS: List[Tuple[int, str]] = [
    (5000, "业务负责人审批"),
    (50000, "部门负责人 + 财务审批"),
]

def extract_amounts(text: str) -> List[int]:
    # 简化示例：抓"xxx元/xxx块/xxxRMB"
    nums = re.findall(r"(\d{1,9})\s*(?:元|块|RMB)", text)
    return [int(x) for x in nums]

def check(amount: int) -> str:
    if amount <= THRESHOLDS[0][0]:
        return THRESHOLDS[0][1]
    if amount <= THRESHOLDS[1][0]:
        return THRESHOLDS[1][1]
    return "采购流程 + 法务合同审核"

if __name__ == "__main__":
    text = sys.stdin.read()
    amounts = extract_amounts(text)
    if not amounts:
        print("未识别到金额：无需预算校验")
        sys.exit(0)
    for a in amounts:
        print(f"识别金额：{a} -> 建议审批：{check(a)}")

---

4.5 scripts/upload.py（示例：把纪要发到你的系统）

# scripts/upload.py
import sys
import json
import time

if __name__ == "__main__":
    content = sys.stdin.read()
    # 这里用假上传示例：真实场景替换为HTTP请求/飞书/Confluence等
    fake_url = f"https://example.com/notes/{int(time.time())}"
    print(json.dumps({
        "status": "ok",
        "url": fake_url,
        "bytes": len(content.encode("utf-8"))
    }, ensure_ascii=False))

官方最佳实践强调：脚本要解决确定性问题、错误处理清晰、依赖说明明确；避免让模型"想当然"。

---

5）Skills vs MCP：一张表讲清楚怎么选（以及常见误用）

MCP 的官方定义：它是开放标准，用于在数据源与 AI 工具之间建立安全、双向连接（MCP servers / clients）。

Skills 的官方定位：文件夹化的"指令、脚本、资源"包，让 Agent 动态发现和加载，从而更擅长特定任务。

维度	Agent Skills	MCP
解决的问题	教模型怎么做事（SOP/格式/规则/脚本）	让模型安全拿数据/调用系统（连接器/工具协议）
主要载体	文件夹 + SKILL.md + reference + scripts	MCP server / client + 协议 + 工具清单
Token 成本	低：按需加载（渐进式披露）	取决于工具调用与返回数据大小
工程边界	适合流程规则 + 轻量自动化	适合系统级连接、权限与审计、生产稳定性
常见误用	把所有制度都塞进 SKILL.md（变"巨型 prompt"）	把"写作规范/汇报模板"硬做成工具（过重）
推荐组合	MCP 拉数据 → Skills 规定产出格式/审计口径	Skills 指挥如何使用 MCP 工具（工具名需全限定）

一句话选择法：

• 你缺的是"连接数据/系统" → MCP
• 你缺的是"公司流程与标准化产出" → Skills
• 你两者都缺 → MCP + Skills 组合（最强）

---

6）上线前 Checklist：让你的 Skill "可复用、可验收、可分享"

直接抄官方 best practices 的工程化要点（我做了中文化整理）：

核心质量

• description 足够具体：包含"做什么 + 何时用"
• SKILL.md 正文 < 500 行；详细内容拆 reference
• 规则可执行：有步骤、有输出格式、有"缺失即待确认"
• 示例具体：给表格、给字段、给反例

脚本与安全

• 脚本只做确定性工作（校验/转换/上传），并有明确错误提示
• 不要把敏感凭证写死在脚本里（用环境变量/密钥管理）
• 只安装可信来源 Skill，审计 scripts 与 reference，防数据外泄

---