把提示词升级成"技能包"：Agent Skills 原理、SKILL.md 写法与 yao-meta-skill 技能工程全拆解

本文由 莫潇羽@源码七号站（www.fuyuan7.com）撰写，转载请注明出处。

快速摘要

如果你还在靠一长串提示词反复"调教"AI，这篇想先告诉你一个结论：那套玩法正在被淘汰。 现在更高效的方式，是把一段反复用的工作流、一堆复用的提示词、一份操作清单，沉淀成一个能被 AI 自动识别、自动加载、跨工具复用的"技能包"——也就是 2025 年下半年开始流行的 Agent Skills。它的物理形态很简单：一个文件夹，里面放一个 SKILL.md，再加上可选的脚本和参考资料。它最聪明的机制叫"渐进式披露"，平时只占几百个 token，真要干活时才加载完整指令，既省钱又稳定。本文会从"它到底是什么"一路讲到"怎么把一个技能做成团队能长期复用的资产"，并以开源项目 yao-meta-skill 为例，拆解技能工程里的路由、评估、治理和跨平台打包这几块硬骨头。

想看完整拆解，往下翻。

一、先说结论：我们正在从"写提示词"切换到"造技能"

我自己折腾大模型这三年，最直观的感受是：人和模型打交道的方式，每隔一段时间就要被推翻重来一次。

最早那一阵，大家拼的是谁的提示词写得长、写得巧。一个 prompt 里塞满了角色设定、约束条件、输出格式、反例正例，恨不得把所有可能性都堵死。那会儿"提示词工程师"还是个挺唬人的称呼。问题也很明显：每开一个新对话，你都得把这套话术重新喂一遍，模型记不住，你也累。

后来进入第二个阶段，光靠文本不够用了。模型得能查知识库、能调外部接口、能跑代码，于是有了函数调用（Function Call）、检索增强（RAG），再到后来的 MCP 协议。AI 从"只会说"变成了"能动手"。

现在轮到第三个阶段，我把它叫做技能工程。核心变化是：AI 不再需要你每次手把手教，而是能根据当前任务，自动从一堆"技能包"里挑出对的那个加载进来。你写一次，它复用很多次；你这个团队写好的技能，别的同事甚至别的工具也能直接拿去用。

这个转变带来的不只是省事。它意味着，过去那些只存在于某个老员工脑子里、或者散落在聊天记录里的"隐性知识"，第一次有了一个标准化的容器可以装起来、传下去。莫潇羽@源码七号站 一直觉得，谁能把团队里那些说不清道不明的经验，封装成机器能直接执行的技能，谁就握住了这一轮 AI 落地的关键。

下面就从最基础的概念开始，把这件事一层层讲透。

二、Agent Skills 到底是什么：给 AI 的一本"岗位手册"

先用一句大白话定义：一个 Skill，就是一个教 AI"在什么场景下、按你的方式、把某件事做对"的文件夹。

这个说法不是我编的。Agent Skills 最早是 Anthropic（Claude 背后的公司）的东西——2025 年 10 月，它先作为 Claude Code 的一个特性亮相；真正的转折点在 2025 年 12 月 18 日，Anthropic 把这套规范和配套 SDK 公开发布到 agentskills.io，明确开放给任何 AI 平台采用。要厘清一点：规范本身是 Anthropic 起草、开源出来的，并不是几家厂商坐下来一起写的；但它确实迅速长成了一个行业级的通用标准。

为什么说"通用"？看落地速度就知道了。开放标准发布后短短 48 小时内，微软就把它接进了 VS Code 与 Copilot，OpenAI 也给 ChatGPT 和 Codex CLI 加上了支持（OpenAI 甚至在官宣前几天就已经在 Codex 里悄悄实现了同构的结构）。到 2026 年初，支持同一份 SKILL.md、同一套目录结构的工具据报道已达三十多款，覆盖 Google 的 Gemini CLI、Cursor、JetBrains 的 Junie、AWS 的 Kiro、Block 的 Goose、字节的 TRAE 等一大批来自不同厂商的产品。这意味着，你写的技能不再绑死在某一家身上——这正是"开放标准"四个字的分量。

治理这条线也在往"多方共管"走。2025 年 12 月，Linux 基金会牵头成立了 Agentic AI Foundation（AAIF），Anthropic、OpenAI、Block 是创始成员，Google、微软、AWS 等也陆续加入，此前的 MCP 协议已经托管在里面。换句话说，这类标准正从"某一家发起"，逐步过渡到"中立机构下、多方共同维护"。这条成长路线，和当年的 MCP 几乎一模一样：先由一家拿出来开源，再被全行业一起采纳、共同治理。

打个比方可能更好懂。你招了个智商极高的实习生，脑子转得飞快，但对你们公司的业务一窍不通。传统做法是每次派活都口头交代一遍流程；而 Skill 相当于直接塞给他一本岗位手册（SOP）——里面写清楚了这个岗位要做什么、按什么步骤做、有哪些坑要避开。他不用每次从零学起，碰到对应的活，翻手册照着做就行。

一个最小的技能长什么样

物理形态上，一个 Skill 就是一个文件夹，里面必须有一个 SKILL.md，其它都是可选的。最小结构大概长这样：

my-skill/
├── SKILL.md          # 必需：技能定义（YAML 头 + Markdown 正文）
├── scripts/          # 可选：确定性脚本（Python / Bash）
├── references/       # 可选：参考资料，按需加载
└── assets/           # 可选：模板、字体、图标等输出用资源

而 SKILL.md 本身，开头是一段 YAML 格式的元信息（业内习惯叫 frontmatter，也就是"文件头"），后面才是 Markdown 正文。一个最朴素的例子：

---
name: report-generator
description: 当用户要求"按公司标准格式生成报告"时使用，
  负责套用统一模板、补齐固定章节、调用数据分析脚本。
---

# 报告生成流程

1. 套用封面模板（见 templates/cover.md）
2. 跑数据分析脚本（见 scripts/analyze.py）
3. 按固定章节顺序拼装正文

这里有两个字段是命脉：name 是技能的名字，习惯用小写加连字符（kebab-case）；description 是触发说明，AI 就是靠它来判断"这个活归不归我管"。description 写得好不好，几乎决定了这个技能能不能被正确唤醒——这一点后面第七章会专门展开。

渐进式披露：为什么它比塞满提示词更省

Skill 设计里我最欣赏的一点，叫渐进式披露（Progressive Disclosure）。说人话就是：用多少、拿多少，绝不一次性全塞进来。

它把信息分成三层，按需逐级加载，过程很像我们去图书馆查资料——先看目录，再翻对应章节，最后才查附录：

这个机制解决的是一个很现实的痛点。按业内的实测口径，每个技能的元数据大约只吃 100 个 token，哪怕你一口气装了 50 个技能，初始上下文也就多占 5000 token 左右。等到 AI 真正决定用某个技能时，才会把那几千 token 的详细指令读进来。

这跟"把所有规则一股脑写进提示词"是两种完全不同的思路。提示词那套，是不管用不用得上，开局就全塞给模型，上下文很快就被挤爆；而且塞得越多，模型的注意力越容易被带偏，工具调用的准确率反而往下掉。渐进式披露恰好把这两个问题一起解决了——平时轻装上阵，干活时才精准取用。

我自己的体会是：一旦理解了"按需加载"这件事，你写技能的心态会变。你不会再想着"把所有情况都写进一个超长文件里"，而是学会把核心放在正文、把细节拆进 references/、把重复操作交给 scripts/。文件结构清爽了，AI 用起来也更稳。

三、Skill、Prompt、MCP、RAG 到底怎么分工

很多人刚接触这堆概念时会犯晕：提示词、RAG、函数调用、MCP、Skill，听着都像是"让 AI 更强"的东西，到底有啥区别？我用自己的话给你捋一遍。

提示词（Prompt） 是反应式的、一次性的。你说"帮我润色这段代码"，它就润色这一次。它很灵活，但通常不跨会话保存，换个对话就得重来。

RAG（检索增强） 解决的是"知识从哪来"。它让模型在回答前先去知识库里捞相关资料，把外部知识临时拼进上下文，主要补的是"信息"。

MCP（模型上下文协议） 解决的是"手脚怎么接出去"。它是一套标准接口，让模型能连上数据库、调外部工具、读你的网盘和代码仓库。业内有个很形象的比喻：MCP 像 AI 时代的"USB 接口"，负责把模型和外部世界接起来。

Skill 解决的是"知道了工具，但该怎么用"。它装的是程序性知识，也就是操作手册、标准流程。沿用上面的比喻，如果说 MCP 给了 AI 一双"手"，那 Skill 就是教这双手怎么干活的"操作说明书"。

放一张表对照着看更清楚：

这里要特别说一句 Skill 和 MCP 的关系，因为最容易被误解成"二选一"。其实它俩是互补的。MCP 负责"连接层"——把工具和数据接进来；Skill 负责"行为层"——告诉模型按你们公司的规范，怎么用这些工具去查数、出报表、处理异常。

更妙的是，Skill 还能给 MCP"减负"。典型的 MCP 服务器一连上，往往要把所有工具的完整描述一次性塞进上下文，动辄上万 token。社区里有个挺经典的做法：用一个轻量 Skill 当"网关"，平时只在文件头里描述几句功能，初始开销压到几百 token；等 AI 真判断需要时，才加载详细指令、再去调底层的 MCP 工具。一来一去，初始成本能砍掉一大截。

所以别再纠结"学了 MCP 是不是 Skill 就没用了"。在稍微正经一点的工程里，这俩是搭配着用的：MCP 铺基础设施，Skill 管业务逻辑。

四、为什么"写个 SKILL.md"远远不够

聊到这儿，可能有人已经跃跃欲试了：不就是写个 SKILL.md 嘛，我现在就能整一个。

这话对了一半。自己玩、做个一次性原型，确实写个文件就够了。 但只要你想把这个技能交给团队长期用，事情立刻就复杂起来。我自己踩过坑才慢慢明白，一个能"扔进团队里反复用"的技能，至少要解决下面这几个工程问题。

第一个是路由识别。 你写的 description 到底能不能让 AI 在该触发的时候触发、不该触发的时候老实待着？描述太笼统（比如"帮助处理项目"），AI 根本不知道什么时候叫它；描述和别的技能撞了车，两个相似技能还会互相抢活。这事儿听着小，实际是技能能不能用起来的第一道门槛。

第二个是质量评估。 一个 SKILL.md 写好放那儿，你没法像跑代码那样跑单元测试。它写得对不对、改了一版是更好还是更差，光靠"我觉得"是靠不住的。

第三个是版本治理。 技能会迭代。这一版改了啥、为什么改、谁审过、什么时候该升级到生产级——这些如果没人记录，时间一长就成了一笔糊涂账。

第四个是跨平台兼容。 Claude、Cursor、Codex 各家的目录约定、实现细节不完全一样。你辛辛苦苦写的技能，会不会被某一款工具锁死、换个环境就跑不了？

你看，从"写个文件"到"做个资产"，中间隔着的是一整套工程化的活：意图澄清、路由设计、基准对照、质量评估、打包发布、生命周期治理。把这些一项项做下来，技能才从一个"随手写的草稿"，变成一个"你敢放心交给团队"的东西。

这也正是开源项目 yao-meta-skill 想解决的事。它由开发者 yaojingang 开源（采用 MIT 协议），核心理念用一句话概括就是：构建可复用的技能包，而不是写长长的提示词。 作者把 YAO 解释为 "Yielding AI Outcomes"——产出 AI 结果、交付真实成果，强调的不是生成更多提示词文本，而是沉淀能落地的 AI 资产。下面几章，我就借它把"技能工程"这套方法论拆开讲。

五、一套把"草稿"变成"资产"的工程流程

很多人写技能的顺序是这样的：脑子里想个大概，打开编辑器敲一段 SKILL.md，复制到项目里就用。yao-meta-skill 反过来，给你一条完整的闭环，让每一步都留下痕迹。我把它拆成六个环节讲。

意图对话：先把"要解决什么"问清楚

最容易被跳过、其实最关键的一步，是动手写之前先跟需求方聊明白。

这套方法里有个细节我很认同：它不是一上来就甩给你一张表格让你填，而是先做一轮有人味的意图对话，用两三个高杠杆问题，把模糊需求逼成清晰定义——这个技能到底要解决什么真实问题？产出什么？不做什么？符合什么标准？只有当理解还不够清楚，或者出现真正的设计冲突时，它才会再追问一两个问题。

这一步的产物，会落成一份意图记录（类似 reports/intent-dialogue.md）。别小看这份文档，它不是给外人看的，而是让你自己日后能拍着胸脯说"我清楚这技能当初是为了啥造的"。

路由设计：让 Agent 在对的时候触发

接下来是写那段精简的 SKILL.md 当"入口"，再配一份接口声明（比如 agents/interface.yaml）。这一步的目标只有一个：让 Agent 准确识别什么时候该唤醒这个技能。

写 description 是门手艺。官方的建议是：要具体、可操作，把用户真正会说的"触发短语"写进去，比如"创建 sprint 时""上传 .fig 文件时"；同时避免"可能""大概"这类模糊词。如果技能触发得太频繁，还可以加负面触发词（明确写出 Do NOT 的场景）来收一收边界。

参考扫描：先看世界级范本，再做本地适配

闭门造车容易写出自嗨的技能。yao-meta-skill 在深度起草前，会静默地先做一轮基准扫描和参考综合——优先去学高质量的公开项目和成熟模式，把行业里的好做法吸收进来。

它还有个我挺喜欢的设定：会主动问你"有没有希望借鉴的参考对象"。但注意，它只学其中的模式、结构和标准这些抽象层面的东西，不复制原文、也不碰你的私密内容。最后再结合你的实际情况做本地校准。先看标杆、再问偏好、最后落地，这个顺序很务实。

质量评估：给技能跑一次"单元测试"

这是把技能从"玩具"拉到"资产"的分水岭，我单独放到第七章细讲。这里先记住一句话：在这套方法里，质量评估是默认动作，不是可选项。

打包与跨平台分发

技能写好、测好之后，要能打包成不同平台都能用的成品。yao-meta-skill 支持从单一源码打包到 OpenAI / Claude / 通用 三种目标格式，并保留中立的元数据，这块我放到第八章讲。

生命周期治理：让迭代有据可查

最后是长期维护。每次迭代改了什么、有什么证据支撑、成熟度打几分、按什么节奏复审、什么时候该从"脚手架"升级到"生产"——这些都记录在案（比如迭代账本 iteration-ledger.md、晋级决策 promotion-decisions.md）。这样技能才不会越改越乱。

把这六步连起来，你会发现它本质上是个 "技能脚手架 + CI/CD" 的二合一：先帮你从零搭出一个合格的技能，再用工程手段持续守住它的质量。下面这张流程图，把整条链路串了起来：

flowchart TD
    A[原始素材: 工作流/提示词/笔记/会议记录] --> B[意图对话<br/>问清要解决什么]
    B --> C[路由设计<br/>SKILL.md + 接口声明]
    C --> D[参考扫描<br/>对照世界级范本]
    D --> E[质量评估<br/>触发准确率 + 盲评]
    E --> F[打包分发<br/>跨平台成品]
    F --> G[生命周期治理<br/>证据/成熟度/复审]
    G -.持续迭代.-> C

六、轻重要匹配风险：三种运行模式

技能工程最容易犯的毛病，是过度设计——为一个一次性的小活，硬整出一套复杂的治理流程，结果投入产出严重不划算。我自己早期就干过这种蠢事，花一下午给一个只用一次的脚本写了评估集，纯属自我感动。

yao-meta-skill 给的解法很清醒：流程的重量，应该和风险成正比。 它定义了三种运行模式，让你按场景选：

这个分级背后还藏着一棵"非技能决策树"——它会帮你判断：眼前这个需求，到底该不该做成技能？ 有些活就是一次性的，做成技能反而是负担。能识别出"这不是技能，就是个一次性任务"，本身就是一种成熟。

所以我现在的习惯是：先问自己这活会不会反复出现、值不值得沉淀；确定要做了，再挑最轻的那个够用的模式起步，等真有团队复用需求了，再往上升级。别一上来就奔着 Library 去，那是给自己找罪受。

七、质量评估怎么做：给路由"判分"

前面反复强调"评估是默认动作"，这一章就把它讲透。因为说到底，技能这件事上最让人不安的一个问题就是：你怎么知道你这技能写对了？

一个 SKILL.md 摆在那儿，它既不是能编译的代码，也不是能跑断言的函数，你没法一键验证。yao-meta-skill 给的答案，是一套多层次的评估体系。我挑几个核心的说。

用三层数据集测"触发准确率"

最基础的一关，是验证你的 description 能不能被正确识别。做法借鉴了机器学习里的老套路：把测试用的真实提示词分成训练集 / 开发集 / 留出集三层。

• 训练集 / 开发集：用来反复调你的描述。
• 留出集（holdout）：藏起来，只在你已经在开发集上选出"最优版本"之后，才拿出来做最终验收。

这么分的目的，是防止你"对着测试题改答案"——如果所有用例你都见过，调出来的高分是假的。留出集就是那张你没提前看过的卷子。

对应到项目里，大致是这样的目录和用例形态：

evals/
├── trigger_cases.json      # 触发用例：prompt -> 期望是否命中本技能
└── blind_holdout/          # 盲测留出集，选出赢家后才用

{
  "cases": [
    { "prompt": "帮我把这段会议录音转写整理成纪要", "expect": "hit" },
    { "prompt": "今天天气怎么样",                   "expect": "miss" }
  ]
}

盲评、法官复核与对抗样本

光测命中率还不够。这套方法还配了几道更狠的关卡：

• 描述优化套件：把同一个技能的多版 description 拿来做盲评对比，看哪一版路由表现最好。盲评的意思是评的时候不知道哪版是哪版，避免主观偏心。
• 法官式复核：再请一个独立的"评分者模型"，对胜出的版本做二次验证，相当于多一道把关。
• 对抗样本：专门准备一批"难题"——那些容易和别的技能撞车的、带迷惑性的负样本，用来测技能在嘈杂环境下还稳不稳。
• 路由记分卡：用一份 route_scorecard.md 把相似技能之间的相互干扰可视化出来，防止"路由混淆"。

除此之外，还有资源边界检查（确保技能不越权操作）和治理检查（验证元数据完整性）这些确定性的脚本，把那些能用规则卡死的东西，交给规则去卡，不靠人肉盯。

我自己的感受是：有没有这套评估，写技能的心态完全不一样。没有它，你改一版描述全凭手感，改完心里也没底；有了它，每次改动是涨了还是掉了，分数一跑就知道。这种"可量化的反馈"，才是工程化和手工作坊的根本区别。

八、跨平台兼容：别让技能被某个工具锁死

技能生态里有个很现实的痛点：平台碎片化。Claude Code 用一个目录约定，Cursor 有自己的一套，OpenAI 那边的实现逻辑又不一样。你辛苦写的技能，万一被某一款工具绑死，换个环境就废了，那复用性就成了空话。

yao-meta-skill 在 2.0 里把这件事抬到了一个新高度，提出了 Skill OS 的概念。它不止是生成一个 SKILL.md，而是围绕这个技能生成一套结构化契约：

• Skill IR（技能中间表示）：用一种平台无关的结构，把意图、触发方式、输入输出、边界、参考资料和交付物都记录下来。你可以把它理解成技能的"源码中间层"。
• 跨端编译：从这份中立的中间表示出发，编译/打包到 OpenAI、Claude、通用 三种目标格式，同时保留中立的激活、执行、信任、降级等元数据。
• 项目自述的可移植性评分是 100/100——意思是它把"一次构建、多端复用"当成硬指标在追。

这套思路的价值在于：你的技能资产，不会被锁死在某一款工具上。 今天用 Claude，明天团队换了 Cursor，技能还能跟着走。

⚠️ 一点合规提醒：技能体系里常会接触到境外的 AI 模型与平台（如 OpenAI、Claude 等）。在国内环境落地时，使用境外模型与服务需遵守国内网络与内容管理的相关规定；涉及数据出境、内容审核的场景，建议优先评估合规边界，必要时换用境内可访问的替代方案。这一条我放在显眼处，是因为它比技术细节更容易被忽略，也更容易出事。

九、上手实操：从安装到第一个技能

讲了这么多原理，落到手上其实没那么玄。这一章我按"安装 → 放对位置 → 让它自己生成技能"的顺序，带你走一遍。

怎么把技能装进你的 Agent

最朴素的方式，就是把技能文件夹直接放到你 Agent 约定的技能目录下。不同工具的目录约定略有差别，但思路一致：文件放对地方，AI 启动时扫描到，就自动认得它。 不需要你手动"运行"或"激活"，这正是渐进式披露的好处——它平时就在那儿待命，碰到对应任务才被唤醒。

我自己更偏爱用命令行一键安装，省得手动拷来拷去。比如用社区的安装器把某个技能链接到本地：

# 用 skills 安装器，从 GitHub 仓库装一个指定技能
npx skills add https://github.com/yaojingang/yao-meta-skill --skill yao-meta-skill

如果你用的是 OpenSkills 这类跨 Agent 的命令行工具，它把 Anthropic 的开放标准扩展到了 Cursor、Claude Code、Windsurf、Aider 等一票工具上，常用命令大概是这样：

# 从官方市场装上全部技能
openskills install anthropics/skills

# 从某个 GitHub 仓库装特定技能
openskills install username/repo-name

# 装到"通用目录"，多个 Agent 共享（个人比较推荐这种）
openskills install anthropics/skills --universal

# 列出当前已安装的技能
openskills list

装好之后，使用时一般只要在指令里提到技能名字或相关关键词，Agent 就会自动把它调起来。比如装好文档类技能后，你直接说"用 PDF 技能提取这个文件里的表单字段"，它就接管了。

一个治理就绪的技能，目录长什么样

如果你要做的是一个比较正式、能交给团队的技能，目录通常会比"最小结构"丰满一些。给你一个参考样板：

my-skill/
├── SKILL.md                 # 入口路由文件
├── agents/
│   └── interface.yaml       # Agent 接口声明
├── references/              # 参考资料（方法、示例等）
├── scripts/                 # 确定性脚本
├── evals/                   # 评估用例
│   ├── trigger_cases.json
│   └── blind_holdout/
├── reports/                 # 评估报告与迭代证据
│   ├── intent-dialogue.md
│   ├── skill-overview.html
│   ├── iteration-ledger.md
│   └── promotion-decisions.md
├── manifest.json            # 治理元数据（生产级才需要）
└── VERSION                  # 版本号

但请务必记住一句话：不是每个目录都必须有。 这套方法的精神是"按需添加"——一个你自己用的轻量技能，可能真就只有一个 SKILL.md。别被这张完整图吓到，照着风险等级往里填就行。

别自己硬写，让"造技能的技能"帮你写

技能开发门槛低，但这不代表你得一个字一个字手敲。一个很省力的做法是：用一个"元技能"去生成业务技能。

不管是 Anthropic 官方的 Skill Creator，还是这篇聊的 yao-meta-skill，逻辑都类似——你把那一堆乱七八糟的素材（工作流笔记、提示词、聊天记录、操作清单）丢给它，用自然语言说清楚你想干嘛，它就帮你产出一个符合标准的技能包。区别在于侧重点：官方那个更偏"对话式创作、人工引导迭代"；yao-meta-skill 更偏"团队复用、显式边界、评估、治理和跨平台"。作者自己也给了个很实在的建议——先用对话式的工具快速做出第一版，再用 yao-meta-skill 把它加固成团队能用的正式资产，两者搭配，不冲突。

整个上手过程，串起来大概是这样：

flowchart LR
    A[准备素材] --> B[安装元技能]
    B --> C[自然语言描述需求]
    C --> D[生成技能包草稿]
    D --> E[跑评估 + 调描述]
    E --> F[打包/放进 Agent 目录]
    F --> G[日常自动触发使用]

十、我自己踩过的几个坑，顺便给点建议

工具再好，用歪了照样翻车。下面这几条是我自己折腾下来攒的教训，分享给准备入坑的你，能少走点弯路。

第一坑：描述写得太虚，技能根本不触发。 早期我图省事，description 写成"帮助处理文档"这种万金油，结果 AI 压根分不清什么时候该叫它。后来才明白，描述里一定要塞进用户真实会说的话——具体的动作、具体的文件类型、具体的场景词。比如"当用户上传 .docx 并要求转成网站博文时"，比"处理文档"管用一百倍。

第二坑：触发太频繁，到处抢活。 描述写得太宽，又会走向另一个极端——什么沾边的活它都往身上揽，跟别的技能打架。解法是加负面触发词，明确写清楚"不要在什么情况下触发"，把边界收紧。正反两面都写到，路由才稳。

第三坑：过度设计，给一次性任务上重型流程。 这个前面说过，我再强调一遍，因为太容易犯了。判断标准很简单：这活会不会反复出现？值不值得沉淀？ 不值得，那它就只是个一次性任务，别硬做成技能。

第四坑：不做评估，全靠手感。 改一版描述觉得"好像更好了"，其实可能更差了——人的直觉在这种事上特别不靠谱。哪怕你只是个人用，也建议攒十来个真实用例当小测试集，改完跑一遍，心里才有数。

第五坑：把所有细节都堆进正文。 渐进式披露的精髓是分层。正文（第二层）只放核心流程，把详细参考拆进 references/、把重复操作交给 scripts/。正文越精炼，加载越快，AI 越不容易被无关信息带偏。

第六坑：脚本来源不审就敢跑。 技能可以带脚本、能执行命令，这意味着来源不明的技能本身就是一个安全风险。装别人的技能前，务必看一眼里面的脚本到底干了啥，尤其警惕那种偷偷读你文件、发你数据出去的操作。这条放到下一章再细说。

我的整体心得就一句：别神化工具，也别糊弄流程。 把"轻量"和"可靠"这两件事同时拿住，技能才能既好用又长久。莫潇羽@源码七号站 这半年攒下的技能里，真正跑得久的，全是那些一开始就把描述和评估认真做扎实的。

十一、合规与安全：国内落地必须绷住的几根弦

技术的事聊得差不多了，但有几根弦，在国内做技能工程时必须时刻绷着。我把它单独拎出来，是