过去两年AI 应用开发的节奏变化很快先是 Prompt 提示词然后是带记忆和工具调用的 Agent再往后是“把复杂能力沉淀成可复用技能包”的 Agent Skills 开发思路。现在相关学习资料大量出现但真正的问题依然是同几个Agent Skills 到底要学什么、本地怎么跑通一个最小示例、技能文件怎么写、如何接 API 和批量任务以及从零基础到能交付项目需要经过哪些阶段。这篇文章会绕过“收藏等于学会”的路径依赖直接整理一套可执行的 Agent 开发线路。内容包括 Agent Skills 的定位与解决场景、环境准备、SKILL.md 技能目录设计与多技能调度、FastAPI 接口调用、批量任务思路、资源占用观察和常见排查方法。无论你是刚接触 Python 的转行者还是已经写过 API 对接的软件工程师都可以把这篇文章当作一条能够边读边动手的主线。1. Agent Skills 开发核心能力速览先快速给出 Agent Skills 学习体系的核心能力标签方便判断这套技能树是否值得投入。能力模块核心知识点练习目标常用工具/方向Agent 基础大模型 API、消息结构、提示词、结构化输出能写出稳定的对话程序OpenAI SDK、Anthropic SDK 或兼容接口工具调用function calling、tools 定义、多轮参数回填让 Agent 能自主获取信息、操作外部系统大模型工具的 tools 参数、自定义 Python 函数任务编排多步任务拆解、状态流转、条件分支能处理跨步骤真实任务LangGraph、CrewAI 等框架或自己维护状态机Agent Skills 设计技能包目录结构、SKILL.md、脚本与资源隔离能把一个业务流程封装成可复用技能Skills 目录规范、自定义技能注册表接口与工程化API 服务、鉴权、批量任务、失败重试、日志监控能上线并稳定运行FastAPI、任务队列、Docker内容与合规边界隐私保护、版权授权、模型安全能在合法合规范围内交付内部测试、权限控制、内容审核关键点在于Agent Skills 开发不是一门“纯理论学科”它更像一个以交付为目标的工程训练模型调用是基础工具调用是骨架技能包的沉淀组织方式和工作流落地才决定你能否从写 Demo 走向做产品。2. Agent Skills 到底解决什么问题要理解 Agent Skills 开发的价值先看一个还没有技能化开发的常见困境。假设你用大模型做一个“周报自动生成”功能。第一版简单粗暴把系统里拉出来的 commit 记录和任务清单塞进 Prompt让模型帮忙总结。Demo 阶段没问题但一旦要覆盖多个团队、多种报告模板、不同的数据源每加一个需求就要改 Prompt。Prompt 越写越长逻辑混杂后续维护非常困难。Agent Skills 的核心思路是不要把所有逻辑塞进一次对话或多轮对话中而是把“一类任务的处理能力”打包成独立技能包。一个技能包通常包含说明这个技能在什么时候触发、怎么使用的 SKILL.md执行具体逻辑的脚本或调用资源可选的配置项、输入样例、校验逻辑。当 Agent 判断当前用户请求属于某个技能时再加载对应的技能文件与脚本。这样做的好处是模块化每个技能负责一块明确职责Agent 主程序只负责意图判断和任务调度。新增一个业务能力时往往只需要新增一个技能包目录而不是重写整套对话逻辑。所以 Agent Skills 并不是给 Agent 换一个更高级的算法而是把智能体应用从“把所有规则写在系统提示词里”的重单文件模式改造为“清晰技能目录 文件系统化组织 按需加载”的工程模式。2025 年下半年以来以 Anthropic 公布的技能目录规范为代表的写法逐渐成为很多团队内部 Agent 工程化的参考基线。实战中这种模式可测试、可审计、可复用也更容易在多人协作时通过 Git 做版本管理。3. Agent Skills 开发适合谁边界在哪里Agent Skills 开发比较适合三种人第一种是常规后端或全栈开发者已经掌握 API 调用希望通过智能体技术把项目从“表单交互”升级为“任务型交互”。第二种是算法工程师或 Prompt 工程师大量时间花在调模型输出上但缺乏工程化封装能力想把提示词、脚本、工具调用整理成稳定交付物。第三种是 AI 应用创业者或团队技术负责人需要快速验证业务场景同时规避“同一个 Agent 越加功能越难维护”的问题。对完全没有编程基础的人来说直接学 Agent Skills 会有一定阻力。可以先补 Python 基础、命令行操作、HTTP 请求与 JSON 数据处理再用本文的案例逐步上手。使用边界同样要明确。Agent Skills 擅长的是把稳定流程变成可执行动作不等于能够处理所有模糊问题。例如完全开放式的创新策划、需要深度共情的场景大模型和技能包的效果并不稳定另外如果你的业务涉及人脸数据、声音数据、个人敏感信息或版权素材则必须在授权与隐私保护框架内使用不能在测试环境外随意调用真实数据更不能绕过服务商的权限与审核机制。开发阶段用脱敏数据验证是最基本要求。最好从一开始就在工程结构里预留权限校验、日志审计和人工审核位置这对企业场景尤其重要。4. 本地开发环境准备Agent Skills 开发以 Python 环境最方便下面给出一个可照做的本地环境检查清单具体版本以你实际安装为准。操作系统Windows 10/11、Ubuntu 20.04、macOS 均可Python建议 3.10 及以上如果同时写前端可以考虑 Node.js 18包管理推荐使用 venv 或 uv 创建虚拟环境模型服务需要一个你有权限调用的模型 API并准备好 API Key代码管理安装 Git并确保 API Key 不提交到仓库运行目录预留一个独立目录管理技能包、输入素材和输出结果。如果本机还没有虚拟环境执行下面的命令python -m venv .venv source .venv/bin/activate # Windows 使用 .venv\Scripts\activate pip install --upgrade pip如果希望环境创建更快也可以改用 uvuv venv uv pip install openai anthropic fastapi uvicorn pyyaml requests注意以上库名是常规 AI 工程组合真实项目要按你使用的模型服务和框架调整不要盲目一次性安装所有包。安装完成后可以用一段最简脚本确认模型接口可用import os # 示例从环境变量读取密钥不要把密钥硬编码到代码里 api_key os.environ.get(MODEL_API_KEY, ) if not api_key: raise RuntimeError(请在环境变量中设置 MODEL_API_KEY) print(环境变量读取成功)如果本项目需要显存信息比如后续准备跑本地模型需要提前用nvidia-smi检查驱动与显卡情况如果只调用云服务 API则不需要本地显卡。5. 从零搭建一个最小 Agent 技能包很多 Agent Skills 教程一上来就铺概念新手很容易失去抓手。更实际的做法是先搭一个最小的“技能包工程”让程序能看见技能、能选择技能、能执行技能之后再逐步增加复杂逻辑。5.1 工程目录结构下面是一个经过简化的技能包工程可以直接复制到本地agent-skills-demo/ ├── skills/ │ └── week_report/ │ ├── SKILL.md │ └── scripts/ │ └── generate_simple_summary.py ├── main.py ├── requirements.txt └── .env.example技能包的根目录是skills/week_report。这个目录里放SKILL.md用于描述技能的适用场景和调用步骤scripts/generate_simple_summary.py是执行脚本。这样设计后Agent 主程序不需要理解每个业务细节它只需要判断“任务应该让哪个技能来处理”然后把控制权交给该技能。5.2 编写 SKILL.mdSKILL.md 是全套 Agent Skills 开发中最核心的一份文件。一个最小可用的 SKILL.md 至少包含两部分文件头部的元信息以及正文的使用说明。--- name: week-report description: 根据提交记录和任务列表生成团队周报摘要适用于周报自动整理场景。 ---正文部分建议写明以下内容触发条件哪些用户请求应该使用本技能处理步骤Agent 需要按什么顺序读取输入、执行脚本、汇总结果输入要求接受哪种格式的数据输出格式预期的 Markdown、JSON 或文本限制哪些情况需要拒绝执行或转人工。# 周报生成技能 ## 使用时机 当用户提供团队成员的 commit 记录、任务完成度或工作日志并要求生成周报摘要时。 ## 执行步骤 1. 确认输入数据字段完整至少包含成员名、工作内容和完成状态。 2. 运行 scripts/generate_simple_summary.py传入 JSON 文件路径。 3. 将脚本输出的 Markdown 摘要返回给用户。 ## 输出格式 Markdown 表格 重点风险提示。 ## 限制 如果输入数据涉及敏感人员绩效信息需要提醒用户确认数据脱敏。SKILL.md 的价值不只是给人看也是给 Agent 看的“技能说明书”。所以描述语言要具体避免“处理各种周报”这样过于宽泛的写法。5.3 技能执行脚本生成脚本可以写得非常简单import argparse import json parser argparse.ArgumentParser() parser.add_argument(--input, requiredTrue, help输入 JSON 路径) parser.add_argument(--output, requiredTrue, help输出 Markdown 路径) args parser.parse_args() with open(args.input, r, encodingutf-8) as f: data json.load(f) lines [] for item in data.get(items, []): member item.get(member, 未知) content item.get(content, ) status item.get(status, 进行中) lines.append(f- {member}{content}{status}) summary \n.join(lines) with open(args.output, w, encodingutf-8) as f: f.write(summary) print(f已生成周报摘要{args.output})这个脚本不依赖大模型只是演示技能包的落地形态。真正的技能可以做得更深入比如对接数据查询、生成图表、调用外部接口。关键是形成“技能说明 - 脚本执行 - 结果回传”的稳定链路。6. 多技能注册与调度实现当技能数量增加后主程序必须有能力管理技能目录。实现方式不复杂让程序扫描skills/目录下每个子目录解析 SKILL.md 的元信息再通过简单的匹配逻辑选择技能。6.1 技能注册表把技能元信息集中到 JSON 文件是一个常见做法{ skills: [ { name: week-report, description: 根据提交记录和任务列表生成周报摘要, path: skills/week_report, entry: scripts/generate_simple_summary.py } ] }如果你不想维护 JSON也可以直接用 Python 扫描目录读取每个 SKILL.md 开头的 YAML 元信息。推荐后者因为新增技能时只需要添加技能目录不需要同步修改注册文件。使用 PyYAML 可以实现自动注册。6.2 调度逻辑示例下面是一个带基础技能选择的命令行程序import os import re import yaml SKILLS_ROOT skills def load_skills(): skills [] for skill_name in os.listdir(SKILLS_ROOT): skill_dir os.path.join(SKILLS_ROOT, skill_name) skill_file os.path.join(skill_dir, SKILL.md) if not os.path.isfile(skill_file): continue with open(skill_file, r, encodingutf-8) as f: content f.read() match re.match(r^---\n(.*?)\n---\n(.*)$, content, re.DOTALL) if not match: continue meta yaml.safe_load(match.group(1)) overview match.group(2) skills.append({ name: meta.get(name), description: meta.get(description, ), usage: overview, dir: skill_dir }) return skills if __name__ __main__: for s in load_skills(): print(f技能{s[name]}描述{s[description]})运行后控制台会输出skills/目录下所有已注册技能。从这里再往下扩展就是利用模型判断用户意图和技能描述是否匹配然后调用对应脚本。可以先不使用大模型调度仅用关键词匹配验证流程降低初次实现难度。7. 把 Agent Skills 封装成 API 并跑批量任务技能开发完成后下一步通常是交付。交付形态有两种常见选择提供 REST API 给其他系统调用或写一个批量处理任务消费脚本。7.1 FastAPI 接口示例下面用 FastAPI 做一个简单接口外部系统可以 POST 正文数据服务端选择 week-report 技能并返回处理结果。业务代码可以很轻重点是暴露出稳定的请求响应结构。import json import subprocess import tempfile from fastapi import FastAPI from pydantic import BaseModel app FastAPI() class TaskRequest(BaseModel): skill: str week-report items: list[dict] [] class TaskResponse(BaseModel): ok: bool message: str output: str app.post(/v1/run-skill, response_modelTaskResponse) def run_skill(req: TaskRequest): if req.skill ! week-report: return TaskResponse(okFalse, message暂不支持该技能) with tempfile.TemporaryDirectory() as tmpdir: input_path f{tmpdir}/input.json output_path f{tmpdir}/output.md with open(input_path, w, encodingutf-8) as f: json.dump({items: req.items}, f, ensure_asciiFalse) cmd [ python, skills/week_report/scripts/generate_simple_summary.py, --input, input_path, --output, output_path ] result subprocess.run(cmd, capture_outputTrue, textTrue) if result.returncode ! 0: return TaskResponse(okFalse, messageresult.stderr[:500]) with open(output_path, r, encodingutf-8) as f: output f.read() return TaskResponse(okTrue, message执行成功, outputoutput)启动接口服务uvicorn main:app --host 127.0.0.1 --port 8000用 curl 发起一次请求curl -X POST http://127.0.0.1:8000/v1/run-skill \ -H Content-Type: application/json \ -d { skill: week-report, items: [ {member: 张三, content: 完成Agent技能包模块设计, status: 已完成}, {member: 李四, content: 修复批量任务接口超时问题, status: 进行中} ] }如果接口返回ok: true并带有 output 内容说明技能服务已经跑通。接下来就可以把它接到内部系统或自动化流程里。7.2 批量任务设计批量执行场景下不建议在接口层直接同步处理大量任务。个人开发者或小团队可以先实现一个简单的脚本循环读取任务列表文件逐条调用技能脚本并把执行结果写入输出目录同时把失败任务单独记录下来。{ tasks: [ { id: task_001, skill: week-report, args: { items: [ {member: 王五, content: 接入企业通讯录, status: 已完成} ] } } ] }执行循环时为每个任务单独建立日志文件python batch_runner.py --tasks tasks.json --output ./results批量处理有几个工程要点任务必须带唯一 ID方便定位日志每条任务执行前记录开始时间结束后记录耗时和状态失败任务不能静默吞掉要写入 fail 目录并允许重跑如果调用大模型 API需要控制并发数避免触发限流和额外成本。当任务量继续增大时再迁移到正式任务队列例如 Redis 队列或对象存储事件触发原理和前期的“任务文件 日志重试”思路一致。8. 资源占用与性能观察Agent Skills 开发项目分为两类资源消耗。只调用云端大模型 API 的应用本地资源占用非常低主要开销是运行脚本、网络往返和少量内存。若你在本机跑开源模型则需要重点观察显存常用的观察命令是nvidia-smi返回结果中的Memory-Usage列可以看到当前显存占用。模型能跑多大、速度多快取决于量化方式、上下文长度、显卡型号和推理框架不能只看参数量。显存占用必须以本机实际运行结果为标准不同来源的“推荐显存”仅供参考。功能上影响响应速度的主要因素有输入提示词和工具描述过长大模型需要处理更多 token工具数量增加后模型自动选择技能的时间会变长技能内脚本执行时间比如爬取页面、查询数据库、处理文件批量任务并发设置过高会触发 API 限流甚至报错。如果发现响应变慢优先做两件事第一精简 SKILL.md 中的描述避免每个请求都携带大段无用说明第二把技能脚本的结果设计成可缓存结构例如周报摘要这类结果可以每天第一次生成后存入缓存相同输入不重复计算。接口服务的进程管理也值得注意。用uvicorn本地调试没问题部署时建议通过进程守护工具管理例如 systemd、pm2 或 Docker Compose。如果用了 Docker端口映射要避免占用冲突例如把宿主机 8000 映射到容器内 8000 时先确认宿主机端口空闲lsof -i :8000如果返回结果为空说明端口未被占用如果有进程占用可以换用其他端口。9. 常见问题与排查方法很多 Agent Skills 新手遇到的问题不是“概念不懂”而是“环境没通、脚本报错、技能调度不生效”。这里整理一份可复用的排查表格。问题现象可能原因排查方式解决方案安装依赖失败Python 版本过低或网络源不可达执行pip config list查看 Python 版本升级到 3.10切换可用镜像源API Key 读取失败环境变量未设置或 .env 文件未加载在代码中打印是否存在变量但不要打印完整 Key正确配置环境变量注意重启终端SKILL.md 无法解析YAML 缩进错误或字段缺失单独用 PyYAML 读取该文件观察报错位置检查 frontmatter 缩进和冒号格式技能目录扫描不到路径写错或目录没有 SKILL.md打印 os.listdir 内容核对 SKILLS_ROOT 和目录名调用大模型接口超时网络问题或上下文过长先用短文本请求测试连通性降低输入长度增加超时时间检查代理设置批量任务中途卡住某个任务脚本出现死循环或 API 重试过久查看日志中最后一条记录为脚本增加超时控制使用 subprocess timeoutAPI 服务无法访问防火墙或端口绑定为 127.0.0.1用 curl 在本机测试根据需求绑定 0.0.0.0但要注意访问安全输出包含错误 JSON模型返回内容被 markdown 代码块包裹打印原始响应再解析先提取代码块内容并清理多余字符显存不足本地模型过大或批量并发太高nvidia-smi 观察占用与进程降低 batch size开启量化或改用 API模型总调用错误工具SKILL.md 描述不够具体或相似技能干扰打印模型选择的技能名称强化描述边界增加负向条件说明排查问题的核心思路是先看日志再缩小范围最后改动代码。一次只改一个变量避免同时替换模型、改描述又重构脚本。10. 最佳实践与合规建议经过多轮 Agent Skills 开发后推荐把下面几条作为默认工程约束第一用 Git 管理技能包版本。SKILL.md 和脚本都是代码不能只在聊天窗口里调好就结束。每次修改技能都写清变更原因方便后续回滚。第二保持技能包目录扁平。一个技能只负责一类任务。如果一个技能描述里出现多种完全不相关的用法就应该把它拆分。类似“把周报技能又做成客服问答技能”的用法会降低调度准确性。第三API Key 永远不出现代码仓库。在.env.example里只放占位变量把真实.env文件加入.gitignore。如果使用 Docker应该通过环境变量注入密钥而不是写死在镜像内部。第四先小范围测试再扩展。第一次接入真实业务数据前先准备一组脱敏样本验证技能输出是否满足要求。尤其是涉及客户资料、员工信息、音频视频素材等内容时必须确认是否具备合法处理授权。不要为了演示效果直接读取未授权的个人数据。第五保留必要的人工审核出口。Agent Skills 自动化程度提高后系统自主执行的场景会变多。对于生成结果影响较大、涉及对外发布的动作应在流程中加入确认步骤。可以把“自动生成”和“自动发布”严格分开。第六评估输出质量时不能只看一两次成功。建议准备一个固定测试集包含正常输入、边界输入和恶意输入每次调整技能后都跑一遍回归测试通过后再进入上线流程。11. 总结与下一步动作Agent Skills 开发最值得投入的点不在于把某个框架背熟而在于建立“大模型 工具调用 技能包化组织 API 交付”的完整闭环。只要跑通本文的最小技能包工程后续在业务上扩展就是不断新增技能目录和对应脚本而不是每来一个需求都重新推翻主程序。如果你想直接开始动手建议按照以下顺序推进第一步先配置好模型 API 环境确认基础调用返回正常 第二步复制本文的week-report技能包改造成你自己的业务技能 第三步启动 FastAPI 服务用 curl 完成一次技能调用 第四步尝试写 3 到 5 个不同方向的技能包并设计一个简单的主程序做技能选择 第五步补充输入校验、日志和失败重试跑 100 条批量任务验证稳定性。最容易踩的坑仍然集中在前 20% 的工程量里依赖环境不一致、SKILL.md 描述含糊、脚本输入输出约定不统一。把前两步的细节打牢后面越做越顺。这篇内容可以先收藏等到你要设计自己的技能目录时再拿前面的工程结构对照检查。