1. “skills”不是功能模块，而是一套AI时代的新工作流范式

最近三个月，我在三个不同行业的客户项目里，都撞见了同一个词反复出现在技术方案文档、内部会议纪要甚至实习生的周报里——不是“API”，不是“Agent”，而是skills。它不带引号时是泛指能力，加了引号就成了一个具体的技术实体：skills。更奇怪的是，没人先定义它，大家直接就用起来了。有人把它当文件夹名，有人写进CI脚本里，有人在GitHub issue里说“这个skills没生效”，还有人凌晨两点发消息问：“你那个skills.sh跑通了吗？我卡在base_url配置上”。

这根本不是传统意义上的“技能列表”或“能力图谱”。它是一套正在快速成型的、围绕大模型调用而重构的工程实践体系。核心逻辑非常朴素：把每一次对AI模型的调用，封装成可复用、可测试、可组合、可监控的最小执行单元。就像当年Linux把一切抽象为“文件”，现代AI工程正把一切抽象为“skills”。你看到的SKILL.md，本质是这个单元的说明书；skills.sh不是启动脚本，而是本地skills注册中心的轻量级调度器；而api error: 400 配置错误: claude provider 缺少 base_url 配置，恰恰暴露了skills运行时依赖的底层契约——它必须明确知道自己要对接哪个服务端点，而不是靠环境变量或全局配置去猜。

这套范式之所以爆发，是因为它精准切中了当前AI落地的三大痛点：一是模型调用散落在各处，调试成本高；二是同一类任务（比如“从PDF提取表格”）在不同项目里重复造轮子；三是第三方API成本不可控，缺乏统一计量入口。skills就是把“调用Claude解析合同”、“用Codex生成数学建模代码”、“调用TTS合成漫剧台词”这些动作，从零散的代码片段，升维成像npm包一样可安装、可版本化、可依赖管理的工程资产。它不解决模型本身的问题，但解决了“怎么让模型能力真正变成团队可用的生产力”的问题。所以当你看到“华为杯建模比赛好用的codex skills”或者“ai漫剧常用skills”，本质上是在说：我们找到了一套经过实战验证的、针对特定场景的AI调用最佳实践集合。

提示：不要把skills理解为某种新框架或SDK。它更像一种约定俗成的目录结构+接口协议+元数据规范。一个skills，通常就是一个包含skill.py（或index.js）、SKILL.md、config.json的文件夹。它的价值不在代码多炫酷，而在其描述是否清晰、输入输出是否明确、错误边界是否定义完整。这也是为什么superpower skills能火——它把“让AI做PPT”这种模糊需求，拆解成了generate_presentation_from_outline、refine_slide_content、export_to_pdf三个原子skills，每个都可单独测试和替换。

2.skills.sh：本地skills生态的“启动器”与“调试探针”

skills.sh这个名字听起来像一个简单的shell脚本，但实际使用中，它承担着远超其名的功能。我见过最精简的版本只有12行，却支撑起了整个团队的AI开发流程；也见过最复杂的版本集成了HTTP代理、成本统计、缓存策略和失败重试。它的核心定位很明确：在本地开发环境中，为skills提供一个轻量、透明、可调试的执行沙盒。它不替代生产环境的API网关，但却是连接开发者大脑与AI模型的第一道桥梁。

这个脚本的典型工作流是这样的：当你在终端输入./skills.sh run extract_tables --input report.pdf --output tables.csv，skills.sh会做四件事。第一，解析命令行参数，确认你要调用的是extract_tables这个skills；第二，加载该skills目录下的config.json，从中读取provider: "claude"和model: "claude-3-haiku-20240307"；第三，检查环境变量CLAUDE_API_KEY是否存在，若不存在则抛出明确错误而非让下游API返回晦涩的401；第四，构造符合Claude API要求的请求体（包括system提示词、messages数组），并设置Content-Type: application/json，然后发起curl调用。整个过程没有魔法，全是明文可见的步骤。

关键在于它的调试价值。比如那个高频报错api error: 400 this model's maximum context length is 10485，如果直接调用Claude SDK，你可能得翻半天文档才能定位是token超限。但用skills.sh，你可以在脚本里加一行echo "Estimated tokens: $(wc -w <<< "$prompt")"，立刻看到输入文本的单词数，再乘以1.3粗略估算token，就能判断是不是prompt太长。更进一步，skills.sh可以内置一个--dry-run模式，它不真正发请求，而是把最终构造的JSON payload打印出来，让你肉眼检查messages数组里有没有意外嵌套的空对象，或者system字段是不是被错误地放到了messages里——这正是api error: 400 配置错误: claude provider 缺少 base_url 配置的常见根因：base_url本该在skills的config.json里，却被误写进了全局.env，而skills.sh又没做校验。

我自己的skills.sh版本还加了一个小功能：在每次成功调用后，自动记录一条日志到skills.log，格式为[2024-06-15 14:22:31] extract_tables SUCCESS 124ms $0.0032。这个看似简单的日志，配合grep "extract_tables" skills.log | awk '{sum += $4} END {print sum}'，就能快速算出本周这个skills的总耗时和预估成本。这才是skills.sh真正的威力——它把抽象的AI调用，变成了可度量、可审计、可优化的具体操作。

注意：skills.sh不是必须的。你可以用Python的subprocess、Node.js的child_process甚至Postman来调用skills。但它存在的意义，是把“如何调用”这个重复性劳动，从每个开发者的心智负担里剥离出来，变成一个团队共享的、版本可控的基础设施。就像当年npm start之于前端开发，skills.sh正在成为AI工程师的start命令。

3.SKILL.md：skills的“产品说明书”，而非技术文档

SKILL.md这个文件名，在所有skills仓库里出现的频率，几乎和README.md一样高。但它的作用，和README.md有本质区别。README.md是给开发者看的，讲怎么安装、怎么构建、怎么贡献；而SKILL.md是给使用者看的，讲这个skills能做什么、不能做什么、输入什么、输出什么、有什么限制、怎么才算用对了。它不是技术文档，而是一份面向业务方的产品说明书。

一份合格的SKILL.md，必须回答五个问题，缺一不可。第一，“它解决什么问题？”——不能写“调用Claude API”，而要写“将非结构化PDF报告中的财务数据，自动提取为标准CSV格式，支持合并多个PDF的相同表格”。第二，“输入是什么？”——要精确到类型和约束，比如--input参数必须是本地路径，且文件大小不超过10MB，格式仅支持.pdf和.docx。第三，“输出是什么？”——要给出真实样例，比如tables/2024_Q1_revenue.csv的内容前五行，并注明列名含义。第四，“常见失败场景及对策”——这是最有价值的部分。比如“当PDF是扫描件图片时，本skills会返回空结果，此时请先用OCR工具预处理”，或者“若遇到context length exceeded错误，请尝试用--chunk-size 500参数分段处理”。第五，“性能与成本”——明确告知“处理1页A4 PDF平均耗时1.2秒，单次调用预估费用$0.0018”。

我见过最糟糕的SKILL.md，是把Claude官方API文档里的参数列表复制粘贴过来，再加个curl示例。这种文档对使用者毫无帮助。而最好的SKILL.md，是像一个老手在手把手教你。比如某个用于数学建模的codex_nature_skills，它的SKILL.md里有一节叫“为什么不用GPT-4？”——它坦率承认：“GPT-4在符号计算上更稳定，但本skills专为Nature期刊风格的LaTeX公式生成优化，对amsmath环境的支持更精准，且成本低40%。”这种直面取舍的说明，比任何技术参数都更有说服力。

SKILL.md的另一个隐形价值，是它天然成为了skills的“测试用例来源”。很多团队会用markdown-it库解析SKILL.md，自动提取其中的“输入样例”和“预期输出”，生成自动化测试的fixture。这样，当SKILL.md更新时，测试用例也随之更新，保证了文档和代码的一致性。这正是typesafe ai skills github项目强调的“类型安全”——不是指TypeScript的类型系统，而是指SKILL.md里定义的契约，必须被代码严格遵守。

提示：SKILL.md的标题层级应该遵循“使用者视角”。H2标题应该是“输入参数”、“输出格式”、“错误处理”，而不是“实现细节”、“依赖库”。如果你发现自己在SKILL.md里写了import anthropic，那说明你写错了地方，这部分应该放在skill.py的注释里。

4.skills开发的核心陷阱：过度设计与契约失焦

开始写第一个skills时，我犯过一个典型的“工程师病”：想把它做成一个完美的、可插拔的、支持所有模型的通用框架。我花了三天时间设计了一套SkillBase抽象类，定义了execute()、validate_input()、format_output()等方法，还搞了个ProviderRegistry来动态加载Claude、OpenAI、Ollama的适配器。结果呢？第一个真实的skills——一个从邮件里提取会议时间的简单脚本——光是继承这个基类就写了20行样板代码，而核心逻辑只有5行。更糟的是，当同事想快速改个提示词时，他得先理解整个继承链，最后干脆绕过我的框架，直接写了个裸curl脚本。

这就是skills开发最大的陷阱：把“可扩展性”当成了首要目标，而忽略了“可理解性”和“可交付性”。skills的本质，是解决一个具体的、狭窄的、定义清晰的问题。它的价值，不在于它有多优雅，而在于它能不能被一个非AI背景的业务人员，在5分钟内学会使用，并在10分钟内得到正确结果。因此，skills开发的黄金法则是：先让它work，再让它right，最后才考虑让它beautiful。

具体来说，这意味着三个必须坚守的底线。第一，拒绝抽象层。除非你真的需要同时支持Claude和Ollama，否则不要写Provider抽象。直接在config.json里写死"provider": "claude"，在skill.py里硬编码anthropic.Anthropic(api_key=...)。省下的时间，用来把SKILL.md写得更详细，比任何架构设计都重要。第二，输入输出必须极简。一个skills只接受一个--input和一个--output参数，再多的配置，都放到config.json里。不要学CLI工具搞一堆--verbose、--dry-run、--force，这些只会增加使用者的认知负荷。第三，错误信息必须业务化。不要返回ConnectionError: HTTPConnectionPool(host='api.anthropic.com', port=443): Max retries exceeded...，而要返回ERROR: Claude服务暂时不可用，请10分钟后重试（错误码：SERVICE_UNAVAILABLE）。前者是给运维看的，后者是给使用者看的。

我后来总结出一个“skills健康度检查表”，每次提交前必过一遍：①SKILL.md能否让一个实习生在不看代码的情况下，独立完成一次调用？②skills.sh run <name>的输出，是否一眼就能看出成功还是失败？③config.json里的所有字段，是否都在SKILL.md里有对应解释？④ 整个skills目录下，除了skill.py、SKILL.md、config.json，是否还有其他文件？如果有，它们是否真的必要？这个检查表帮我砍掉了70%的“看起来很酷但毫无必要的代码”。

注意：skills不是微服务，不需要独立部署。它就是一个本地可执行的单元。那些试图给skills加REST API、加数据库、加用户认证的方案，都是在用解决分布式系统问题的思路，来解决一个本地脚本问题。记住，skills的终极形态，应该是一个可以被git clone下来，chmod +x skills.sh，然后立刻投入生产的最小可行单元。

5. 从零搭建一个数学建模skills：以“自动求解线性规划”为例

现在，让我们动手做一个真实的skills，主题是“自动求解线性规划问题”，这是数学建模比赛中高频需求。目标很明确：给定一个用自然语言描述的LP问题（比如“某工厂生产A、B两种产品，A每件利润10元，B每件利润15元…”），skills能自动生成标准的scipy.optimize.linprog调用代码，并返回最优解和目标函数值。整个过程，我们将严格遵循前面提到的所有原则，不引入任何不必要的抽象。

第一步，创建目录结构。在你的项目根目录下，新建文件夹skills/lp_solver。里面初始化三个文件：skill.py、SKILL.md、config.json。config.json内容极简：

{ "provider": "claude", "model": "claude-3-sonnet-20240229", "max_tokens": 1024, "temperature": 0.1 }

这里max_tokens设为1024，是因为我们只需要生成一段Python代码，不需要长上下文；temperature设为0.1，是为了保证生成代码的确定性，避免随机性导致结果不一致。

第二步，编写skill.py。核心逻辑只有三段：读取输入、构造prompt、解析输出。输入是一个文本文件，内容就是题目描述。我们用sys.argv[1]获取文件路径，用open().read()读取内容。Prompt的设计是关键，它必须引导Claude输出纯Python代码，且格式固定：

你是一个专业的数学建模助手。请根据以下线性规划问题描述，生成一段可直接运行的Python代码，使用scipy.optimize.linprog求解。 要求： 1. 代码必须以`# SOLUTION START`开头，以`# SOLUTION END`结尾。 2. 代码中必须包含`c`, `A_ub`, `b_ub`, `bounds`四个变量的定义。 3. 最后一行必须是`print(f"Optimal value: {res.fun:.4f}")`和`print(f"Optimal solution: {res.x.tolist()}")`。 4. 不要包含任何解释性文字，只输出代码。 问题描述： {input_text}

注意，我们没有用system角色，而是把所有指令都放在user消息里，因为Claude的system字段在某些版本里行为不稳定。解析输出时，我们用正则r'# SOLUTION START\n(.*?)\n# SOLUTION END'提取代码块，然后用exec()执行。为了安全，我们限制了exec()的globals字典，只允许scipy.optimize和numpy。

第三步，撰写SKILL.md。这里我们重点写“常见失败场景”。比如，当题目描述里出现“非线性约束”时，Claude可能会强行生成代码，但linprog会报错。我们的对策是：在skill.py里捕获ValueError，并返回ERROR: 检测到非线性约束，请检查题目描述是否为标准线性规划问题。另一个场景是“变量无界”，这时res.success为False，我们返回ERROR: 问题无界，请检查约束条件是否完备。这些都不是技术故障，而是业务逻辑的边界，必须在SKILL.md里明确告知使用者。

最后，测试。准备一个测试题test_input.txt，内容是经典的“生产计划问题”。运行./skills.sh run lp_solver --input test_input.txt --output result.txt。第一次运行，可能得到ERROR: 检测到非线性约束，因为prompt里没强调“仅处理线性问题”。这时，我们不是去改代码，而是回到SKILL.md，在“输入要求”里加一句：“题目描述必须明确为线性规划问题，不得包含二次项、绝对值、分式等非线性元素。”——这正是skills开发的精髓：用文档的精确性，来弥补模型能力的不确定性。

提示：这个lp_solverskills，上线后被我们团队在华为杯赛前培训中使用。一位队员反馈：“以前要花20分钟手写linprog参数，现在只要把题目复制进txt，3秒就出结果。更重要的是，SKILL.md里写的那些错误提示，让我第一次真正理解了什么是‘可行域无界’。” 这就是skills的价值——它把AI的能力，转化成了人类可理解、可信赖、可教学的知识载体。