Agent Skills 是什么？用一个最小案例给 AI 增加可复用技能

Agent Skills 是把任务规则、操作步骤和配套资源封装成可重复调用能力的一种方式。它比临时提示词更稳定：技能文件说明何时触发、怎样执行、哪些边界不能越过，脚本和模板则负责重复且确定的工作。

你每天都要提醒 AI “先读规范、再检查文件、最后输出报告”，换个对话又得重说一遍。这类稳定流程适合沉淀为 Agent Skills。本文用一个“检查 Markdown 标题”的最小案例，讲清技能目录、SKILL.md、触发规则、资源组织和验证方法。今天这篇文章，编程狮带你从一段重复提示词开始，做出第一个可维护的 AI 技能。

一、Agent Skills 与普通提示词有什么区别

普通提示词解决当前对话的问题，Agent Skills 解决反复出现的一类任务。一个技能通常包括使用说明、触发范围、执行步骤，以及脚本、参考资料或模板等资源。它的目标不是让提示词变长，而是让任务方法可以版本化、复查和复用。

可以把普通提示词想成口头交代，把 Agent Skills 想成岗位操作手册。口头交代适合临时事项；操作手册适合每天都要做、步骤固定、遗漏会造成损失的流程。

如果想先看更多技能设计案例，可以阅读 AI 编程技能教程。本文使用的目录和字段应以你所用平台的实际规范为准，不同 Agent 系统可能有不同的发现与加载方式。

二、从一个最小技能目录开始

先创建一个只做一件事的技能：检查 Markdown 文件是否只有一个 H1，并报告缺少标题或标题过多的问题。

markdown-heading-checker/
├── SKILL.md
└── scripts/
    └── check_headings.py

SKILL.md 是给 Agent 阅读的主说明，scripts 放可以重复执行的确定性逻辑。复杂技能还可以增加 references、assets 或 templates，但最小案例不需要先把目录铺满。

技能名应描述能力，不要使用“万能助手”这类宽泛名称。目录越清楚，Agent 越容易在正确场景触发，也越不容易把不相关请求拉进来。

三、编写可触发、可执行的 SKILL.md

一个实用的 SKILL.md 至少回答四个问题：技能做什么、何时使用、按什么步骤做、哪些事情不做。下面是最小示例：

---
name: markdown-heading-checker
description: 检查 Markdown 文件的标题层级。用户要求检查 Markdown 结构、H1 数量或标题跳级时使用。
---

# Markdown 标题检查

1. 找到用户指定的 Markdown 文件。
2. 运行 scripts/check_headings.py。
3. 报告 H1 数量和标题跳级位置。
4. 只有用户明确要求修复时才修改文件。

不要检查正文事实，也不要自动改写文章内容。

description 要同时写清能力和触发条件。正文步骤使用动作动词，并说明只读检查与写入修改的授权边界。最后一句“不要做什么”非常重要，它能防止技能从结构检查扩张成整篇重写。

💡 小提示：把对结果影响最大的规则放在主文件里。很少使用的背景资料再放 references，避免 Agent 每次都读大量无关内容。

四、把确定性检查交给脚本

让模型自己数标题容易受代码块和文本干扰，确定性规则更适合脚本。下面的 Python 脚本忽略代码围栏，统计 H1，并检测标题层级一次跳过两级以上的情况。

import re
import sys
from pathlib import Path


def check_markdown(path):
    text = Path(path).read_text(encoding="utf-8")
    in_code = False
    headings = []

    for number, line in enumerate(text.splitlines(), start=1):
        if line.startswith("```"):
            in_code = not in_code
            continue
        if in_code:
            continue

        match = re.match(r"^(#{1,6})\s+(.+)$", line)
        if match:
            headings.append((number, len(match.group(1)), match.group(2)))

    h1_count = sum(level == 1 for _, level, _ in headings)
    jumps = []
    for previous, current in zip(headings, headings[1:]):
        if current[1] > previous[1] + 1:
            jumps.append((previous[0], current[0]))

    return h1_count, jumps


if __name__ == "__main__":
    count, jumps = check_markdown(sys.argv[1])
    print(f"H1 count: {count}")
    for start, end in jumps:
        print(f"Heading level jump: line {start} -> line {end}")
    raise SystemExit(0 if count == 1 and not jumps else 1)

脚本通过退出码表达成功或失败，Agent 只负责解释结果。这种分工比让模型自由判断更稳定：规则能测试，输出能比较，失败位置也能复现。Python 语法不熟悉时，可以查阅 Python3 基础教程。

五、设计触发规则和资源边界

Agent Skills 最常见的问题不是写不出步骤，而是触发范围太宽。描述里如果只写“用于处理文档”，任何文档请求都可能加载它；改成“检查 Markdown H1 数量和标题跳级”就清楚得多。

可以用三条规则收紧边界：

1. 写明输入类型，例如 Markdown 文件而非所有文档；
2. 写明用户意图，例如检查结构而非写作、翻译或事实核验；
3. 写明修改权限，例如默认只报告，明确要求后才修复。

资源也遵循最小原则。脚本只接收目标文件路径，不扫描整块磁盘；模板只用于报告格式，不覆盖用户文章；参考资料只加载与当前检查相关的章节。技能能够读取资源，不代表每次都应该读取全部资源。

如果能力需要外部服务、认证或额外命令，再考虑插件等更大的扩展形式。Codex 插件参考 可以帮助你区分“一个本地工作方法”和“包含多种能力的扩展包”。

5.1 怎样测试一个 Agent Skill

技能测试至少包括触发、正确执行、不误触发和失败恢复四类。只测试成功样本，很容易得到“演示可用、实际不稳”的结果。

还要给脚本准备测试文件：无 H1、两个 H1、H2 直接跳到 H4、代码块内含伪标题，以及完全正常的文章。每次修改技能后重新运行这些样本，避免修复一个规则又破坏另一个规则。

5.2 什么时候应该拆分 Agent Skills

一个技能如果同时负责写文章、发布 CMS、分析流量和发送通知，触发会变得模糊，权限也难控制。更合适的做法是拆成选题、写作、质检和发布四个技能，再由上层流程按需要组合。

拆分信号包括：输入类型明显不同、权限等级不同、失败处理不同、资源越来越多，或者主文件已经很难在一次阅读中理解。拆分后每个技能仍应拥有完整出口条件，不能依赖模型猜测“差不多就进入下一步”。

Agent Skills 的价值最终体现在可维护性：规则变化时只改一处，脚本可以测试，失败能定位，用户也知道它将做什么。技能不是提示词收藏夹，而是一份带边界的执行契约。

总结

Agent Skills 把重复任务中的触发条件、执行步骤、脚本和边界组织成可复用能力。最小技能从一个清楚名称、一份 SKILL.md 和一个确定性脚本开始，不需要先搭建庞大框架。

你需要带走三点：description 要写清何时触发；规则判断尽量交给可测试脚本；默认权限应保持最小。下一步可以从你每周重复三次以上的一个任务入手，把稳定步骤写成技能，再补五类测试样本。

延伸学习

想继续把技能用于真实开发，可以按这个顺序：

1. 先学 Lingma AI 开发实战课程，理解 AI 能力怎样进入工程工作流；
2. 再读 AI 制作前端项目笔记，观察任务怎样拆成可执行步骤；
3. 最后查看 Codex 安装参考，确认本地运行环境的基础配置。

常见问题

Q：Agent Skills 和保存提示词有什么区别？

保存提示词主要复用文字，Agent Skills 还会定义触发条件、步骤、资源和权限边界，并能调用脚本完成确定性操作。任务简单时保存提示词足够，流程稳定且反复执行时技能更合适。

Q：一个技能文件写得越长越好吗？

不是。主文件应保留每次执行都需要的关键规则，背景资料和大样例放到按需读取的参考文件中。过长会增加噪声，也会让真正重要的边界被淹没。

Q：Agent Skill 一定要包含脚本吗？

不一定。纯写作规范可以只有说明和模板。但只要任务包含计数、校验、转换或批处理，脚本通常更可靠，也更容易通过固定样本测试。

Q：怎样防止技能误修改文件？

把默认行为写成只读，明确修改需要用户授权；脚本接收具体文件路径，不使用宽泛目录；执行前列出目标，修改后保留检查结果和可恢复方式。