Agent Skills 完全指南 — 从公开规范到SKILL.md实践设计，再到skills.sh安全

在使用AI代理时，’技能’、’Agent Skills’、’skills.sh’、’MCP’和’系统提示’等术语会同时出现。尽管名称相似，看起来像是来自同一机构或产品，但它们各自的角色是不同的。

首先需要纠正的一点是，Agent Skills并非机构名称。它是一种公开文件格式的名称，用于将特定业务流程、参考资料和执行代码作为软件包添加到AI代理中。Anthropic最初开发并发布了它，目前不仅Claude，ChatGPT和Codex等多种代理产品都支持这种格式。

然而，它并非ISO、IEC、IETF、W3C等标准化机构制定的国际标准。确切地说，它更接近于被多个实现采纳的公开互操作格式或开放规范。

本文将区分并解释以下三点：

Agent Skills公开规范实际定义的内容
稳定构建安全和审计任务技能的实践设计
搜索和安装公开技能的skills.sh与供应链安全

Agent Skills是谁创建的？

Agent Skills官方文档解释说，这种格式最初由Anthropic开发，并在作为开放格式发布后被多个代理产品采纳。通用规范和文档正在agentskills/agentskills仓库中公开开发。

关系可以简化如下：

Anthropic
└── Agent Skills 형식 최초 개발·공개

Agent Skills 공개 사양
├── agentskills.io 문서
├── agentskills/agentskills 사양 저장소
├── Claude의 스킬 구현
├── ChatGPT·Codex의 스킬 구현
└── 기타 호환 에이전트 구현

Anthropic的skills仓库目前主要关注Claude中使用的实现和示例。该仓库本身也明确指出，有关通用标准的信息应查阅agentskills.io。

OpenAI也并非重新创建了独有的同名规范。OpenAI的技能文档明确指出，ChatGPT和Codex的技能是基于公开的Agent Skills规范的。

因此，以下陈述最为准确：

Agent Skills是Anthropic最初开发并发布的AI代理轻量级技能包格式，目前是多个产品采纳的公开互操作规范。

图：Agent Skills规范与各产品实现、skills.sh角色关系 · 基于Agent Skills Overview、OpenAI Build skills、skills.sh Documentation重构

Agent Skills规范定义的最小结构

技能的核心是一个目录及其内部的SKILL.md文件。

aws-iam-policy-review/
├── SKILL.md              # 必需
├── scripts/              # 可选: 执行代码
├── references/           # 可选: 策略·文档·知识
├── assets/               # 可选: 模板·示例
└── 그 밖의 파일          # 可根据需要添加

SKILL.md由YAML Frontmatter和Markdown正文组成。

---
name: aws-iam-policy-review
description: >
  Review AWS IAM policies for excessive permissions, privilege escalation,
  unsafe trust relationships, and missing conditions.
  Use when a user asks to assess or harden an IAM policy.
---

# AWS IAM 策略审查

1. 정책 문법을 확인한다.
2. Action, Resource, Principal, Condition을 분석한다.
3. 권한 상승 가능성을 분석한다.
4. 근거와 최소 권한 수정안을 제안한다.

Agent Skills官方规范实际上只要求两个Frontmatter字段：name和description。



—	—	—	—
`name`	必需	1~64字符，英文小写字母·数字·连字符，与目录名一致	技能识别
`description`	必需	1~1,024字符	说明其功能及使用时机
`license`	可选	许可证名称或文件引用	分发·使用条件
`compatibility`	可选	1~500字符	执行环境、软件包、网络要求
`metadata`	可选	字符串键值对	作者·版本等扩展信息
`allowed-tools`	可选	各实现体的支持差异	预先允许的工具、实验性功能

不要假设所有代理都会以相同方式解释allowed-tools，仅仅因为它在规范中。此字段是实验性的，需要单独检查各实现体的支持和权限模型。

代理如何发现技能？

Agent Skills的一个重要设计原则是渐进式披露（Progressive Disclosure）。

1. Discovery
   모든 스킬의 name과 description만 확인

2. Activation
   사용자 요청과 맞는 스킬의 SKILL.md 전체 로드

3. Execution
   필요한 scripts·references·assets만 추가 사용

如果代理从一开始就读取所有技能的冗长正文，上下文会迅速耗尽。因此，description不应仅仅是简单的介绍，而应像技能路由规则一样编写。

好的描述应包含以下三点：

무엇을 수행하는가
+ 언제 호출해야 하는가
+ 비슷해 보이지만 호출하지 말아야 할 경우

例如，“帮助AWS”不如“审查IAM策略中过度的权限和权限提升，不用于一般的AWS成本·网络审查”更准确地触发。

官方规范建议将整个SKILL.md保持在500行或约5,000个token以下，并将长篇资料分离到单独的文件中。这并非强制限制，而是为了提高上下文效率的建议值。

必须区分官方规范和实践设计

以下项目并非Agent Skills的官方必需Frontmatter：

역할
목표
입력 조건
허용 범위
금지 범위
판단 기준
출력 형식
오류 처리
완료 기준
테스트 사례

但这并不意味着它们不必要。这些是在安全审查、审计、代码审查等对结果一致性和可复现性要求高的任务中，有用的提示工程和代理设计模式。



—	—	—
区分	Agent Skills 官方规范	实践推荐设计
目的	定义兼容的技能包格式	确保任务结果的一致性和安全性
必需元素	`SKILL.md`、`name`、`description`	目的、工作流、安全边界、输出契约等
正文目录	不强制	根据任务特性进行结构化
测试	非官方必需目录	推荐触发、正常、风险、边界案例
工具权限	部分元数据和实现体策略	明确设计读、写、审批范围

图：官方规范与实践推荐设计的边界 · 基于Agent Skills Specification和Best practices for skill creators重构

安全·审计技能所需的实践结构

对于安全任务技能，可以推荐以下配置：



—	—	—
构成要素	重要度	说明
元数据	必需	名称、触发描述、版本、兼容环境
目的	必需	应产生的最终结果
适用·不适用条件	必需	应调用和应排除的情况
输入契约	推荐	必需输入、可选输入、输入不足时的行为
执行程序	必需	操作顺序和决策流程
判断标准	重要	判断问题·风险等级的依据
安全边界	重要	禁止操作和需要审批的操作
工具使用策略	使用工具时必需	读、写、外部传输范围
输出契约	必需	供人阅读或系统处理的结果结构
错误处理	推荐	处理失败、不确定性、信息不足
验证标准	重要	完成条件和测试方法

目的应以完成状态编写

坏例子：

IAM 정책을 분석한다.

好例子：

제공된 IAM 정책에서 과도한 권한, 권한 상승 경로,
신뢰 정책 오류와 조건문 누락을 식별하고,
각 발견의 근거와 최소 권한 수정안을 제공한다.

即使输入不足也要定义行为

확인 가능한 위험은 먼저 분석한다.
확인할 수 없는 항목은 추정하지 않고 검토 제한 사항으로 표시한다.
SCP와 권한 경계가 없으면 전체 유효 권한을 확정하지 않는다.

安全边界以行动权限编写

읽기 작업                  자동 수행 가능
정책 수정안 생성            자동 수행 가능
실제 정책 변경              사용자 승인 필요
정책 삭제·권한 확대          기본 실행 금지
인증정보 원문 재출력          금지

与其抽象地写“安全行动”，不如具体说明哪些操作是自动执行的，哪些操作需要审批，哪些操作不执行。

固定输出契约和错误处理

人工可读的报告可以按以下方式构成：

1. 검토 요약
2. 주요 발견 사항 표
3. 발견별 근거와 영향
4. 권한 상승 경로
5. 최소 권한 수정안
6. 검토 제한 사항
7. 추가로 필요한 정보

如果需要自动后处理，使用JSON Schema固定严重性、置信度、位置、证据和建议的类型会更稳定。

目录按角色划分较好

与其将所有策略和示例都集中在一个长技能中，不如按以下方式分离：

aws-iam-policy-review/
├── SKILL.md
├── references/
│   ├── severity-criteria.md
│   ├── privilege-escalation-patterns.md
│   ├── sensitive-actions.md
│   ├── condition-key-guidance.md
│   └── output-schema.json
├── scripts/
│   ├── validate_policy.py
│   └── normalize_statements.py
├── assets/
│   ├── report-template.md
│   └── sample-policy.json
└── tests/
    ├── trigger-evals.json
    ├── policy-cases/
    └── expected-results/

tests/并非官方规范的必需目录，但可以为了运营质量而添加。将核心工作流放在SKILL.md，长判断表放在references/，确定性验证放在scripts/，输出骨架放在assets/，回归验证放在tests/，这样更易于管理。

系统提示、Agent Skills、MCP有何不同？

这三个要素并非竞争关系，而是不同的层次。



—	—	—	—
区分	系统提示	Agent Skills	MCP
问题	它应该总是如何行动？	它应该如何执行特定任务？	它应该如何与哪些数据·工具连接？
适用范围	所有请求	仅在相关任务中	连接服务器的资源·工具
主要内容	整体原则和最高层边界	领域程序·判断·示例	资源·提示·工具通信
加载	从对话开始	需要时	连接·调用时
脚本·资料	通常不包含	可一同打包	外部系统提供功能

以AWS IAM审查为例，它们结合如下：

시스템 프롬프트
└── 승인 없는 변경 금지, 비밀 보호

Agent Skill
└── 정책 수집 → 정규화 → 위험 판단 → 수정안 작성 절차

MCP Tools
├── IAM 정책 조회
├── Access Analyzer 결과 조회
├── 공식 문서 검색
└── 보고서 저장

技能不是连接工具的协议，MCP也不定义安全审查程序本身。

skills.sh是什么？

skills.sh并非Agent Skills规范本身。它是由Vercel运营的公开技能搜索目录，并与vercel-labs/skills发布的skills CLI连接。

一句话区分如下：

Agent Skills
= 스킬을 어떤 파일 형식으로 작성할 것인가

skills.sh
= 작성된 스킬을 어디서 찾고 여러 에이전트에 어떻게 설치할 것인가



—	—	—
区分	Agent Skills	skills.sh·skills CLI
性质	编写格式·公开规范	搜索目录·安装工具
核心	`SKILL.md`结构	`npx skills`命令
角色	技能定义·加载	发现·安装·更新·排名
开始·运营	由Anthropic开始，公开开发	Vercel
存储位置	各Git仓库和本地目录	查找原始仓库并放置到代理路径
国际标准机构	否	否
比喻	软件包规范	搜索目录和通用安装管理器

skills CLI如何使用？

仅查看公开仓库的技能列表：

npx skills add vercel-labs/agent-skills --list

在项目范围内安装特定技能：

npx skills add vercel-labs/agent-skills 
  --skill web-design-guidelines

仅安装到Codex：

npx skills add vercel-labs/agent-skills 
  --skill web-design-guidelines 
  --agent codex

不安装而临时使用：

npx skills use 
  vercel-labs/agent-skills@web-design-guidelines 
  --agent claude-code

管理命令：

npx skills list
npx skills update
npx skills remove <skill-name>
npx skills init aws-iam-policy-review

CLI目前支持Claude Code、Codex、Cursor、GitHub Copilot、Gemini CLI等70多个代理安装路径。默认安装范围是当前项目，使用-g或--global则会全局安装到用户。安装方式可以选择指向公共副本的符号链接或单独文件复制。

skills.sh排名和Official的含义

根据skills.sh文档，排名基于CLI收集的匿名安装统计数据。因此，排名仅显示受欢迎程度和可发现性，并非准确性、安全性或维护质量的评分。

如果不想使用遥测，可以使用CLI提示的环境变量：

DISABLE_TELEMETRY=1 npx skills add owner/repo

DONOTTRACK也作为替代设置被提示。

Official列表是查看由相应产品或技术创建组织提供的技能的功能。但以下三句话是不同的：

공식 제작자가 배포했다                 가능
Vercel이 내용 전체를 보증한다           아님
보안상 무조건 안전하고 최신이다          보장되지 않음

优先选择官方创建者的技能是一个好的开始，但在安装前必须检查当前的提交、脚本和权限要求。

公开技能为何成为供应链风险？

技能可能不仅仅是简单的说明文档。

SKILL.md
├── 명령 실행 절차
├── 파일 변경 지침
├── 외부 도구 사용 규칙
└── 기존 지침과 충돌할 수 있는 문장

scripts/
├── Python·Bash·JavaScript 실행 코드
├── 의존성 설치
└── 외부 통신

技能本身不会创建新的操作系统权限。然而，它可能诱导代理以特定方式使用其已有的文件、Shell、网络、仓库和云权限。

恶意或粗心的技能可能导致以下行为：

读取敏感文件和环境变量
将数据传输到外部服务器
修改仓库代码和设置
安装软件包或可执行文件
更改和部署云策略
尝试绕过安全检查或高级别指令

skills.sh安全审计页面汇总了Gen Agent Trust Hub、Socket、Snyk等工具的结果。然而，各工具的判断标准不同，skills.sh文档也明确指出无法保证所有技能的质量和安全性，因此建议在安装前自行审查。

企业应如何引入？

与其立即全局安装公开技能，不如构建一个经过批准的供应链更为安全。

图：公开技能的企业引入审查和部署流程 · 基于skills.sh Documentation和vercel-labs/skills README重构

공개 skills.sh·Git 저장소
        ↓
출처·라이선스 확인
        ↓
SKILL.md와 scripts 전체 검토
        ↓
외부 URL·의존성·요구 권한 분석
        ↓
검토된 커밋 고정
        ↓
사내 승인 저장소
        ↓
프로젝트 범위 설치
        ↓
샌드박스·최소 권한·사람 승인
        ↓
업데이트 전 diff와 회귀 테스트


控制项	推荐方案

—	—
来源	优先选择官方组织或已验证的仓库
版本	固定到已审查的提交，而非分支最新版本
安装范围	优先选择项目级别而非全局
代码审查	不仅检查`SKILL.md`，还要检查整个`scripts/`
外部通信	审查域名、传输数据和依赖安装
执行权限	最小化Shell、网络、云写入权限
秘密信息	从代理环境中移除不必要的凭证
高风险操作	对策略更改·部署·删除应用人工审批
更新	差异审查和重新验证，而非自动跟踪
部署	运营内部镜像或已批准的Git仓库

特别是，以下命令很方便，但不应在未经审查的仓库中使用：

npx skills add unknown-owner/unknown-repo --all -g -y

这是因为它是一种未经确认就全局安装所有技能的组合。更安全的顺序是：首先使用--list查看技能，然后审查原始提交的SKILL.md、scripts/、外部URL和许可证，最后只在项目范围内安装所需的技能。

与npm相同吗？

有相似之处，但并非完全相同。



—	—	—
区分	npm	skills.sh
原始分发	将软件包发布到注册表	主要发现并连接Git仓库中的技能
安装目标	JavaScript软件包和依赖项	指令·脚本·参考资料·资产
安装位置	`node_modules`	代理特定的技能目录
主要管理	软件包版本·依赖项	代理特定的部署·发现·安装统计
执行风险	安装·运行时代码	代理遵循的指令和执行代码

因此，与其将skills.sh简单地断定为“Agent Skills的npm”，不如将其描述为一个结合了搜索目录和为多个代理提供通用安装管理器的服务更为准确。

最终总结

Agent Skills、skills.sh、系统提示和MCP的角色可以一次性总结如下：

Agent Skills
= 업무 절차를 패키징하는 공개 파일 형식

SKILL.md 실무 설계
= 그 형식 안에 목적·절차·판단·안전·출력 기준을 채우는 방법

skills.sh
= 공개 스킬을 검색하고 여러 에이전트에 설치하는 디렉터리·CLI

시스템 프롬프트
= 모든 요청에 적용되는 상위 행동 원칙

MCP
= 외부 데이터와 도구를 연결하는 통신 프로토콜

Agent Skills官方强制的最小元素很少。但实际的运营质量取决于SKILL.md中的工作流、判断标准、安全边界、错误处理和测试。

skills.sh的搜索排名或Official标记是帮助发现的信号，而非安全保证书。应像审查代码供应链一样审查公开技能，并结合固定版本、项目单位安装、最小权限和人工审批，才能安全地利用它们。

Agent Skills不是机构或国际标准，而是一种公开的技能包格式，skills.sh是寻找和安装使用该格式的技能的生态系统。格式的兼容性和运营的安全性是两个独立的问题。