AI Agent技能上架被拒的元凶：权限声明不匹配

一个被拒两次的AI Agent技能

开发者向技能市场提交了五个AI Agent技能，四个在几分钟内就上线了，唯独一个被连续拒绝了两次——而且原因和技能本身的质量毫无关系。

这个技能通过只读的JSON-RPC调用获取实时数据，功能正常，也带了测试。但审核方的拒绝理由写着：「该技能声明的权限不足以支撑其描述的功能。它声称要与区块链RPC交互，但没有声明任何网络工具或主机。」

换句话说，市场的安全审查机制会自动比对 SKILL.md中描述的能力 和 权限声明中列出的工具/主机。文档里一旦出现fetch、HTTP、API、RPC这些词，而权限声明里没有网络工具——直接拒绝，每次都一样。

这类问题正在成为AI Agent技能生态的一个典型痛点。随着Agent应用加速落地，技能市场上架的自动化审核会越来越严格，而权限声明恰恰是开发者最容易忽视的环节。

为什么会发生这种不匹配

技能市场会从上传的包中自动检测权限。但自动检测本质上是启发式规则，而启发式规则恰好在最需要精准的地方出问题——那些以只读、低风险方式使用网络的技能。

失败模式是不对称的：

• 少声明（技能用了网络，声明里没写）→ 直接拒绝，因为审核方无法验证什么数据会离开用户机器
• 多声明（声明了一个技能从不使用的工具）→ 没问题，只要在权限备注里解释为什么防御性声明即可

这个不对称性意味着：拿不准的时候，多声明，然后在备注字段里解释清楚。可惜很多开发者默认走的是「最小权限」思路，认为少声明更安全，结果反而卡在审核环节。

更深层的问题在于，安全审查逻辑和开发者的直觉存在系统性偏差。审核方关心的核心问题是「什么数据会离开这台机器」，而开发者关注的是「技能能不能跑通」。两个视角之间的信息缺口，就是权限声明需要填补的地方。

SKILL.md 是 AI Agent 技能包中的核心描述文件，通常采用带 Frontmatter 的 Markdown 格式。Frontmatter 部分一般只包含 name 和 description 两个字段，用于向 Agent 声明「这个技能叫什么」以及「什么时候应该加载它」；正文则描述技能的能力、工作流程、输入输出示例和注意事项。技能市场的自动审核系统会解析 SKILL.md 的正文语义，并与权限声明中列出的工具与主机做比对：正文里出现了网络相关词汇却未声明 network，就会被判定为「声明的权限不足以支撑描述的功能」。因此 SKILL.md 不仅是写给 Agent 和用户看的说明书，也是审核系统判断权限是否匹配的主要依据。

五分钟修复流程

开发者在多次被拒后总结出了一套提交前自检步骤：

关键词扫描自己的SKILL.md

搜索这些词：fetch、HTTP、API、RPC、webhook、endpoint、curl。只要它们出现在描述运行时行为的地方，就必须声明 network 工具。这个动作只需要几分钟，但能避免绝大多数自动拒绝。

列出所有运行时主机

RPC端点、API基地址、支付服务商——全部列出来。文档链接不算，只有运行时实际访问的目标才算。这个区分很关键，因为审核方追踪的是数据流向，而不是你引用了哪些参考文档。

像写给审计员一样写备注字段

一两句话说明：网络访问是用来做什么的，以及不是用来做什么的（不用密钥、不写数据、不发交易）。这就是审核员「猜测」和「确认」之间的差别。一句清晰的备注，可以把手动审核变成自动通过。

反方向也要检查

如果技能读取文件，声明 file_read。如果运行脚本，声明 terminal。任一方向的不匹配都会触发人工审核——而人工审核意味着更长的等待时间和更多的不确定性。

重新提交也有坑：快照机制

修复权限声明后，开发者通过后台面板重新提交，几分钟后收到了一模一样的拒绝信息。原因在于：安全筛查针对的是提交时刻的快照。事后更新元数据（哪怕通过平台自己的API）不会创建新快照。

正确的重新提交流程是：

1. 打开现有列表的编辑表单（提交全新表单会因名称重复而被拒）
2. 使用「替换技能ZIP——需要重新审批」选项，再次上传包，这会创建新快照
3. 通过最终审核对话框确认，提交快照进入审核

这个快照机制对于不熟悉平台内部流程的开发者来说是一个隐形陷阱。它意味着「改了就算数」的直觉在这里不成立，必须触发一次完整的重新上传才能让审核系统看到变化。

快照机制指平台在开发者提交技能包时，会对当时的 SKILL.md、权限声明和 ZIP 内容做一次不可变的记录，后续审核均针对这份快照进行。这意味着通过后台面板或平台 API 修改元数据，并不会让审核系统看到新内容，因为那只是在修改列表的展示信息，而非重新生成快照。只有通过「替换技能 ZIP——需要重新审批」选项重新上传包，才会创建新快照并触发审核。这一设计的目的在于保证审核对象与实际上架内容一致，避免开发者在审核通过后偷偷修改技能行为。理解这一点，就能明白为什么「改了权限声明却收到一模一样的拒绝信息」——审核的始终是旧快照。

提交前自检清单

开发者现在每次提交前都会跑一遍这份清单：

• 权限声明覆盖文档中每一个能力关键词
• 所有运行时主机已声明，纯文档域名已排除
• 权限备注解释了「为什么」和「不做什么」
• 描述的第一句话回答了「Agent什么时候应该加载这个技能」
• Frontmatter只包含 name 和 description，值内不含Markdown
• 正文结构完整：何时使用 → 做什么 → 怎么工作 → 示例输出 → 注意事项
• 无硬编码密钥；破坏性操作显式选择加入
• 定价处于该品类的合理区间

这份清单本身也被打包成了一个技能——Agent Skill Publish Gate，一个7道门的静态审计工具，可以在提交到任何平台之前对SKILL.md进行预检。

Frontmatter 是 Markdown 文件开头由 --- 包裹的元数据区块，在 SKILL.md 中通常只允许 name 和 description 两个字段。审核系统对 Frontmatter 有较严格的格式要求：值内部不能包含 Markdown 语法，否则可能解析失败或被判定为格式不合规。此外，description 的第一句话需要回答「Agent 什么时候应该加载这个技能」，因为这直接影响 Agent 在运行时能否正确路由到该技能。正文结构则建议遵循「何时使用 → 做什么 → 怎么工作 → 示例输出 → 注意事项」的顺序，让审核方和用户都能快速判断技能的能力边界与安全属性。

更大的启示

对于今年在Agent工具链上做交付的开发者来说，这次经历指向一个更本质的认知：能跑的技能，不等于能上架的技能。

审核方只能批准他们能验证的东西，而验证从一份诚实、完整的权限声明开始。与其把权限声明当成一道行政手续，不如把它理解为和审核方之间的通信协议——写清楚了，大家都省事。

技能市场的自动化审核只会越来越成熟。今天因为权限声明不匹配被拒，明天可能因为更细粒度的合规要求被卡。提前建立一套提交前自检流程，比事后反复排查要高效得多。

带上凭据，而不是承诺。

背景补充

最小权限原则（Principle of Least Privilege）是软件安全中的经典实践：一个程序只应申请完成其功能所必需的最小权限，以缩小攻击面。但在技能市场的自动审核场景下，这条原则会与审核逻辑冲突。审核方首要关心的是「什么数据会离开用户机器」，而非「技能能否跑通」；如果技能以只读方式访问 RPC 却未声明网络权限，审核方无法验证数据流向，只能直接拒绝。相反，多声明一个实际未使用的工具通常不会导致拒绝，只要在备注中说明这是防御性声明。因此在技能市场上架这一特定场景中，开发者需要把「最小权限」暂时调整为「可验证的完整声明」。