1. 为什么我要自己写一套本地 AI Skill 工具集
1.1 从「只会聊天」到「真的动手」
我平时用 AI 处理文档、整理素材、批量转格式，最烦的就是每次都要手动复制粘贴路径、手动跑脚本。AI 明明能听懂「把桌面上的 md 文件都转成网页」这种话，但它就是碰不到我的硬盘。这个断层，就是 Skill 机制要解决的问题。
所谓 Skill，你可以把它理解成给 AI 装的一本「操作手册 + 工具箱」。手册是SKILL.md，里面写清楚这个技能能干什么、什么话该触发哪个工具、哪些目录绝对不能碰；工具箱是一堆.py脚本，真正去读写文件、遍历目录、移动文件的是它们。AI 负责听懂人话、匹配技能、把参数传对，Python 负责落地执行。
这套东西适合谁？适合经常和本地文件打交道的人：写博客的要批量转 Markdown、做素材的要按类型归档下载文件夹、做项目的要快速看目录结构。你不需要会训练模型，只要会写 Python 函数、会写 Markdown 文档，就能搭起来。
1.2 整套闭环长什么样
一句话概括运行链路：
用户自然语言指令 → 意图识别匹配 SKILL.md 路由表 → 安全策略校验 → 调用对应 Python 脚本执行本地操作 → 脚本结果回传给 AI 整理成可读反馈
这里面有两个关键设计。第一是路由表，它把「整理桌面」这种模糊说法映射到具体的organize_by_type.py。第二是安全闸门，AI 操作本机文件最怕误删误移，所以SKILL.md里必须写死高危路径拦截和二次确认规则。
1.3 本次要搭的文件系统 Skill 能力清单
我这次搭的这套，包含三个高频刚需工具：
- Markdown 批量转 HTML 静态页面
- 一键输出文件夹树形结构图
- 按文件后缀自动分类整理杂乱文件夹
配套约束是：所有操作走绝对路径校验，系统关键目录直接拒绝，批量移动前必须回显操作数量。下面从工程结构开始，一步步给你可复制的代码。
2. TaoToken 前置准备：统一 Key 与 API 通道
2.1 为什么 Skill 需要一个统一的模型通道
Skill 本身是本地文件，但「听懂自然语言」这一步得靠模型。你可以在本地 Agent 客户端里配置模型，也可以让脚本自己调 API。我选择用 TaoToken 作为统一通道，原因是它把 Key 和 Base URL 统一了，换模型不用改一堆配置，脚本里只认一个地址就行。
TaoToken 的定位是模型 API 聚合通道，官网在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 入口是 https://taotoken.net/api 。注意 API 地址不带 UTM 参数，配置的时候别把推广参数拼进去。
2.2 拿到 Key 并确认三件套
接入任何模型通道，你手里必须凑齐三件套：Base URL、API Key、Model ID。少一个都跑不通。
操作路径是这样：先打开 https://taotoken.net/api-keys ，在控制台里创建一个新的 API Key，复制出来存好。然后去 https://taotoken.net/doc 看当前支持的模型列表，挑一个你常用的 Model ID，比如做代码和工具调用比较稳的型号。
注意：Key 只显示一次，创建后立刻复制。不要把它硬编码进要提交到 Git 的脚本里，用环境变量或者本地
.env文件。
2.3 在客户端里配置模型通道
如果你用的是支持自定义模型的 Agent 客户端，配置项一般就三个字段：
| 配置项 | 填写内容 |
|---|---|
| Base URL | https://taotoken.net/api |
| API Key | 你在控制台创建的 Key |
| Model ID | 从文档里选的模型标识 |
配好之后，客户端就能通过这个通道调用模型。Skill 的加载和模型通道是两件事：Skill 决定「能做什么」，模型通道决定「谁来理解指令」。两者都配好，闭环才成立。
3. 可复制配置：SKILL.md 模板与 Python 技能骨架
3.1 标准 Skill 包目录结构
先把工程目录定下来，后面所有文件都往这个结构里放：
file_system_skill/ ├─ SKILL.md # 技能总配置文件（核心） ├─ conversionFormats.md # 格式转换补充参考文档 ├─ convert_md2html.py # MD 转 HTML 工具脚本 ├─ dir_tree.py # 目录树生成脚本 └─ organize_by_type.py # 文件自动分类脚本3.2 SKILL.md 完整模板
SKILL.md是 AI 的行为约束手册，路由表和安全规则都写在这里。下面这份可以直接复制改：
# FileSystem Skill 本地文件系统操作技能 ## 1、技能总述 本技能为 AI 提供本机文件系统安全可控的运维能力，包含文件格式转换、 目录结构查看、文件自动规整三大核心工具，所有文件操作携带安全校验机制。 ## 2、四大核心组成 1. 意图决策对照表：将用户自然语言意图路由分发至对应工具脚本 2. 4 个核心功能模块：格式转换、目录可视化、文件整理、公共安全校验 3. 运行准则：安全优先、高危操作强制二次确认、禁止访问系统关键目录 4. 标准调用工作流示例 ## 3、意图路由匹配表 | 用户自然语言指令示例 | 路由目标脚本 | | ---- | ---- | | 将 xxx 文件夹下 md 文件转换成网页、md 转 html | convert_md2html.py | | 查看这个文件夹目录结构、打印树形目录、生成目录树 | dir_tree.py | | 整理桌面文件、按文件类型归类下载文件夹、自动分类文件 | organize_by_type.py | ## 4、运行安全硬性规则（安全闸门） 1. 禁止遍历/修改：C:\Windows、C:\Program Files、/etc、/usr 等系统核心目录 2. 文件删除、批量移动文件必须向用户弹窗确认，得到确认指令后方可执行 3. 所有文件操作必须使用绝对路径校验，拒绝模糊危险路径 4. 执行结果必须回显：操作文件数量、存放路径、执行是否成功 ## 5、标准工作流 Step1：解析用户指令，提取目标文件夹路径、执行参数 Step2：依据路由表匹配对应的 Python 工具 Step3：SKILL 内置安全规则校验路径合法性 Step4：高危行为发起确认询问 Step5：调用本地 py 脚本执行真实文件操作 Step6：捕获脚本运行输出/报错，整理成自然语言回复用户3.3 Python 技能函数骨架
三个脚本我都给你完整可运行的版本。先看 Markdown 转 HTML：
import markdown import os def batch_md_to_html(source_dir: str, out_dir: str = "./html_output"): """批量将目录内 md 文件转为静态 HTML 文件""" if not os.path.exists(out_dir): os.makedirs(out_dir) html_template = """<!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8"> <title>{title}</title> <style>body{{padding: 2rem;max-width: 900px;margin: 0 auto;}}</style> </head> <body>{content}</body> </html> """ file_count = 0 for filename in os.listdir(source_dir): if filename.lower().endswith(".md"): md_path = os.path.join(source_dir, filename) with open(md_path, "r", encoding="utf-8") as f: md_content = f.read() html_body = markdown.markdown( md_content, extensions=["tables", "fenced_code"] ) html_full = html_template.format(title=filename, content=html_body) save_name = filename.replace(".md", ".html") save_path = os.path.join(out_dir, save_name) with open(save_path, "w", encoding="utf-8") as f: f.write(html_full) file_count += 1 return f"转换完成，共处理 {file_count} 个 Markdown 文件，输出路径：{os.path.abspath(out_dir)}" if __name__ == "__main__": res = batch_md_to_html("./test_md") print(res)再看目录树生成脚本，注意它带了最大深度限制，防止层级过深卡死：
import os def generate_dir_tree(root_path: str, max_depth: int = 8) -> str: """生成目录树文本结构""" tree_lines = [os.path.basename(os.path.abspath(root_path)) + "/"] def walk(path, depth): if depth > max_depth: return items = sorted(os.listdir(path)) for idx, item in enumerate(items): item_full = os.path.join(path, item) prefix = "│ " * depth symbol = "└── " if idx == len(items) - 1 else "├── " tree_lines.append(f"{prefix}{symbol}{item}") if os.path.isdir(item_full): walk(item_full, depth + 1) walk(root_path, depth=1) return "\n".join(tree_lines) if __name__ == "__main__": tree_text = generate_dir_tree("./") print(tree_text)最后是文件自动分类脚本，内置了系统目录拦截：
import os import shutil FILE_TYPE_MAP = { "图片": [".jpg", ".png", ".gif", ".jpeg", ".bmp", ".webp"], "文档": [".pdf", ".doc", ".docx", ".xls", ".xlsx", ".md", ".txt"], "压缩包": [".zip", ".rar", ".7z", ".tar", ".gz"], "程序": [".exe", ".py", ".bat", ".ps1"], "视频": [".mp4", ".mov", ".avi", ".mkv"], "音频": [".mp3", ".wav", ".flac"] } def organize_folder(target_folder: str): """按文件后缀自动归类文件夹内所有文件，文件夹不会被移动""" block_paths = ["C:/Windows", "C:/Program Files", "/etc", "/usr"] for block in block_paths: if target_folder.startswith(block): return "错误：禁止操作系统保护目录" total_move = 0 for file in os.listdir(target_folder): file_full_path = os.path.join(target_folder, file) if os.path.isdir(file_full_path): continue file_suffix = os.path.splitext(file)[1].lower() match_folder = "其他文件" for cat_name, suffix_list in FILE_TYPE_MAP.items(): if file_suffix in suffix_list: match_folder = cat_name break cat_path = os.path.join(target_folder, match_folder) if not os.path.exists(cat_path): os.makedirs(cat_path) shutil.move(file_full_path, os.path.join(cat_path, file)) total_move += 1 return f"文件整理完成，一共归类移动 {total_move} 个文件" if __name__ == "__main__": result = organize_folder(r"C:\Users\你的用户名\Desktop") print(result)3.4 补充参考文档 conversionFormats.md
# 文件转换支持格式对照表 1. Markdown 支持语法：表格、代码块、标题、列表、加粗斜体 2. 输出 HTML 为纯静态文件，无需任何前端服务即可打开 3. 归类脚本识别的全部后缀参考 FILE_TYPE_MAP 配置 4. 若需要新增文件类型，直接修改 organize_by_type.py 内的 FILE_TYPE_MAP 字典即可4. 验证请求：自然语言到文件操作的完整链路
4.1 先单独跑通每个脚本
在接入 AI 之前，先确认脚本本身没问题。进入file_system_skill目录，准备一个测试文件夹test_md，里面放几个.md文件，然后执行：
python convert_md2html.py预期输出类似：
转换完成，共处理 3 个 Markdown 文件，输出路径：/Users/you/file_system_skill/html_output再跑目录树：
python dir_tree.py你会看到当前目录的树形结构打印出来。最后跑分类脚本，把organize_folder里的路径改成你的测试目录，执行后检查文件是否按类型进了子文件夹。
4.2 用模型通道验证意图解析
脚本没问题后，验证模型能不能正确理解指令。你可以用模型对话入口 https://taotoken.net/chat 直接测试，把SKILL.md的路由表内容贴进去，然后输入：
帮我整理一下下载文件夹，按文件类型归类观察模型是否把意图匹配到organize_by_type.py，并提取出目标路径参数。如果模型返回的是「我无法访问你的文件系统」，说明它没读到 Skill 定义，需要检查 Skill 是否被正确加载进上下文。
4.3 完整闭环验证动作
把 Skill 包导入你的本地 Agent 客户端后，下发一条真实指令：
把 test_md 文件夹里的 md 文件全部转成 html 网页预期链路是：模型解析出意图「格式转换」→ 匹配路由表到convert_md2html.py→ 提取路径参数test_md→ 安全校验通过 → 调用脚本 → 脚本返回处理数量 → 模型整理成自然语言回复你。如果每一步都能对上，闭环就通了。
4.4 用 Coding Plan 做长期 Agent 调试
如果你打算把这套 Skill 长期跑在编码或自动化场景里，可以看下 Coding Plan 入口 https://taotoken.net/coding-plan 。它更适合需要持续调用、反复调试 Agent 的场景，比单次对话验证更省心。调试阶段我建议先用模型对话快速验证意图，稳定后再切到长期方案。
5. 本篇常见错排查：401、路径拦截与脚本报错
5.1 报错 401 Unauthorized
这是最常见的接入错误，说明 Key 没配对。排查顺序：
第一，确认Base URL填的是https://taotoken.net/api，不要多写斜杠或拼上推广参数。第二，确认 API Key 是从 https://taotoken.net/api-keys 复制出来的完整字符串，没有首尾空格。第三，确认 Model ID 在文档列表里存在，写错模型名有时也会返回鉴权类错误。
如果你在客户端里看到local proxy failed之类的提示，通常是本地代理配置和通道地址冲突，把客户端里的自定义代理关掉，直连通道地址再试。
5.2 报错 reading choices 或返回结构解析失败
这个错误一般出现在脚本自己调 API 的场景。原因是不同模型的返回 JSON 结构不完全一样，你按choices[0].message.content取值时，如果模型返回的是流式分块或者工具调用格式，就会取不到。
解决办法是在解析前先打印原始返回：
import json resp = json.loads(raw_response) print(json.dumps(resp, ensure_ascii=False, indent=2))看清楚结构再取值。如果是工具调用场景，内容可能在tool_calls字段里，而不是content。
5.3 脚本报「禁止操作系统保护目录」
这是安全闸门生效了，不是 bug。检查你传入的target_folder是不是以C:/Windows、/etc这类路径开头。注意 Windows 路径分隔符，脚本里用的是正斜杠匹配，如果你传的是反斜杠路径，可能绕过拦截，建议统一转成正斜杠再判断。
5.4 OAuth 相关报错
如果你在客户端里用的是 OAuth 登录方式而不是 API Key，可能会遇到 token 过期或 scope 不足的报错。这种场景下建议改用 API Key 方式接入，配置更直接，三件套填对就能跑。OAuth 的刷新逻辑各家客户端不一样，排查成本高。
5.5 脚本能跑但 AI 不调用
这种情况通常是SKILL.md的路由表描述太模糊。比如你只写了「文件整理」，用户说「把桌面弄干净点」，模型可能匹配不上。解决办法是在路由表的「用户自然语言指令示例」列里多写几种口语化说法，覆盖同义表达。路由表写得越具体，匹配越稳。
6. 把 Skill 用起来：从验证到长期落地
6.1 先跑通一条链路再扩展
不要一上来就写十个工具。先把「自然语言 → 技能匹配 → 文件操作 → 结果回传」这一条链路跑通，确认模型能正确路由、脚本能正确执行、结果能正确回显。这条链路通了，后面加工具就是复制模板改函数的事。
6.2 安全规则要写在最前面
我踩过的坑是：早期版本没加路径拦截，测试时差点让脚本遍历到系统目录。后来把安全规则写进SKILL.md的硬性规则里，同时在每个 Python 脚本里也加一层路径校验。双保险，AI 层拦一次，脚本层再拦一次。
6.3 日志和异常捕获别省
给每个脚本加 try/except，把报错信息返回给模型而不是直接崩溃。再在SKILL.md里加一条规则：所有文件操作写入本地日志。这样出问题能回溯，知道是哪条指令触发了哪个操作。
6.4 扩展方向
这套模板可以直接复用到其他场景：图片批量压缩、Git 仓库状态检查、系统资源监控。改的是 Python 函数和路由表，SKILL.md的结构不用动。等你把文件系统这套跑顺了，再仿写其他 Skill 会快很多。
需要长期跑 Agent 的话，Coding Plan 入口在 https://taotoken.net/coding-plan ，接入文档在 https://taotoken.net/doc ，Key 管理在 https://taotoken.net/api-keys 。先把文件系统 Skill 跑通，再按需扩展。
