这次我们来看一个在 LLM 应用层越来越绕不开的概念Agent Skills。与之配套的还有一套最近社区讨论热度很高的落地方法——Karpathy 提出的 LLM Wiki 思路。简单说这俩东西结合起来解决的是同一个问题怎么把大模型从“只会聊天”变成“能干活”而且干活的技能还能沉淀、复用、迭代而不是每次都在 Prompt 里靠人肉堆字数。先说结论Agent Skills 不是什么高不可攀的框架它本质上就是一套“给大模型配技能”的组织方式。而 LLM Wiki 更直接它主张用普通 Markdown 文件来定义技能、存储知识、编排流程不需要搞复杂的 Agent 框架也能让 LLM 完成相当完整的任务闭环。这篇文章就按“概念 → 方法 → 落地 → 实战 → 排错”的顺序带你把这条链路完整走一遍。文章会覆盖以下实操内容Agent Skills 核心概念拆解、Karpathy LLM Wiki 方法论解读、Agent.md 标准模板设计、Python 技能加载器实现、批量任务与 API 调用示例、常见问题排查。适合同样在折腾 LLM Agent 的开发者、对知识库/文档自动化有需求的效率党以及想把大模型接入自己工作流的人。1. Agent Skills 核心能力速览能力项说明项目类型LLM Agent 技能组织与编排方法核心思想将 Agent 可执行的能力拆分为独立“技能”以文件/模板形式存储代表方法Agent Skills LLM Wiki技能载体Markdown 文件如 Agent.md、参考文档、示例文件依赖基础LLM API 或本地部署的大模型服务运行环境Python 3.8任意支持 OpenAI 兼容接口的模型服务核心功能任务规划、工具调用、文档处理、知识检索、批量执行批量任务支持通过循环调用 缓存 失败重试实现接口 API支持模型服务本身提供 API技能库作为 Prompt/上下文组装层可扩展性高新增一个技能 新增一个文件适合场景论文写作辅助、文档问答、批量整理、知识库构建、Agent 应用开发从资源占用角度看Agent Skills 本身不消耗额外算力真正的开销来自底层 LLM 服务的推理成本。如果你用的是云端 API按 token 计费如果本地部署才需要关注显存占用具体数值取决于模型规模和量化版本。这一点后面会展开讲。2. 为什么需要 Agent Skills先把问题摆出来。直接用 LLM 做复杂任务会碰到几个很现实的痛点上下文窗口有限。一次对话能塞的内容有限文档一长就超限。Prompt 不稳定。同样的任务提示词写得不一致输出质量就飘。能力不可复用。别人写好的高质量 Prompt换个场景又得重写。工具调用靠手工。让模型调函数、读文件、跑脚本每次都现场商量。知识无法沉淀。做完一个任务经验没有留下来下次从零开始。Agent Skills 要解决的就是这五个问题。你可以把 Agent Skills 理解为“给大模型配的一套职业技能包”。每个技能包含任务定义、执行步骤、输入输出格式、参考示例、注意事项。当 Agent 收到用户请求时不是直接裸问模型“请帮我写一篇论文”而是先从技能库里找到对应的技能文件把技能描述 用户请求 上下文一起组装成最终的 Prompt再发给 LLM。这样做的好处很明显技能是标准化的质量可控。技能是文件化的方便管理和版本迭代。技能是组合式的多个基础技能可以拼出一个复杂工作流。技能是共享的团队内部可以直接复制使用。所以Agent Skills 不是某个框架的专有名词而是一种设计模式。无论你是用 LangChain、Dify、Coze还是自己写代码调 API都可以采用这套思路。而 Karpathy 的 LLM Wiki则是这种模式的一种极简实现方案。3. LLM Wiki 方法论让大模型用文件系统思考Andrej Karpathy 提出的 LLM Wiki 方法核心主张可以概括成一句话用普通文本文件作为 LLM Agent 的记忆和技能存储介质用文件夹作为组织结构用 Agent.md 作为每个任务的入口文件。为什么这个思路被很多人称为“2026 年最值得关注的方法论”因为它足够简单简单到不需要引入任何重量级框架。3.1 文件即技能在 LLM Wiki 体系里一个技能就是一个文件夹一个任务就是一个 Markdown 文件。比如llm-wiki/ ├── Agent.md ├── skills/ │ ├── keyword-research/ │ │ ├── Agent.md │ │ ├── example-input.txt │ │ └── reference.md │ ├── pdf-summary/ │ │ ├── Agent.md │ │ └── output-template.md │ └── web-research/ │ ├── Agent.md │ └── steps.md ├── documents/ │ ├── 论文A.pdf │ └── 素材集/ └── outputs/ └── 2026-01-01/每个技能文件夹里的 Agent.md就是这个技能的“岗位说明书”。LLM 读取这个文件后就知道自己在这个任务里扮演什么角色、需要做什么、按照什么步骤做、输出什么格式。3.2 Agent.md 标准模板一个合格的 Agent.md 应该包含这些区块# 角色 你是一个专业的中文科技论文写作助手。 # 任务 根据用户提供的原始素材生成一篇结构完整的论文初稿。 # 输入 - 原始素材路径documents/论文A.pdf - 目标字数5000-8000字 - 输出语言中文 # 执行步骤 1. 阅读素材提取核心观点。 2. 列出论文大纲交给用户确认。 3. 根据大纲逐节撰写。 4. 输出Markdown格式的完整文稿。 # 输出格式 Markdown文档包含一级/二级标题、正文段落。 # 注意事项 - 引用真实文献时必须标注来源。 - 语言风格要求客观、严谨。 - 避免重复素材中已有的表述。 # 参考示例 见 example-input.txt 和 output-example.md这段模板看起来平平无奇但它的威力在于你可以给不同的任务写不同的 Agent.md然后让同一个 LLM API 去执行而模型会按照文件里的定义切换行为模式。这就是“技能”的本质——不是模型变了而是给模型的指令变了。3.3 与 Obsidian 结合的扩展玩法LLM Wiki 的另一个亮点是可以直接和 Obsidian 这类笔记软件结合。因为 Obsidian 本身就是用 Markdown 文件管理笔记天然支持文件夹结构、双链、标签。你可以在 Obsidian 里建一个“LLM Wiki”仓库。每个 Agent 任务对应一个笔记文件。笔记的 Front Matter 填写任务元数据角色、输入、输出。笔记正文填写详细指令。写个脚本把这个仓库同步给 LLM API。这样你的知识库不只是给人看的也能被大模型“看懂”并利用。Obsidian 负责管理Python 脚本负责桥接LLM API 负责执行。整个过程轻量、透明、可控。4. 环境准备与前置条件动手之前先确认环境。Agent Skills 的落地依赖很低核心就两样一个 LLM 服务 一个 Python 运行环境。检查项要求说明操作系统Windows / macOS / Linux均可差异主要在路径写法Python3.8 及以上推荐 3.10LLM API任意 OpenAI 兼容接口如 OpenAI、DeepSeek、Qwen、本地 vLLM 等网络能访问模型服务本地部署则不需要外网可选工具Obsidian用于管理和编辑技能库磁盘技能库本身几乎不占空间主要是文档素材占用如果走本地部署路线需要额外准备 CUDA、模型权重等这里不展开后续单独写一篇本地部署实测。5. 从零搭建一个 Agent 技能库下面进入实操。先建目录结构再写技能文件最后用 Python 把技能加载成 Prompt。5.1 创建技能库目录mkdir -p llm-wiki/{skills,docs,outputs} mkdir -p llm-wiki/skills/tech-writer5.2 编写技术写作技能的 Agent.md# 角色 你是资深技术博客作者擅长将技术项目写成通俗易懂的教程。 # 任务 根据用户提供的项目描述输出一篇适合发布在技术社区的博客文章。 # 输入 - 项目描述来自用户的原始信息 - 输出字数3000-5000字 - 目标平台技术博客 # 执行步骤 1. 提取项目核心卖点。 2. 确定文章结构概念、速览、环境准备、实操、排错。 3. 按结构逐段撰写使用Markdown格式。 4. 最后检查一遍确保技术细节准确。 # 输出格式 Markdown正文不得包含任何前言或后记。 # 注意事项 - 代码块必须标注语言类型。 - 所有命令必须可直接复制运行。 - 不确定的信息不要编造。5.3 Python 技能加载器这一步是核心代码。我们把技能文件读取出来和用户请求拼接成一个完整的 Prompt再调用模型服务。import os from pathlib import Path from openai import OpenAI # 模型服务配置换成你自己的 API Key 和接口地址 client OpenAI( api_keyyour-api-key, base_urlhttps://api.example.com/v1, ) SKILLS_DIR Path(./llm-wiki/skills) def load_skill(skill_name: str) - str: 读取技能目录下的 Agent.md 文件 skill_path SKILLS_DIR / skill_name / Agent.md if not skill_path.exists(): raise FileNotFoundError(f技能未找到: {skill_name}) return skill_path.read_text(encodingutf-8) def build_prompt(skill_name: str, user_input: str) - str: 组装最终 Prompt skill_prompt load_skill(skill_name) return f{skill_prompt} # 用户请求 {user_input} def run_agent(skill_name: str, user_input: str, model: str gpt-4o-mini): prompt build_prompt(skill_name, user_input) response client.chat.completions.create( modelmodel, messages[ {role: system, content: 你是一个严格执行技能定义的 AI Agent。}, {role: user, content: prompt}, ], temperature0.7, ) return response.choices[0].message.content if __name__ __main__: result run_agent( skill_nametech-writer, user_input写一篇关于本地部署OCR工具的博客, ) print(result)这段代码就构成了一个最简单的 Agent 运行时。run_agent函数接收技能名称和用户请求返回生成结果。后续所有功能扩展都可以在这个框架上叠加。6. 实战案例一论文写作辅助先看一个最常见的场景用 Agent Skills 辅助论文写作。传统做法是直接把论文要求写在 Prompt 里问题是要求一多Prompt 就乱效果不稳定。用技能库的方式可以拆解成“大纲生成技能”“段落撰写技能”“润色技能”三个独立技能。6.1 大纲生成技能# 角色 你是学术写作专家。 # 任务 根据给定的研究主题生成论文大纲。 # 输入 - 研究主题来自用户 - 论文字数8000字 # 输出格式 Markdown 列表包含一级/二级/三级标题。 # 注意事项 - 大纲必须逻辑清晰各部分权重合理。 - 标题使用学术表达避免口语化。6.2 调用批量生成大纲import json topics [ 基于大语言模型的文档自动分类方法研究, 低资源条件下的少样本学习技术综述, 多模态数据的语义对齐与融合算法, ] for i, topic in enumerate(topics, 1): print(f正在处理第 {i} 个主题{topic}) outline run_agent(paper-outline, topic) output_path f./outputs/outline_{i}.md with open(output_path, w, encodingutf-8) as f: f.write(outline) print(f已保存到 {output_path})这个案例展示了 Agent Skills 在批量任务上的优势同一个技能文件套用多个输入就能批量产出结构一致的结果。对论文开题、课题申报这类重复性较强的写作需求效率提升非常明显。6.3 分技能写作流程更完整的做法是分阶段调用不同技能# 第1步生成大纲 python run_agent.py paper-outline 你的研究主题 # 第2步根据大纲撰写段落 python run_agent.py paragraph-write 段落标题素材 # 第3步全文润色 python run_agent.py paper-polish 论文初稿每个技能保持独立可以单独测试、单独优化。这比一个巨大的 Prompt 好维护得多。7. 实战案例二知识库问答与文档处理第二个场景更贴近日常工作知识库问答。很多人想做文档问答但不知道从哪下手。用 LLM Wiki 的思路可以做个非常轻量的版本。7.1 文档切分与索引构建from pathlib import Path def read_documents(doc_dir: str) - list[dict]: 读取 docs 目录下的所有支持文件返回文档片段列表 docs [] doc_path Path(doc_dir) for md_file in doc_path.rglob(*.md): content md_file.read_text(encodingutf-8) # 简单的按标题切分实际项目可换成更精细的策略 chunks content.split(\n## ) for idx, chunk in enumerate(chunks): docs.append( { id: f{md_file.stem}_{idx}, file: str(md_file), content: chunk.strip(), } ) return docs7.2 查询时检索相关片段def search_docs(docs: list[dict], query: str, top_k: int 3) - list[dict]: 最简单的关键词检索实际可替换为向量检索 scored [] query_words set(query.lower().split()) for doc in docs: content_lower doc[content].lower() score sum(1 for w in query_words if w in content_lower) if score 0: scored.append((score, doc)) scored.sort(reverseTrue) return [doc for _, doc in scored[:top_k]]7.3 用技能文件定义回答格式# 角色 你是知识库问答助手。 # 任务 根据给定的检索片段回答用户问题。 # 输入 - 用户问题根据实际传入 - 检索片段如下 # 执行步骤 1. 阅读检索片段。 2. 只从片段中提取答案。 3. 如果片段不能回答明确告知。 # 输出格式 先给结论再给出处引用。 # 注意事项 - 禁止编造片段中不存在的信息。 - 引用时需要标注片段文件名。这个方案虽然不是完整的 RAG没有向量化、没有重排序但作为演示 Agent Skills 的串联能力已经足够。核心是技能文件负责约束回答方式检索代码负责提供上下文两者结合就能获得一个行为稳定、来源可追溯的问答助手。8. 批量任务、API 调用与错误处理很多实际需求是批量处理几十个文件、几十个话题、几十次调用的循环。Agent Skills 在这种场景下优势很大因为技能一旦定好批量跑就是纯工程问题。8.1 批量任务脚本模板import time import json from pathlib import Path from typing import Callable def batch_run( items: list, process_func: Callable, output_dir: str ./outputs, max_retries: int 3, delay: float 1.0, ): 通用批量任务执行器 output_path Path(output_dir) output_path.mkdir(parentsTrue, exist_okTrue) success_count 0 fail_count 0 results [] for idx, item in enumerate(items, 1): print(f[{idx}/{len(items)}] 处理中...) for attempt in range(1, max_retries 1): try: result process_func(item) results.append({item: item, result: result, status: success}) success_count 1 break except Exception as e: print(f 第{attempt}次失败: {e}) if attempt max_retries: results.append({item: item, error: str(e), status: failed}) fail_count 1 time.sleep(delay * attempt) # 保存结果和日志 with open(output_path / results.json, w, encodingutf-8) as f: json.dump(results, f, ensure_asciiFalse, indent2) print(f完成成功 {success_count}失败 {fail_count})8.2 API 调用封装在实际业务中你可能希望把这个 Agent 能力暴露成 HTTP API方便接到自己的工具链里。用 FastAPI 可以快速实现from fastapi import FastAPI, HTTPException from pydantic import BaseModel app FastAPI(titleAgent Skills API) class SkillRequest(BaseModel): skill_name: str user_input: str model: str gpt-4o-mini class SkillResponse(BaseModel): skill_name: str output: str app.post(/agent/run, response_modelSkillResponse) async def run_skill(req: SkillRequest): try: output run_agent(req.skill_name, req.user_input, req.model) return SkillResponse(skill_namereq.skill_name, outputoutput) except FileNotFoundError: raise HTTPException(status_code404, detailf技能不存在: {req.skill_name}) except Exception as e: raise HTTPException(status_code500, detailstr(e)) app.get(/health) async def health(): return {status: ok}启动 API 服务uvicorn main:app --host 127.0.0.1 --port 8000测试调用curl -X POST http://127.0.0.1:8000/agent/run \ -H Content-Type: application/json \ -d {skill_name: tech-writer, user_input: 写一个关于Docker的文章}这样一个带技能编排的 API 服务就跑起来了。你可以叫它 Agent Service也可以叫它 Skill Runner本质上都是一个东西把 Agent Skills 封装成独立服务供上层应用调用。8.3 批量失败重试策略建议指数退避重试间隔从 1s 开始每次翻倍避免打爆 API 限流。输出缓存相同输入不重复调用省 token。断点续跑处理完的条目记录状态重启后跳过已完成项。日志完整每条任务的输入、输出、耗时、错误都写日志。限流控制控制每秒请求数防止被限流封禁。9. 性能与资源观察Agent Skills 这个体系本身的资源开销非常小真正的瓶颈在 LLM 推理。9.1 Token 消耗分析环节Token 消耗优化方式技能文件读取每技能约 500-1500 token精简 Agent.md只保留必要内容检索片段注入每片段约 200-500 token控制 top_k只注入最相关内容历史对话随轮数线性增长设置最大轮数超出后裁剪系统提示词固定约 100-300 token保持简短所以每个请求的 token 开销大约在 800-2500 token 之间。按市面上主流 API 价格计算一次完整任务的成本通常在几分钱到几毛钱之间具体取决于模型档次和输入长度。9.2 延迟优化建议小模型优先任务简单时用 mini 档模型复杂再用大模型。并发控制批量任务用线程池控制并发不是越多越好。就近接入API 服务选择离模型服务近的网络节点减少延迟。结果缓存常见问题直接命中缓存跳过模型调用。9.3 本地部署时的显存观察如果换成本地部署的模型如 Qwen 系列、Llama 系列才会涉及显存占用。以下是可以重点观察的指标显卡占用率nvidia-smi显存使用量模型加载后就固定占一块推理耗时从请求发出到响应返回的时间并发处理能力同时处理多个请求时显存会被重复使用实际所需显存与模型参数量、量化精度强相关。更稳妥的判断是先用 API 跑通业务逻辑确认效果后再考虑本地化部署优化成本。10. 常见问题与排查方法问题现象可能原因排查方式解决方案技能文件读取失败路径写错或文件不存在检查 SKILLS_DIR 路径和文件名确认目录结构使用绝对路径API 调用超时网络波动或模型推理慢查看错误码和日志增加 timeout开启重试机制生成结果与技能定义不符Prompt 中技能指令被稀释检查技能文件是否被完整加载技能描述前置减少冗余上下文批量任务卡住单次请求未设置超时检查进程状态和日志给每个请求设置 timeout 上限Token 消耗过高历史记录太长查看请求日志的 token 数裁剪上下文减少轮数输出格式混乱技能文件格式定义不清晰检查输出格式描述给出更具体的示例或用 few-shot本地模型显存不足模型体积超过显存nvidia-smi 查看占用换更小的量化模型或降低并发API 端口无法访问防火墙或绑定地址错误检查 127.0.0.1:8000 是否通绑定 0.0.0.0检查防火墙规则10.1 定位问题优先级遇到问题不要瞎猜按这个顺序排查先看技能文件是否加载打印完整 prompt。再看 API 是否正常用简单 prompt 直接调一次。再看是否超时检查 timeout 设置。最后看模型输出把返回结果存日志分析质量。这样一步步缩小范围大部分问题都能快速定位。11. 最佳实践与使用建议11.1 技能库工程化建议先小后大。先在 3-5 个技能上跑通再扩展。版本管理。技能文件进 Git记录每次修改。命名规范。技能名用短横线连接如paper-outline、pdf-summary。测试先行。每个技能配一个最小输入验证输出稳定后再用。输出目录规范。按日期/任务分类避免文件混乱。11.2 Prompt 设计建议一份好的 Agent.md应该满足三个要求可执行模型读了就知道第一步干什么。可验证输出结果有明确的格式标准能程序化检查。可复用不绑定具体输入能适用于一类任务。11.3 合规与安全边界这部分必须提醒。Agent Skills 的应用场景越广越要守住边界版权合规处理的文档、素材必须有合法来源生成的内容不能抄袭、不能侵犯他人版权。隐私保护不要把个人敏感信息、未公开的数据投喂给公开 API 模型。企业环境建议用本地部署或私有化 API。内容安全对模型输出要做内容过滤尤其是面向外部用户的服务。责任边界模型生成的内容需要人工复核尤其是技术文章、论文、报告等专业内容不能直接发布。接口安全暴露 API 服务时必须加鉴权避免被恶意刷量。11.4 后续扩展方向如果 Agent Skills 这套方法你已经跑通可以考虑几个进阶方向多 Agent 协作不同技能分配给不同 Agent协作完成复杂任务。工具调用集成技能里定义可调用的函数让模型自己选择工具。向量检索升级把关键词检索替换成向量数据库提升召回质量。流程可视化把技能编排做成可视化界面非技术用户也能配置。记忆持久化Agent 的执行结果写回知识库形成持续学习回路。12. 总结与下一步Agent Skills 和 LLM Wiki 这套方法最值得尝试的点在于它用最朴素的文件系统解决了一个很实际的问题——如何让 LLM 稳定、可复用、可组合地完成真实任务。不需要复杂的框架不需要昂贵的基础设施一个文件夹加一段 Python 脚本就能搭建出属于自己的 Agent 技能库。建议你最先验证的功能是写一个最简单的 Agent.md设计一个你每天都在做的重复性任务比如周报生成、文档摘要、邮件草拟然后用 Python 跑一遍。如果按照这套流程能跑通再逐步加技能、加批量、加 API。最容易踩的坑有两个。第一个是技能文件写得太复杂塞了太多内容模型反而不知道该听谁的第二个是一开始就追求大而全装了十几个技能结果没有一个好用。正确做法是一个技能一个任务做到极致。后续可以继续扩展的方向包括多 Agent 协作的复杂任务编排、基于向量检索的本地知识库、接入更多第三方工具 API、把技能库分享给团队共同维护。这五个方向哪一个都够再写好几篇深度文章建议先收藏这篇等基础流程跑通后再逐步进阶。