主页
030 秒速览The 30-second version
一个 Agent Skill 就是一个文件夹,里面必须有一个 SKILL.md。这个文件的开头是几行元数据(名字 + 一句「什么时候该用我」的描述),下面是给 Agent 看的操作说明。文件夹里还可以塞脚本、参考文档、模板。
An Agent Skill is a folder that must contain a SKILL.md. That file opens with a few lines of metadata (a name, plus a description saying when to use it), followed by instructions written for the agent. The folder can also bundle scripts, reference docs and templates.
关键的设计不是格式,而是加载方式:启动时 Agent 只读每个技能的名字和描述(每个约 30–50 token),只有当任务匹配上描述,才把完整正文读进上下文。所以你可以挂几十个技能而几乎不占地方。
The interesting design choice isn't the format — it's the loading strategy. At startup the agent reads only each skill's name and description (roughly 30–50 tokens apiece). The full body loads only once a task matches that description. That's how you can keep dozens of skills on hand at near-zero context cost.
1它来解决什么痛点The problem it solves
先说 Skills 出现之前的世界。你手上有一个通用能力很强的 Agent:会写代码、会 debug、会写文档。但它不知道你这边的规矩——你们团队的 commit message 怎么写、你们的 lint 流水线是自定义的、每个 PR 合并前必须过一份安全清单。
Start with the world before skills. You have an agent that's broadly capable — it writes code, debugs, produces docs. What it doesn't know is your local rules: how your team writes commit messages, that your lint pipeline is custom, that every PR needs a security checklist before merge.
过去的做法是:把这些偏好、约定、工具文档一股脑塞进系统提示。问题很直接——这段提示每一次会话都会加载,不管你今天用不用得上。它和你真正的工作内容抢同一个上下文窗口。
The standard workaround was to stuff all of it into the system prompt. The problem is blunt: that prompt loads every session, whether it's relevant or not, competing with your actual work for the same context window.
Skills 的赌注就下在这里:与其造一堆专用的单一用途 Agent,不如给一个通用 Agent 配一个技能库,用的时候才取。Anthropic 的产品经理 Mahesh Murag 把这个设计原则叫做「渐进式披露(progressive disclosure)」——每个技能平时只占几十个 token 的「摘要」,细节等任务需要时再展开。
That's where skills place their bet: rather than building a fleet of narrow single-purpose agents, give one general-purpose agent a skill library it draws from on demand. Anthropic PM Mahesh Murag calls the underlying principle "progressive disclosure" — each skill costs a few dozen tokens as a summary, with the detail expanding only when the task calls for it.
换个说法:图书馆和背包
Another way to put it: the library and the backpack
系统提示像是「把整个书架背在身上」——每天都背,不管今天读不读。Skills 像是「随身带一份索引卡,书留在图书馆」——你只背卡片(名字 + 一句这本书讲什么),真要用了才去把那本书取下来。索引卡很薄,所以你可以带 50 张。
A system prompt is like carrying the whole bookshelf on your back — every day, read or not. Skills are like carrying an index card per book and leaving the books on the shelf: the card holds only a title and a line about what's inside, and you fetch the actual book when you need it. Cards are thin, so you can carry fifty.
格式本身由 Anthropic 提出,2025 年 12 月 18 日作为开放标准发布,现在规范托管在 agentskills/agentskills(代码 Apache-2.0,文档 CC-BY-4.0),已经被 20 多个 Agent 产品采用——同一个 SKILL.md 文件在 Claude Code、OpenAI Codex CLI、Gemini CLI、GitHub Copilot、Cursor、VS Code 上都能直接用,不用改。
The format itself came from Anthropic and was released as an open standard on 18 December 2025. The spec now lives at agentskills/agentskills (code Apache-2.0, docs CC-BY-4.0) and has been adopted by more than twenty agent products — the same SKILL.md runs unmodified in Claude Code, OpenAI Codex CLI, Gemini CLI, GitHub Copilot, Cursor and VS Code.
2机制:渐进式披露的三个阶段Mechanism: the three stages of progressive disclosure
规范把加载过程明确拆成三段。理解这三段,你就理解了 Skills 的全部魔法(以及它的全部局限)。
The spec breaks loading into three explicit stages. Understand these three and you understand both the whole trick and all of its limits.
图 1:渐进式披露三阶段。数字来自 agentskills 官方 README 与 2026-02 Bosch/CMU 研究(arXiv:2602.08004)。
Fig. 1 — The three stages of progressive disclosure. Figures from the official agentskills README and the Feb 2026 Bosch/CMU study (arXiv:2602.08004).
description 字段是整个技能里最重要的一行。它是唯一在「发现」阶段被读到的东西,也就是说:它是决定技能会不会被用的全部依据。写得含糊(「帮助处理代码」),技能就会长期躺在硬盘上;写得具体(「用 conventional commits 规范格式化提交信息。当用户要求撰写、审查或修正 commit message 时使用」),它才会在该出现的时候出现。
The description field is the single most important line in the whole skill. It's the only thing read during discovery — which means it is the entire basis on which the skill does or doesn't get used. Write it vaguely ("helps with code") and the skill sits on disk forever. Write it precisely ("Format commit messages using the conventional commits spec. Use when the user asks to write, review, or fix a commit message") and it fires at exactly the right moments.
Anthropic 侧的最佳实践里还有一条反直觉的建议:description 要写得「稍微强势一点」,因为 Claude 有一个可测量的欠触发(under-trigger)倾向——它宁可不用技能也不愿误用。
Anthropic's own guidance adds a counter-intuitive note: write the description a little "pushy", because Claude has a measured tendency to under-trigger skills — it would rather skip one than misapply it.
3一个 Skill 长什么样Anatomy of a skill
最小可用形态就是一个文件夹加一个文件:
The minimum viable form is one folder and one file:
my-skill/
└── SKILL.md # 必需:YAML 元数据 + markdown 说明my-skill/
└── SKILL.md # required: YAML frontmatter + markdown instructions完整形态多出三个约定俗成的目录:
The full form adds three conventional directories:
skill-name/
├── SKILL.md # 必需
├── scripts/ # 可选:可执行的 Python / Bash / JS
├── references/ # 可选:按需加载的详细文档
└── assets/ # 可选:模板、schema、数据文件skill-name/
├── SKILL.md # required
├── scripts/ # optional: executable Python / Bash / JS
├── references/ # optional: detailed docs, loaded on demand
└── assets/ # optional: templates, schemas, data filesSKILL.md 的两部分
The two halves of SKILL.md
上半部分是 YAML 元数据(frontmatter),下半部分是纯 markdown 的指令正文。一个真实可跑的最小例子:
The top half is YAML frontmatter; the bottom half is a plain-markdown instruction body. A minimal working example:
---
name: format-newsletter
description: 把原始文字整理成专业的周报结构。当用户提供
草稿、要求「排版 / 结构化 / 清理 newsletter」时使用。
---
# Newsletter 格式化
## 何时使用
用户给了 newsletter 原始文字、想要专业结构,或提到「格式化 newsletter」时。
## 步骤
1. **清理**:去掉多余换行,修正空格。
2. **结构**:确保存在 标题 / 引言 / 本周更新(用列表)/ 本周金句 / 行动号召。
3. **语气**:口语但专业。
4. **格式**:用 Markdown 标题(#、##)与加粗(**)。---
name: format-newsletter
description: Formats raw text into a professional weekly newsletter
structure. Use when asked to format, structure, or clean up a draft.
---
# Newsletter Formatting
## When to use
Whenever the user provides raw newsletter text, wants a professional
structure, or mentions "formatting the newsletter."
## Instructions
1. **Cleanup:** remove excessive line breaks, fix spacing.
2. **Structure:** ensure Title / Introduction / Key Updates (bulleted) /
Quote of the Week / Call to Action all exist.
3. **Tone:** conversational yet professional.
4. **Formatting:** Markdown headers (#, ##) and bolding (**).代码示例来自 Firecrawl 的 Agent Skills 解析文(2026-05 更新),与 agentskills 官方 README 的结构描述一致。
Example adapted from Firecrawl's Agent Skills explainer (updated May 2026); consistent with the structure described in the official agentskills README.
值得知道的 frontmatter 字段
Frontmatter fields worth knowing
| 字段 | 作用 | 什么时候用 |
|---|---|---|
name | 技能名,同时变成斜杠命令。只允许小写字母、数字、连字符,上限 64 字符。 | 必填。deploy-to-staging 合法,Deploy_To_Staging 不合法。 |
description | 决定技能会不会被激活。写给模型看,不是写给人看。 | 必填,而且是全场最重要的一行。 |
disable-model-invocation | 关掉自动加载,只能用户手动 /name 调用;description 完全退出上下文,「上下文税」降到近零。 | 有副作用的技能:部署、提交、对外写操作。 |
paths | glob 模式,限制技能在哪些路径下才考虑自动激活。 | 技能只适用于 libs/go/ 时,在别处就不参与匹配。 |
allowed-tools | 限定技能可用的工具范围,支持通配(如 Bash(gh *))。 | 收窄权限面。注意:这是 CLI 侧字段,通过 SDK 使用时不生效。 |
effort | 思考深度:low / medium / high。 | 格式化类用 low;架构决策类用 high。别留给默认。 |
context: fork | 在独立 subagent 里跑,拥有自己的上下文窗口。 | 要吞大量参考资料、否则会撑爆主会话的技能。 |
argument-hint | 自动补全时提示参数,如 [environment] → /deploy [environment]。 | 需要参数的技能。 |
| Field | What it does | When to reach for it |
|---|---|---|
name | Skill name, which also becomes the slash command. Lowercase letters, numbers and hyphens only; 64 characters max. | Required. deploy-to-staging is valid; Deploy_To_Staging is not. |
description | Decides whether the skill activates at all. Written for the model, not for humans. | Required — and the most consequential line in the file. |
disable-model-invocation | Turns off automatic loading; users invoke it manually with /name. The description drops out of context entirely, cutting the "context tax" to near zero. | Skills with side effects: deployments, commits, external writes. |
paths | Glob patterns limiting where the skill is considered for auto-activation. | A skill that only applies to libs/go/ shouldn't compete elsewhere in the repo. |
allowed-tools | Scopes which tools the skill may use; supports wildcards such as Bash(gh *). | Narrowing the permission surface. Note: this is a CLI-side field and does not apply when using skills through the SDK. |
effort | Thinking depth: low / medium / high. | low for a formatting skill, high for architecture calls. Don't leave it to chance. |
context: fork | Runs the skill in an isolated subagent with its own context window. | Reference-heavy skills that would otherwise bloat the primary session. |
argument-hint | Shows expected arguments in autocomplete: [environment] → /deploy [environment]. | Any skill that takes arguments. |
正文里还能用三个运行时变量:$ARGUMENTS(斜杠命令后面跟的全部内容)、$ARGUMENTS[0](按位取参)、${CLAUDE_SKILL_DIR}(引用打包脚本时用,不受用户当前工作目录影响)。
The body also supports three runtime substitutions: $ARGUMENTS (everything passed after the slash command), $ARGUMENTS[0] for positional access, and ${CLAUDE_SKILL_DIR} for referencing bundled scripts regardless of the user's working directory.
references/,让它按需加载。
The spec recommends keeping SKILL.md bodies under 5,000 tokens and whole skill directories under 500 lines. That's not pedantry — it forces you to separate what the agent actually needs from what's merely nice to have. Want more detail? Push it into references/ and let it load on demand.
技能装在哪儿
Where skills live
- Claude Code:默认读
~/.claude/skills - Codex CLI:
~/.codex/skills - Gemini CLI:扫描
~/.gemini/skills - Cursor:读项目级目录
- Claude Code reads from
~/.claude/skillsby default - Codex CLI uses
~/.codex/skills - Gemini CLI scans
~/.gemini/skills - Cursor reads project-level directories
社区维护的 npx skills CLI(Vercel Labs)会自动判断装到哪里:
The community npx skills CLI (Vercel Labs) handles placement automatically:
npx skills add firebase/agent-skills
npx skills add anthropics/skills/pdf⚠️ 手动安装时,放好目录后需要重启会话——技能是在启动时被发现的。
⚠️ If you install manually, restart the session after dropping the folder in place — skills are discovered at startup.
4怎么写才有用Writing one that actually works
格式十分钟就学会了。难的是下一个问题:这个技能该不该存在,以及它该多短。下面这套流程综合了 Anthropic 的官方最佳实践、一篇被广泛引用的工程博客《Does Your Skill Earn Its Keep?》,以及 2026-07 的论文《Authoring Agent Skills: A Software-Engineering Approach》。
The format takes ten minutes to learn. The hard question comes next: should this skill exist at all, and how short can it be? The workflow below combines Anthropic's published best practices, a widely-cited engineering post titled "Does Your Skill Earn Its Keep?", and the July 2026 paper Authoring Agent Skills: A Software-Engineering Approach.
- 先不带技能试一次。打开 Agent,直接描述你要什么,什么技能都不装。如果它已经做得挺好,你不需要技能。如果它做成了但绕了远路,或者以某种具体的方式失败了——那个缺口,就是你的技能该填的,仅此而已。跳过这一步,你根本不知道 Agent 在哪里需要帮助。
- 算一下「上下文税」。你的 description 会在每一次会话加载,不管技能触没触发。100 token 的描述 × 1,000 个工程师 × 每天 10 次会话 = 每天 100 万 token 的固定开销,而且是在 Agent 碰到任何真实任务之前。问题不是「这个技能有用吗」,而是「它挣得回自己的成本吗」。10 个人时你察觉不到;10,000 个人时,一个定位不准的技能就是每天都在复利的隐形税。
- 先写评测,再写技能。确认缺口真实存在后,别急着写技能——先写一个 eval。把任务编码成可测的形式,量出当前模型 + 当前 harness 的基线。这样技能写完你才知道它到底有没有帮上忙。没有 eval,你就是在猜:你可能写出一个增加噪声、误导模型、或与其它技能冲突的东西。
- 问一句:这是技能,还是脚本?如果它主要是一串确定性步骤,如果有人能用 bash 脚本或一个 Makefile target 完成其中 80%——那就写脚本。最糟的技能是用 500 token 的自然语言描述一件其实等同于
make test加几个 flag 的事。技能可以调用脚本:脚本负责可预测的部分(便宜、可靠),技能负责判断——什么时候跑、输出怎么解读、出意外了怎么办。 - 写到最小。目标不是一份完整指南,不是教程,是一次轻推:指向正确的框架、提醒一条模型不可能知道的内部约定、点出一个容易漏的 flag。每多一行都是模型要处理的额外上下文、更多指令冲突的可能、以及将来更大的维护负担。最好的技能,一分钟内读得完。
- 诚实对待适用范围与分发方式。这个技能是给谁的?一份专为你们团队工作流写的端到端技能,对团队外几乎没用——如果它进了默认集合,所有人都在替它交上下文税。普适的放进默认配置;团队/领域专用的做成 opt-in。一个对 15 个人极有价值、对另外 5,000 人纯属噪声的技能,不该被默认加载。
- Try the task without a skill first. Open the agent and describe what you want with nothing installed. If it already handles the task well, you don't need a skill. If it succeeds but takes a roundabout path, or fails in a specific way, that gap is what your skill should fill — and nothing more. Skip this step and you can't know where the agent actually needs help.
- Do the context-tax arithmetic. Your description loads into context on every session, for every engineer, whether the skill fires or not. 100 tokens of description × 1,000 engineers × 10 sessions a day = a million tokens of daily overhead before the agent touches a single task. The question isn't "is this useful?" but "will it earn back what it costs to carry?" At ten engineers you'll never notice. At ten thousand, a poorly targeted skill is a silent tax compounding daily.
- Write the eval before the skill. Once you've identified a real gap, don't write the skill yet — encode the task as a measurable eval and establish a baseline for your current model and harness. Only then can you tell whether the skill actually helped. Without an eval you're guessing, and you may ship something that adds noise, confuses the model, or conflicts with other skills.
- Ask: is this a skill or a script? If it's mostly a sequence of deterministic steps — if someone could write a bash script or a Makefile target that does 80% of it — write the script instead. The worst skills spend 500 tokens of natural language describing something that is really just
make testwith a few flags. A skill can call a script: the script handles the predictable parts cheaply and reliably, while the skill handles the judgement — when to run it, how to read the output, what to do when something unexpected happens. - Keep it minimal. You're not writing a comprehensive guide or a tutorial. You're writing a nudge: a pointer to the right framework, a reminder of an internal convention the model can't know, a specific flag that's easy to miss. Every extra line is more context to process, more room for conflicting instructions, and more maintenance debt later. The best skills read in under a minute.
- Be honest about scope and distribution. Who is this for? A detailed end-to-end skill built around your team's workflow is unlikely to help anyone outside it — and if it ships in the default set, everyone pays its context tax. Broadly applicable? Ship it by default. Team- or domain-specific? Make it opt-in. A skill that's invaluable to 15 people and meaningless noise to 5,000 should not load by default.
图 2:「该不该写这个技能」的决策路径。综合自 Anthropic 最佳实践与《Does Your Skill Earn Its Keep?》。
Fig. 2 — Deciding whether a skill should exist. Synthesised from Anthropic's best practices and "Does Your Skill Earn Its Keep?".
5到底有没有用:第一批实测数据Do skills actually help? The first hard numbers
到 2026 年年中为止,这个问题一直靠体感回答。SkillsBench 是第一份把它量化的公开基准:86 个任务、11 个领域、配套人工策划的技能与确定性验证器,跑了 7,308 条轨迹。
Until mid-2026 this question was answered by vibes. SkillsBench is the first public benchmark to quantify it: 86 tasks across 11 domains, each paired with curated skills and deterministic verifiers, measured over 7,308 trajectories.
图 3:SkillsBench 主要结果(arXiv:2602.12670)。「pp」= 百分点。
Fig. 3 — Headline SkillsBench results (arXiv:2602.12670). "pp" = percentage points.
怎么读这几个数字
How to read these numbers
- 平均 +16.6pp 是真的,但平均值在这里很危险。软件工程只有 +4.5pp——如果你的场景就是写代码,别指望技能带来跃迁。医疗 +51.9pp 说明:模型越缺乏领域程序性知识的地方,技能的杠杆越大。
- 16/84 的负增益不是噪声,是警告。写坏了的技能会让 Agent 变差。这正是「先写 eval」那一步存在的理由。
- 模型自己写的技能平均无效。这是全篇最反直觉的一条:模型能受益于程序性知识,却不能可靠地产出它。所以「让 Claude 帮我把这个流程写成技能」可以当草稿起点,但不能当终点——人得进来做筛选和裁剪。
- 聚焦优于全面。2–3 个模块的紧凑技能,表现优于面面俱到的大文档。这和规范的 5,000 token 上限、以及「写成一次轻推」的建议是同一件事的三种说法。
- 小模型 + 技能 ≈ 大模型无技能。这条有直接的成本含义:某些任务上,与其升级模型档位,不如补一份好技能。
- +16.6pp on average is real, but averages are dangerous here. Software engineering gets only +4.5pp — if coding is your use case, don't expect a step change. Healthcare's +51.9pp tells the real story: the leverage is largest exactly where the model lacks domain procedural knowledge.
- 16 of 84 negative deltas is a warning, not noise. A badly written skill makes the agent worse. That is precisely why "write the eval first" exists as a step.
- Model-authored skills show no average benefit. The most counter-intuitive finding in the whole study: models can consume procedural knowledge reliably but can't produce it. "Have Claude turn this workflow into a skill" is a fine starting draft — it is not a finished artefact. A human has to prune.
- Focused beats comprehensive. Skills with 2–3 modules outperform exhaustive documentation. This is the same claim as the spec's 5,000-token ceiling and the "write a nudge" advice, stated three different ways.
- A small model with skills can match a large model without them. That has a direct cost implication: on some tasks, adding a good skill beats upgrading the model tier.
另一份补充证据来自 NVIDIA SkillEvaluator:用 2026-08-12 的基准快照,在正确性 / 可发现性 / 有效性 / 效率四个维度上给技能打分,baseline 平均分只有 39–46 分(满分 100)。换句话说:大部分已发布的技能,离「写好」还有很远。
A second data point comes from NVIDIA SkillEvaluator: scoring skills on correctness, discoverability, effectiveness and efficiency against an August 12, 2026 benchmark snapshot, average baseline scores landed at just 39–46 out of 100. Put plainly: most published skills are nowhere near well-written.
6和谁比:什么时候选 SkillsSkills vs the alternatives
Skills 不是唯一能给 Agent 加能力的方式。搞清它在生态里的位置,你才知道什么时候不该用它。
Skills aren't the only way to extend an agent. Knowing where they sit in the ecosystem is how you learn when not to reach for them.
| 方式 | 它给 Agent 的是 | 成本模型 | 什么时候选它 |
|---|---|---|---|
| Agent Skills | 程序性知识:「这类活该怎么干」 | 启动时每技能 30–50 token;命中才展开正文 | 有固定流程/约定/领域套路要教;跨产品复用;要版本控制 |
| MCP(Model Context Protocol) | 能力接口:「你可以调这些工具、读这些数据」 | 工具 schema 常驻上下文;需要跑一个 server | 需要真正连到外部系统(数据库、SaaS、内部 API) |
| 系统提示 / CLAUDE.md | 全局的、每次都成立的约束 | 每次会话全量加载 | 内容确实每次都需要(项目结构、语气、红线) |
| 脚本 / Makefile | 确定性执行 | 近乎为零(不进上下文) | 步骤固定、无需判断——这是最被低估的选项 |
| 微调 | 改变模型本身的倾向 | 训练成本 + 数据准备 + 迭代周期长 | 提示与技能都试过仍不够;有稳定大量的样本 |
| Approach | What it gives the agent | Cost model | Reach for it when |
|---|---|---|---|
| Agent Skills | Procedural knowledge — "here's how this kind of work is done" | 30–50 tokens per skill at startup; body expands only on a match | You have a repeatable workflow, convention or domain playbook to teach; you want cross-product reuse and version control |
| MCP (Model Context Protocol) | Capability surface — "here are tools you can call and data you can read" | Tool schemas sit in context; you have to run a server | You genuinely need to reach an external system: a database, a SaaS product, an internal API |
| System prompt / CLAUDE.md | Global constraints that hold every single time | Loaded in full, every session | The content really is needed every time — project layout, tone, hard rules |
| Scripts / Makefile | Deterministic execution | Effectively zero — never enters context | The steps are fixed and need no judgement. The most underrated option on this list. |
| Fine-tuning | Shifts the model's own dispositions | Training cost, data prep, long iteration loop | Prompting and skills were tried and weren't enough, and you have stable volume of examples |
7坑、税与安全Costs, noise and security
7.1 生态噪声:数量爆炸,质量没跟上
7.1 Ecosystem noise: explosive growth, lagging quality
2026 年 2 月,Bosch Research 与卡内基梅隆大学的研究者分析了 40,285 个公开技能(arXiv:2602.08004),数字很能说明问题:生态在 20 天里增长了 18.5 倍——1 月 16 日 2,179 个,2 月 5 日超过 4 万个;峰值出现在 1 月 25 日,单日发布 8,857 个,占该窗口全部新增的 23%。
In February 2026, researchers at Bosch Research and Carnegie Mellon analysed 40,285 publicly listed skills (arXiv:2602.08004). The numbers speak for themselves: the ecosystem grew 18.5× in twenty days — from 2,179 skills on 16 January to over 40,000 by 5 February, peaking on 25 January with 8,857 skills published in a single day, 23% of all new listings in the window.
- 46% 的市场条目和至少一个其它技能重名——大量近乎相同的转发副本。没有可靠的质量信号,找到某个任务的「最佳版本」需要比应有的更多手工评估。
- 供需错配:55% 的技能是软件工程流程(因为这是开发者最容易写的);而安装量最高的类别是信息检索(平均每个技能 1,268 次安装,约为代码生成类的 5 倍),恰恰长期供给不足——因为它需要稳定的连接器和持续维护。
- 46% of marketplace listings share a name with at least one other skill — a mass of near-identical reposts. Without reliable quality signals, finding the best version of a skill takes more manual evaluation than it should.
- Supply doesn't match demand: 55% of all skills are software-engineering workflows, because that's what developers find easiest to write. Meanwhile the highest-install category is information retrieval (averaging 1,268 installs per skill, roughly 5× code generation) and it stays chronically undersupplied, because it needs stable connectors and ongoing maintenance.
7.2 安全:把技能当依赖治理,而不是当文档审阅
7.2 Security: govern skills as dependencies, not as documents
MEMORY.md(Agent 的持久指令存储),使得技能被删除后,恶意行为仍然存活。
36% of skills carry a security flaw. 1,467 were found vulnerable, of which 534 (13.4%) contain at least one critical-level issue — malware distribution, prompt injection, exposed secrets. The nastiest observation: malicious skills rewrote MEMORY.md, the agent's persistent instruction store, so the malicious behaviour survived deletion of the skill itself.
学术侧给出的攻击面分类学(arXiv:2604.02837 等)列了六条路径:直接提示注入、间接提示注入、动态上下文、工具授权、外部依赖、市场信任。云安全联盟(CSA)把这类问题统称为「Agent 上下文投毒」——Anthropic 在 2026-02-10 的 Claude Code 版本里通过 Unicode 规范化修补过其中一种手法,但研究者指出:这类技术的门槛只是「攻击者能通过正常的技能分发渠道投递一个文件」。
The academic threat taxonomy (arXiv:2604.02837 and related work) lists six paths: direct prompt injection, indirect prompt injection, dynamic context, tool grants, external dependencies, and marketplace trust. The Cloud Security Alliance groups these under "agent context poisoning." Anthropic patched one variant via Unicode sanitisation in the 10 February 2026 Claude Code release — but as researchers note, the technique requires only that an attacker can deliver a file through the normal skill distribution channel.
前述 4 万技能研究还有一个量化补充:近 40% 的已发布技能会访问敏感上下文或执行写操作,9% 落在关键风险等级。而规范目前还没有在平台层面强制权限模型或沙箱——安全地限定作用域这件事,责任落在写技能的人身上。
The 40,000-skill study adds a quantitative complement: nearly 40% of published skills access sensitive context or perform writes, and 9% fall into the critical-risk category. The spec does not yet enforce a permission model or sandboxing at the platform level, so the burden of scoping skills safely falls on whoever writes them.
实操上的三条对策:
Three practical mitigations:
- 装第三方技能前通读 SKILL.md 全文和 scripts/ 里的每个脚本——它和装一个 npm 包是同一性质的操作,不是「读一篇文档」。
- 对有副作用的技能加
disable-model-invocation: true,让它只能被人手动调起,顺带把 description 的上下文税降到零。 - 用
allowed-tools收窄工具面(如Bash(gh *)而不是放开整个 Bash),并配合 Agent 侧的权限/沙箱设置。
- Before installing a third-party skill, read the whole SKILL.md and every script in scripts/. This is the same class of action as installing an npm package — not "reading a doc."
- Put
disable-model-invocation: trueon anything with side effects so it can only be invoked deliberately by a human — which also drops its description's context tax to zero. - Narrow the tool surface with
allowed-tools(Bash(gh *)rather than all of Bash), backed by your agent's own permission and sandbox settings.
7.3 三个还没解决的粗糙边缘
7.3 Three rough edges that remain
- 会话中途更新技能很别扭。技能在会话启动时加载。你推了 SKILL.md 的改动,正在跑的会话不会生效,得重启。对集中共享技能的团队来说,「不打断在跑的工作流去滚动更新」目前仍是没被工具解决的协调问题。
- 发现机制噪声大。重名率 46%,缺乏质量信号,挑技能仍然是体力活。
- 没有平台级权限模型。见 7.2。
- Updating a skill mid-session is awkward. Skills load at session start. Push a change to SKILL.md and a running session won't see it until restart. For teams sharing skills centrally, rolling out updates without disrupting active work remains an unsolved coordination problem.
- Discovery is noisy. A 46% name-collision rate and no reliable quality signal means choosing a skill is still manual labour.
- No platform-level permission model. See 7.2.
8学习资源与术语表Where to go next, plus a glossary
- agentskills.io —— 官方文档与规范正文(先看 Specification)
- agentskills/agentskills —— 规范仓库(20.6k star,Apache-2.0)
- anthropics/skills —— 官方参考技能,含
skill-creator、pdf / docx / xlsx / pptx 文档处理技能 - Claude Code · Extend Claude with skills —— Claude Code 侧的安装与使用文档
- Claude Platform · Agent Skills 概览 —— 平台/SDK 侧
- Anthropic Engineering · Writing effective tools for AI agents
- SkillsBench(arXiv:2602.12670) —— 效果评测
- Snyk · ToxicSkills —— 供应链安全实证
- DeepLearning.AI · Agent Skills with Anthropic —— 与 Anthropic 合作的短课程
- agentskills.io — official docs and the spec itself (start with the Specification)
- agentskills/agentskills — the spec repository (20.6k stars, Apache-2.0)
- anthropics/skills — official reference skills, including
skill-creatorand the pdf / docx / xlsx / pptx document skills - Claude Code · Extend Claude with skills — installation and usage on the Claude Code side
- Claude Platform · Agent Skills overview — platform and SDK side
- Anthropic Engineering · Writing effective tools for AI agents
- SkillsBench (arXiv:2602.12670) — effectiveness benchmark
- Snyk · ToxicSkills — supply-chain security evidence
- DeepLearning.AI · Agent Skills with Anthropic — short course built with Anthropic
- 渐进式披露(progressive disclosure)
- 只在需要时才把详细内容读进上下文的加载策略。Skills 的核心机制。
- 程序性知识(procedural knowledge)
- 「这类事情该怎么一步步做」的知识,区别于「这是什么」的事实性知识。Skills 装的主要是前者。
- 上下文税(context tax)
- 一个技能的 description 在每次会话都要占用的固定 token 开销,不管技能是否触发。乘以团队人数和会话频率后会变得可观。
- 欠触发(under-trigger)
- 模型倾向于不去调用本该调用的技能。对策是把 description 写得更具体、更「强势」。
- 上下文投毒(context poisoning)
- 攻击者通过正常渠道投递一个含恶意指令的文件(如 SKILL.md),让 Agent 把它当成合法指令执行。
- pp(percentage point,百分点)
- 两个百分数之间的绝对差值。33.9% → 50.5% 是 +16.6pp,不是 +16.6%。
- Progressive disclosure
- A loading strategy that pulls detail into context only when it's needed. The core mechanism behind skills.
- Procedural knowledge
- Knowledge of how a class of task is done, step by step — as opposed to factual knowledge of what something is. Skills mostly package the former.
- Context tax
- The fixed token cost a skill's description imposes on every session, whether or not it fires. Multiplied by headcount and session frequency, it stops being trivial.
- Under-triggering
- A model's tendency to skip a skill it should have invoked. The fix is a more specific, slightly pushier description.
- Context poisoning
- Delivering a file containing malicious instructions (e.g. a SKILL.md) through a normal distribution channel so the agent executes it as legitimate guidance.
- pp (percentage points)
- The absolute difference between two percentages. 33.9% → 50.5% is +16.6pp, not +16.6%.