# https://github.com/heilcheng/awesome-agent-skills 项目说明书

生成时间：2026-05-11 16:27:26 UTC

## 目录

- [项目介绍](#page-project-intro)
- [项目结构](#page-project-structure)
- [什么是Agent Skills](#page-what-is-agent-skill)
- [支持的AI代理](#page-compatible-agents)
- [技能质量标准](#page-skill-quality-standards)
- [快速开始](#page-quick-start)
- [使用技能](#page-using-skills)
- [创建技能](#page-creating-skills)
- [官方技能目录分类](#page-official-skill-categories)
- [网站架构](#page-website-architecture)

<a id='page-project-intro'></a>

## 项目介绍

### 相关页面

相关主题：[项目结构](#page-project-structure), [什么是Agent Skills](#page-what-is-agent-skill)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/README.md)
- [README.ko.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/README.ko.md)
- [README.zh-CN.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/README.zh-CN.md)
- [website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)
- [website/package.json](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/package.json)
- [website/src/components/WikiSidebar.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/WikiSidebar.tsx)
- [website/src/components/sections/Tutorials.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/Tutorials.tsx)

</details>

# 项目介绍

## 项目概述

awesome-agent-skills 是一个专注于 AI Agent Skills（智能体技能）的开源精选列表项目，旨在成为 AI Agent 技能领域最全面的资源集合 资料来源：[README.md:1]()[README.ko.md:1]()。

该项目由 @heilcheng 创建并维护，聚合了来自 Anthropic、OpenAI、GitHub 等主要 AI 平台的技能资源，为开发者提供一站式的技能发现、学习和应用平台 资料来源：[website/src/components/WikiSidebar.tsx:45-50]()。

## 核心价值主张

本项目围绕三大核心用户群体设计其价值主张：

| 用户群体 | 价值主张 | 使用场景 |
|---------|---------|---------|
| 初学者 | 零门槛使用技能 | 直接复制 GitHub URL 粘贴到 AI 对话即可 |
| 团队与企业 | 组织知识封装 | 将操作手册、风格指南、领域流程版本化管理 |
| 技能开发者 | 一次构建，多端部署 | 一个文件，零基础设施，GitHub 即分享平台 |

资料来源：[website/index.html:85-100]()

## 技术架构

### 项目结构

```
awesome-agent-skills/
├── README.md                    # 项目主文档
├── README.zh-CN.md              # 中文文档
├── README.ko.md                 # 韩文文档
├── skills/                      # 技能列表目录
│   ├── development/             # 开发类技能
│   ├── data/                    # 数据处理类技能
│   ├── automation/              # 自动化类技能
│   └── security/                # 安全类技能
└── website/                     # 文档网站
    ├── src/
    │   ├── components/          # React 组件
    │   │   ├── sections/        # 页面区块
    │   │   └── WikiSidebar.tsx  # 维基导航侧边栏
    │   └── pages/               # 页面文件
    └── public/                  # 静态资源
```

资料来源：[website/package.json]() [website/src/components/WikiSidebar.tsx:1-60]()

### 前端技术栈

网站采用现代前端技术栈构建：

| 技术 | 版本/用途 | 说明 |
|-----|----------|------|
| Next.js | 14+ | React 框架，提供 SSR 和路由 |
| TypeScript | 类型安全 | 主要开发语言 |
| Tailwind CSS | 样式框架 | 响应式样式系统 |
| Lucide React | 图标库 | UI 图标组件 |
| Framer Motion | 动画库 | 页面过渡和交互动画 |

资料来源：[website/package.json]() [website/src/components/sections/Tutorials.tsx:1-30]()

### Agent Skills 协议

Agent Skills 是一种开放标准协议，最初由 Anthropic 开发，现已被 30+ 款 Agent 产品采用：

```mermaid
graph LR
    A[SKILL.md 文件] --> B[元数据 Frontmatter]
    A --> C[指令内容 Markdown]
    B --> D[name 必填]
    B --> E[description 必填]
    B --> F[license 可选]
    B --> G[compatibility 可选]
    B --> H[metadata 可选]
    B --> I[allowed-tools 可选]
    C --> J[When to use]
    C --> K[Instructions]
    C --> L[Gotchas]
    C --> M[Examples]
    C --> N[Validation]
```

资料来源：[website/index.html:150-180]()

## 技能加载机制

### 渐进式加载流程

Agent Skills 采用"渐进式披露"（Progressive Disclosure）设计理念，遵循四阶段加载模型：

```mermaid
graph TD
    A[启动时] --> B[阶段1: 发现 Discovery]
    A --> A1[仅加载 name 和 description<br/>~50-100 tokens/skill]
    
    B --> C{用户任务匹配?}
    C -->|是| D[阶段2: 激活 Activation]
    C -->|否| E[保持轻量]
    
    D --> F[加载完整 SKILL.md]
    F --> G[指令、示例、脚本]
    
    D --> H{需要脚本?}
    H -->|是| I[阶段3: 脚本执行]
    H -->|否| J[直接执行指令]
    
    I --> K[阶段4: 验证 Validation]
    J --> K
```

资料来源：[website/index.html:220-250]()

### 技能存储位置

技能文件支持多种存储路径，兼容不同 Agent 客户端：

| 路径 | 用途 | 典型应用 |
|-----|------|---------|
| `~/.claude/skills/` | 用户级技能 | Claude Code / Claude.ai |
| `~/.agents/skills/` | 全局技能 | 通用 Agent 客户端 |
| `.claude/skills/` | 项目级技能 | 项目专属配置 |
| `.github/skills/` | GitHub 存储 | GitHub 原生集成 |

资料来源：[website/index.html:30-35]() [website/src/components/sections/UsingSkills.tsx:40-50]()

## 功能特性

### 技能分类体系

项目按照技能功能进行系统化分类：

- **development** — 开发类技能（代码审查、重构、测试生成等）
- **data** — 数据处理类技能（数据分析、转换、ETL 等）
- **automation** — 自动化类技能（CI/CD、部署、监控等）
- **security** — 安全类技能（代码扫描、依赖审计等）

资料来源：[website/src/components/sections/FindingSkills.tsx:1-20]()

### 技能质量标准

每个技能遵循统一的质量规范：

| 维度 | 要求 | 说明 |
|-----|------|------|
| **结构化指令** | 清晰的步骤分解 | 避免模糊描述，精确指导 |
| **触发条件** | 明确的激活条件 | 让 Agent 准确判断何时使用 |
| **示例覆盖** | 丰富的输入输出示例 | 减少理解歧义 |
| **验证机制** | 内置检查流程 | 自我验证输出正确性 |
| **错误处理** | 预判常见问题 | Gotchas 章节记录坑点 |

资料来源：[website/src/components/sections/QualityStandards.tsx:1-30]()

### 命令行工具支持

通过 `npx skills` CLI 可快速管理技能：

| 命令 | 功能 |
|-----|------|
| `npx skills find [query]` | 搜索相关技能 |
| `npx skills add <owner/repo>` | 添加技能（支持 GitHub 简写/完整 URL/本地路径） |
| `npx skills list` | 列出已安装技能 |
| `npx skills check` | 检查更新 |
| `npx skills update` | 升级所有技能 |
| `npx skills remove [skill-name]` | 移除技能 |

资料来源：[README.ko.md:15-25]()

## 兼容的 Agent 平台

项目支持的 Agent 产品矩阵：

| Agent | 文档链接 |
|-------|---------|
| Claude Code | code.claude.com/docs/en/skills |
| Claude.ai | support.claude.com/articles/12512180 |
| Codex (OpenAI) | developers.openai.com/codex |
| Cursor | cursor.com/docs |
| Copilot | github.com/features/copilot |
| Gemini CLI | developers.google.com/gemini-code-assistant |

资料来源：[README.ko.md:30-40]()

## 快速入门

### 使用现有技能

```mermaid
graph LR
    A[浏览 awesome-agent-skills] --> B[找到目标技能]
    B --> C[复制 GitHub URL]
    C --> D{客户端类型}
    D -->|Claude Code| E[/skills add <url>]
    D -->|Claude.ai| F[粘贴原始 URL]
    D -->|其他 CLI| G[npx skills add]
    E --> H[用自然语言请求任务]
    F --> H
    G --> H
```

### 开发新技能

创建新技能的推荐步骤：

1. 创建以技能命名的文件夹
2. 在文件夹内创建 `SKILL.md` 文件
3. 编写 YAML frontmatter（name 和 description 必填）
4. 在 Markdown 正文编写结构化指令
5. （可选）在 `scripts/` 子目录添加可执行脚本

资料来源：[website/index.html:40-70]()

## 国际化支持

项目文档支持多语言版本：

| 语言 | 文件 | 路径 |
|-----|------|------|
| 英语 | README.md | 根目录 |
| 中文 | README.zh-CN.md | 根目录 |
| 韩语 | README.ko.md | 根目录 |

资料来源：[README.zh-CN.md:1]() [README.ko.md:1]()

## 相关资源

| 资源 | 链接 |
|-----|------|
| 官方规范 | agentskills.io/specification |
| CLI 工具 | vercel-labs/skills |
| 项目网站 | agent-skill.co |
| GitHub 仓库 | github.com/heilcheng/awesome-agent-skills |

资料来源：[website/index.html:280-300]() [website/src/components/WikiSidebar.tsx:40-45]()

---

<a id='page-project-structure'></a>

## 项目结构

### 相关页面

相关主题：[项目介绍](#page-project-intro), [网站架构](#page-website-architecture)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)
- [website/src/components/sections/SkillDirectory.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/SkillDirectory.tsx)
- [website/src/components/sections/QualityStandards.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/QualityStandards.tsx)
- [website/src/components/sections/UsingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/UsingSkills.tsx)
- [website/src/components/sections/FindingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/FindingSkills.tsx)
- [website/src/components/Footer.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/Footer.tsx)
- [README.ko.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/README.ko.md)
</details>

# 项目结构

## 概述

awesome-agent-skills 是一个用于收录和管理 AI Agent 技能（Agent Skills）的开源项目仓库。该项目采用现代化的 Web 技术栈构建，为 AI Agent 提供可复用的技能库和文档站点。

## 技术栈概览

| 技术类别 | 具体技术 |
|---------|---------|
| 前端框架 | Next.js (TypeScript) |
| 样式方案 | Tailwind CSS + 自定义 CSS 变量 |
| 动画效果 | Framer Motion |
| 图标库 | Lucide React |
| 部署平台 | Vercel |
| 包管理 | npm/pnpm |

资料来源：[README.ko.md:1-20]()

## 目录结构

```text
awesome-agent-skills/
├── .gitignore              # Git 忽略配置
├── README.md               # 项目主文档
├── README.ko.md            # 韩语文档
├── README.zh.md            # 中文文档
├── vercel.json             # Vercel 部署配置
└── website/                # 主站点目录
    ├── next.config.ts      # Next.js 配置文件
    ├── tsconfig.json       # TypeScript 配置
    ├── package.json        # 依赖管理
    ├── public/             # 静态资源目录
    └── src/
        ├── app/            # Next.js App Router
        │   ├── layout.tsx  # 根布局组件
        │   ├── page.tsx    # 首页组件
        │   └── globals.css # 全局样式
        ├── components/     # React 组件库
        │   ├── sections/   # 页面区块组件
        │   └── Footer.tsx  # 页脚组件
        └── lib/            # 工具函数库
```

资料来源：[website/src/components/sections/SkillDirectory.tsx:1-50]()

## Website 模块架构

### 组件层级结构

```mermaid
graph TD
    A[App Router] --> B[Root Layout]
    B --> C[Page Component]
    C --> D[Section Components]
    
    D --> E[SkillDirectory]
    D --> F[QualityStandards]
    D --> G[UsingSkills]
    D --> H[FindingSkills]
    D --> I[Footer]
    
    E --> J[Framer Motion Animations]
    F --> K[Good/Bad Pattern Cards]
    G --> L[CLI Code Panels]
    H --> M[External Resource Links]
```

### 核心组件说明

#### SkillDirectory 组件

负责技能目录的展示和搜索过滤功能。该组件使用 Framer Motion 实现布局动画，支持按名称和描述进行技能搜索。

```typescript
// 核心数据结构
{ filtered: skill[] }
```

资料来源：[website/src/components/sections/SkillDirectory.tsx:1-80]()

#### QualityStandards 组件

展示技能的 Quality Standards（质量标准），包含好/坏代码模式对比卡片，帮助开发者理解最佳实践。

| 组件元素 | 功能描述 |
|---------|---------|
| Good Pattern | 展示推荐代码模式 |
| Bad Pattern | 展示应避免的代码模式 |
| Pattern Description | 模式说明文字 |

资料来源：[website/src/components/sections/QualityStandards.tsx:1-60]()

#### UsingSkills 组件

提供技能使用指南，包含 CLI 命令示例和复制功能。该组件实现了代码复制交互逻辑。

| 功能模块 | 说明 |
|---------|------|
| CLI 代码面板 | 展示 `npx skills add` 等命令 |
| 复制按钮 | 支持一键复制到剪贴板 |
| 视觉反馈 | 复制成功后显示 Check 图标 |

资料来源：[website/src/components/sections/UsingSkills.tsx:1-70]()

#### FindingSkills 组件

展示如何发现和获取技能的外部资源链接，支持 Marketplace 和 CLI 工具类资源的展示。

```typescript
// 资源类型
type ResourceType = 'marketplace' | 'leaderboard' | 'cli' | 'general'
```

资料来源：[website/src/components/sections/FindingSkills.tsx:1-60]()

#### Footer 组件

页面底部组件，包含版权信息、社交链接和联系方式。

| 链接类型 | URL/功能 |
|---------|---------|
| 官方网站 | agent-skill.co |
| GitHub | 项目仓库 |
| Twitter/X | 开发者账号 |
| 邮箱 | haileycheng@proton.me |

资料来源：[website/src/components/Footer.tsx:1-50]()

## 主题与样式系统

### 暗色模式支持

项目使用 CSS 变量实现暗色/亮色主题切换：

```css
:root {
  --bg: #000;
  --text: rgba(255, 255, 255, 0.95);
  --border: rgba(255, 255, 255, 0.08);
}

[data-theme="light"] {
  /* 亮色模式变量覆盖 */
}
```

### 色彩系统

| 用途 | 颜色变量 |
|-----|---------|
| 主色（蓝色） | `#0a84ff` |
| 辅助色（紫色） | `#bf5af2` |
| 成功色（绿色） | `#30d158` |
| 警告色（橙色） | `#ff9f0a` |

资料来源：[website/index.html:1-100]()

## 技能目录组织

### 目录结构规范

技能按照分类组织，每个技能包含：

```
skill-name/
├── SKILL.md          # 必选：技能定义文件
└── scripts/          # 可选：辅助脚本目录
    ├── script.py     # Python 脚本（PEP 723 格式）
    └── script.sh     # Shell 脚本
```

### SKILL.md 格式规范

每个技能必须包含 YAML frontmatter：

```yaml
---
name: skill-name                    # 必选：技能名称（小写 + 连字符）
description: >-                     # 必选：功能描述
  1-512 字符，用于 Agent 发现和激活
license: Apache-2.0                 # 可选：开源许可证
compatibility: Python 3.11+          # 可选：环境要求
metadata:                          # 可选：元数据
  author: example-org
  version: "1.0"
allowed-tools: Bash Read Write      # 可选：预批准工具列表
---
```

资料来源：[website/index.html:200-300]()

## 构建与部署

### Vercel 部署配置

项目通过 `vercel.json` 配置自动化部署流程：

```json
{
  "buildCommand": "npm run build",
  "outputDirectory": ".next",
  "installCommand": "npm install"
}
```

### Next.js 配置要点

| 配置项 | 说明 |
|-------|------|
| `reactStrictMode` | 启用 React 严格模式 |
| `images` | 图片优化配置 |
| `env` | 环境变量管理 |

资料来源：[website/next.config.ts]()

## 开发工作流

```mermaid
graph LR
    A[代码编写] --> B[TypeScript 检查]
    B --> C[ESLint 检查]
    C --> D[Next.js Build]
    D --> E[Vercel Preview]
    E --> F[合并到 Main]
    F --> G[自动部署生产环境]
```

## 资源链接

| 资源类型 | 链接 |
|---------|------|
| 项目官网 | agent-skill.co |
| GitHub 仓库 | github.com/heilcheng/awesome-agent-skills |
| 官方规范 | agentskills.io/specification |
| CLI 工具 | vercel-labs/skills |

资料来源：[website/src/components/Footer.tsx:1-40]()

## 总结

awesome-agent-skills 项目采用现代化的 Next.js + TypeScript 技术栈，构建了一个用于管理和展示 AI Agent 技能的文档站点。项目的组件化设计使其具有良好的可维护性和扩展性，同时通过 Vercel 平台实现了自动化的 CI/CD 流程。

---

<a id='page-what-is-agent-skill'></a>

## 什么是Agent Skills

### 相关页面

相关主题：[支持的AI代理](#page-compatible-agents), [快速开始](#page-quick-start)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)
- [website/src/components/sections/QualityStandards.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/QualityStandards.tsx)
- [website/src/components/sections/UsingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/UsingSkills.tsx)
- [website/src/components/sections/WhatIsIt.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/WhatIsIt.tsx)
- [website/src/components/sections/Contributing.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/Contributing.tsx)
- [website/src/components/Footer.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/Footer.tsx)

</details>

# 什么是Agent Skills

## 概述

Agent Skills 是一个开放的 AI Agent 技能标准，旨在让 AI 助手能够学习和掌握特定任务的执行能力。简单来说，Agent Skill 就是一个纯文本指令文件（称为 `SKILL.md`），它教会 AI 如何完成特定任务。把它想象成一张食谱卡：AI 阅读它，按照步骤执行，就能完成任务。资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)

### 核心特点

Agent Skills 具有以下核心特点，使其区别于传统的提示工程方法：

| 特点 | 描述 |
|------|------|
| **按需加载** | 技能只在需要时加载，AI 保持快速响应 |
| **零基础设施** | 不需要复杂的部署环境，一个文件即可 |
| **版本控制** | 可以像普通项目一样在 GitHub 上共享和管理 |
| **跨平台兼容** | 兼容 30+ 个 AI 开发平台，无需修改即可通用 |
| **纯文本格式** | 使用 Markdown 编写，无需编程基础 |

资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)

## SKILL.md 文件格式规范

### 文件结构

每个 Agent Skill 存放在一个独立的文件夹中，文件夹内必须包含 `SKILL.md` 文件。推荐的标准目录结构如下：

```
skill-name/
├── SKILL.md          # 必需：主要指令文件
└── scripts/          # 可选：辅助脚本目录
    └── example.py
```

### Frontmatter 元数据

每个 `SKILL.md` 文件以 YAML frontmatter 开头，其中 `name` 和 `description` 是必填字段：

```yaml
---
name: pdf-processing
description: Extract and summarize text from PDF documents
---
```

#### name 字段规范

| 规则 | 要求 |
|------|------|
| 字符集 | 仅小写字母、数字和连字符 |
| 长度 | 1-64 个字符 |
| 匹配 | 必须与父目录名称一致 |
| 禁止 | 连续连字符、首尾连字符 |

资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)

### 推荐的正文章节结构

`SKILL.md` 的 Markdown 正文部分没有格式限制，但推荐使用以下标准结构，以便 Agent 更好地理解和执行：

```markdown
## 何时使用此技能
触发条件、适用范围和局限性。

## 指令
逐步操作步骤，要明确具体。

## 注意事项
特定于环境的事实，容易出错的地方。

## 示例
具体的输入 → 输出对。

## 验证
如何验证输出是否正确。
```

资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)

## 工作原理

Agent Skills 采用渐进式披露（Progressive Disclosure）设计模式，在不同阶段加载不同深度的信息：

```mermaid
graph TD
    A[启动 Agent] --> B[轻量级扫描]
    B --> C[加载 name 和 description]
    C --> D{任务匹配?}
    D -->|否| E[不使用技能]
    D -->|是| F[按需加载完整 SKILL.md]
    F --> G[执行技能指令]
    G --> H[运行 scripts/ 中的脚本]
    H --> I[任务完成]
    
    style B fill:#e1f5fe
    style F fill:#fff3e0
```

### 阶段一：发现（Discovery）

在启动时，Agent 仅加载每个可用技能的 `name` 和 `description`，每个技能约 50-100 个 token。此阶段不会加载任何实际指令内容。资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)

### 阶段二：激活（Activation）

当用户的任务与某个技能的描述匹配时，Agent 将完整的 `SKILL.md` 读入上下文。此时加载的内容包括详细的指令、示例和脚本。

### 阶段三：执行（Execution）

Agent 根据技能指令执行任务，必要时可运行 `scripts/` 子目录中的可执行文件。

## 安装与使用

### 三种使用视角

```mermaid
graph LR
    A[新手用户] --> |复制 GitHub URL| B[粘贴到 AI 对话]
    C[团队/企业] --> |捕获组织知识| D[版本控制的技能包]
    E[技能作者] --> |一次构建| F[跨平台部署]
    
    style A fill:#c8e6c9
    style C fill:#bbdefb
    style E fill:#ffe0b2
```

#### 新手用户

1. 浏览技能目录
2. 复制技能的 GitHub URL
3. 将 URL 粘贴到 AI 对话中

#### 团队和企业

将组织知识（如操作手册、风格指南、领域流程）捕获为可移植的版本控制技能包。资料来源：[website/src/components/sections/UsingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/UsingSkills.tsx)

### CLI 安装方式

```bash
# Claude Code
npx skills add anthropics/skills/docx

# 或使用 GitHub 简写格式
npx skills add <owner>/<repo>/<skill-name>
```

### 手动安装路径

对于某些平台，可以直接将技能文件夹放置到指定目录：

| 平台 | 安装路径 |
|------|----------|
| Claude Code | `~/.claude/skills/` |
| 通用 Agent | `.agents/skills/` |
| GitHub Actions | `.github/skills/` |

资料来源：[website/src/components/sections/UsingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/UsingSkills.tsx)

## 兼容平台

Agent Skills 是一个被主要 AI 开发工具采用的开放标准。创建的技能无需修改即可在以下平台使用：

| 平台类别 | 工具列表 |
|----------|----------|
| Anthropic | Claude Code, Claude.ai |
| OpenAI | Codex |
| Microsoft | GitHub Copilot |
| IDE 插件 | Cursor |
| 其他 | 30+ 兼容平台 |

资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)

## 脚本支持

Agent 可以运行 `scripts/` 子目录中的可执行文件。设计脚本时应考虑 Agent 的特性：

```python
#!/usr/bin/env -S uv run
# /// script
# requires-python = ">= 3.11"
# dependencies = ["requests", "rich"]
# ///

import sys, json

# 避免交互式提示
# 使用结构化输出 (JSON/CSV)
# 将错误写入 stderr
# 使用有意义的退出码
print(json.dumps({"result": "ok"}))
```

### 脚本设计原则

| 原则 | 说明 |
|------|------|
| 避免交互 | 不要使用 input() 或交互式提示 |
| 结构化输出 | 使用 JSON 或 CSV 格式 |
| 错误处理 | 将错误信息写入 stderr |
| 明确退出码 | 使用有意义的退出码 |

资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)

## 技能质量标准

### 好的技能 vs 差的技能

#### 优秀技能的编写模式

- 使用清晰的步骤编号
- 提供具体的触发条件
- 包含实际的输入输出示例
- 明确说明验证方法

#### 需要避免的模式

- 模糊不清的指令
- 缺少上下文说明
- 没有错误处理指引
- 缺乏实际案例

资料来源：[website/src/components/sections/QualityStandards.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/QualityStandards.tsx)

## 创建你的第一个技能

创建步骤非常简单：

```mermaid
graph LR
    A[创建文件夹] --> B[命名技能]
    B --> C[创建 SKILL.md]
    C --> D[添加 name 和 description]
    D --> E[编写指令正文]
    E --> F[放置到 skills 目录]
```

1. 创建一个以技能名称命名的文件夹
2. 在文件夹内创建 `SKILL.md` 文件
3. 在文件顶部添加 YAML frontmatter（name 和 description）
4. 在下方用纯英文编写你的指令
5. 将文件夹放置到 `.claude/skills/` 或 `.github/skills/` 目录

资料来源：[website/src/components/sections/Contributing.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/Contributing.tsx)

## 总结

Agent Skills 提供了一种轻量级、标准化的方式来扩展 AI Agent 的能力。通过将任务指令封装为可移植的 `SKILL.md` 文件，用户可以：

- **快速分享**：通过 GitHub URL 一键分享技能
- **版本控制**：像代码一样管理技能版本
- **跨平台使用**：一次创建，多平台通用
- **零门槛创作**：纯文本格式，无需编程基础

这种设计让 AI 助手能够"学会"执行特定任务，同时保持核心的快速响应特性。资料来源：[website/src/components/Footer.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/Footer.tsx)

---

<a id='page-compatible-agents'></a>

## 支持的AI代理

### 相关页面

相关主题：[使用技能](#page-using-skills), [什么是Agent Skills](#page-what-is-agent-skill)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)
- [website/src/components/sections/QualityStandards.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/QualityStandards.tsx)
- [website/src/components/Footer.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/Footer.tsx)
- [website/src/components/sections/WhatIsIt.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/WhatIsIt.tsx)
- [website/src/components/sections/UsingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/UsingSkills.tsx)
- [website/src/components/sections/CreatingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/CreatingSkills.tsx)
</details>

# 支持的AI代理

## 概述

Agent Skill Index 是一个兼容多种 AI 代理系统的技能索引平台，旨在为不同 AI 助手提供统一的技能（Skill）管理规范。该项目定义了标准化的 SKILL.md 格式，使开发者能够创建一次技能，即可在多个支持该规范的 AI 代理上使用。

该平台兼容的主流 AI 代理包括 **Claude**、**Codex**、**Copilot** 以及其他遵循 agentskills.io 规范的代理工具。资料来源：[website/index.html:1-10]()

## 支持的AI代理列表

### 主流支持的代理

| 代理名称 | 平台类型 | 技能加载方式 | 官方文档 |
|---------|---------|------------|---------|
| Claude | Anthropic | /skills add 命令或粘贴 URL | Claude.ai / Claude Code |
| Codex | OpenAI | npx skills add | OpenAI Codex 文档 |
| Copilot | Microsoft | npx skills add | GitHub Copilot 文档 |
| Claude Code | Anthropic CLI | /skills add <github-url> | Claude Code 文档 |

资料来源：[website/index.html:1-10]()

### 代理兼容性说明

所有支持的 AI 代理都需要遵循 agentskills.io 规范来实现技能加载功能。该规范定义了技能文件的结构、YAML 前端定义以及渐进式加载机制。

```mermaid
graph TD
    A[AI 代理启动] --> B[扫描技能目录]
    B --> C{是否匹配用户任务}
    C -->|是| D[加载完整 SKILL.md]
    C -->|否| E[保持轻量模式]
    D --> F[执行技能指令]
    E --> G[等待匹配]
    F --> H[返回结果]
```

资料来源：[website/index.html:180-200]()

## 技能加载机制

### 渐进式披露设计

Agent Skills 采用渐进式披露（Progressive Disclosure）设计理念，在不同阶段加载不同程度的信息：

1. **启动时扫描**：仅加载每个技能的 `name` 和 `description` 字段，约 50-100 token/技能
2. **按需激活**：当用户任务与技能描述匹配时，读取完整的 SKILL.md 内容
3. **指令执行**：根据技能指令和可选脚本完成任务

```mermaid
graph TD
    A[启动] --> B[扫描技能目录<br/>~project/.agents/skills/<br/>~/.agents/skills/<br/>~/.claude/skills/]
    B --> C[加载 name + description]
    C --> D[等待用户任务]
    D --> E{任务匹配检测}
    E -->|匹配 skill description| F[加载完整 SKILL.md]
    E -->|不匹配| D
    F --> G[执行指令与脚本]
    G --> H[验证输出]
    H --> I[返回结果]
```

资料来源：[website/index.html:180-200]()

### 技能目录结构

支持的技能目录位置根据不同 AI 代理有所不同：

| 目录路径 | 适用代理 | 说明 |
|---------|---------|------|
| `.claude/skills/` | Claude Code | 项目级技能目录 |
| `.github/skills/` | GitHub 集成 | 企业级技能目录 |
| `~/.agents/skills/` | 通用 | 用户级技能目录 |
| `.agents/skills/` | 通用 | 本地技能目录 |

资料来源：[website/index.html:180-200]()

## 技能格式规范

### SKILL.md 结构

每个技能由 YAML 前端定义和 Markdown 正文组成：

```yaml
---
name: pdf-processing
description: >
  Extract text and tables from PDF files, fill PDF forms, and merge
  multiple PDFs. Use when working with PDF documents, forms, or when
  the user mentions PDFs, document extraction, or form filling.
license: Apache-2.0
compatibility: Requires Python 3.11+ and uv
metadata:
  author: example-org
  version: "1.0"
allowed-tools: Bash(uv:*) Read Write
---
```

### 前端字段说明

| 字段名 | 类型 | 必填 | 说明 |
|-------|------|-----|------|
| name | string | 是 | 小写字母、数字、连字符，1-64字符 |
| description | string | 是 | 技能描述，激活条件判断依据 |
| license | string | 否 | 技能许可证类型 |
| compatibility | string | 否 | 兼容性要求说明 |
| metadata | object | 否 | 作者、版本等元数据 |
| allowed-tools | string | 否 | 预批准的工具列表（实验性） |

资料来源：[website/index.html:30-80]()

### 推荐正文结构

```markdown
## When to use this skill
触发条件、范围和限制说明。

## Instructions
逐步操作流程，需要明确具体。

## Gotchas
环境特定的事实，不符合预期的行为。

## Examples
具体的输入输出示例。

## Validation
如何验证输出正确性。
```

资料来源：[website/index.html:120-150]()

## 工具与脚本支持

### 脚本目录

技能可包含可选的 `scripts/` 子目录存放可执行文件：

```bash
my-skill/
├── SKILL.md
└── scripts/
    ├── extract.py
    └── ocr.py
```

### 代理友好脚本设计原则

1. **非交互式**：避免交互式提示
2. **结构化输出**：使用 JSON/CSV 而非自由文本
3. **错误处理**：诊断信息输出到 stderr
4. **退出码**：使用有意义的退出代码

```python
#!/usr/bin/env -S uv run
# /// script
# requires-python = ">= 3.11"
# dependencies = ["requests", "rich"]
# ///
import sys, json

# 正确示范
print(json.dumps({"result": "ok"}))  # 数据到 stdout
sys.exit(0)  # 有意义的退出码
```

资料来源：[website/index.html:120-150]()

## 质量标准

### 技能质量要素

| 要素 | 说明 |
|-----|------|
| 明确性 | 指令清晰、无歧义 |
| 可验证性 | 内置验证流程 |
| 隔离性 | 不依赖未声明的环境 |
| 简洁性 | 避免不必要的复杂性 |

### 好的示例 vs 坏的示例

**好的模式**：
```markdown
1. First, verify the input is valid JSON.
2. Then, run `scripts/validate.py` to check schema.
3. If validation fails, stop and report the error.
```

**坏的模式**：
```markdown
1. Do something with the file.
2. Maybe check if it's correct.
3. Continue if it looks okay.
```

资料来源：[website/src/components/sections/QualityStandards.tsx:1-50]()

## 官方规范资源

完整的 SKILL.md 格式规范、目录结构要求、渐进式披露设计以及客户端实现指南可在官方规范页面获取：

| 资源 | 地址 |
|-----|------|
| 官方规范 | agentskills.io/specification |
| GitHub 仓库 | github.com/heilcheng/awesome-agent-skills |
| 作者联系 | LinkedIn @haileyhmt / Email haileycheng@proton.me |

资料来源：[website/index.html:200-250]()

## 快速入门

### 新手使用步骤

1. **找到技能**：浏览技能目录，按类别（开发、数据、自动化、安全等）组织
2. **加载到AI**：复制 GitHub URL，根据不同平台使用对应命令
3. **用自然语言提问**：AI 自动读取技能指令并执行

```bash
# Claude Code
/skills add <github-url>

# Claude.ai
粘贴 raw SKILL.md URL 到聊天窗口
```

### 企业团队使用

捕获组织知识——操作手册、风格指南、领域流程——以可移植的版本控制包形式存储，实现跨团队共享和复用。

资料来源：[website/src/components/sections/WhatIsIt.tsx:1-30]()
[website/src/components/sections/UsingSkills.tsx:1-50]()

---

<a id='page-skill-quality-standards'></a>

## 技能质量标准

### 相关页面

相关主题：[创建技能](#page-creating-skills)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)
- [README.ko.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/README.ko.md)
</details>

# 技能质量标准

## 概述

技能质量标准（Skill Quality Standards）是 awesome-agent-skills 项目为确保 AI Agent 技能（Skills）具备一致性、可复用性和高效性而制定的一系列规范与最佳实践。这些标准涵盖了技能的元数据定义、内容结构、编写原则以及验证方法，旨在帮助技能作者创建高质量、可维护的技能文件。

资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)

## 核心质量维度

技能的 quality 由以下五个核心维度构成：

| 维度 | 编号 | 核心原则 | 关键要求 |
|------|------|----------|----------|
| 作用域设计 | 01 | 设计内聚、适度规模的技能 | 避免过窄（浪费开销）或过宽（失去焦点） |
| 指令编写 | 03 | 添加 Agent 缺乏的内容；跳过 Agent 已知的部分 | 聚焦项目约定、领域特定流程和边缘情况 |
| 控制策略 | 04 | 仅在重要时刻做规定性要求 | 多种方案等效时给予自由；操作脆弱、不可逆或必须按特定顺序时明确严格 |
| 脚本设计 | 05 | 使脚本对 Agent 友好 | 非交互式标志、结构化输出、有意义的退出码 |
| 验证机制 | 06 | 将验证循环构建到指令中 | 检查表、输出模板匹配、计划-验证-执行模式 |

资料来源：[website/index.html:1-150](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)

## SKILL.md 元数据标准

### 必需字段

每个技能必须包含以下 YAML 前端格式（Frontmatter）字段：

```yaml
---
name: pdf-processing          # 必需：技能名称
description: >-                # 必需：技能描述
  1-1024 个字符的描述文本
---
```

| 字段 | 类型 | 限制 | 说明 |
|------|------|------|------|
| `name` | 必需 | 1-64 字符 | 仅使用小写字母、数字和连字符；禁止连续连字符；禁止首尾连字符；必须与父目录名匹配 |
| `description` | 必需 | 1-1024 字符 | Agent 启动时读取的关键字段，用于决定是否激活技能；应描述技能功能和使用场景 |

**name 字段示例：**

```
name: pdf-processing
name: code-review
name: data-analysis
```

**description 字段质量标准：**

| 质量等级 | 示例 |
|----------|------|
| 良好 | "Extracts text and tables from PDF files. Use when working with PDFs, forms, or document extraction." |
| 不佳 | "Helps with PDFs." |

资料来源：[website/index.html:1-100](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)

### 可选字段

| 字段 | 类型 | 限制 | 说明 |
|------|------|------|------|
| `license` | 可选 | 许可证名称或文件名 | 保持技能包自包含 |
| `compatibility` | 可选 | 1-500 字符 | 仅在存在特定环境要求时使用 |
| `metadata` | 可选 | 键值对 | 作者、版本等元数据 |
| `allowed-tools` | 可选·实验性 | 空格分隔的工具列表 | 预批准可运行的工具，减少操作确认提示 |

资料来源：[website/index.html:1-80](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)

## 内容结构标准

### 推荐章节结构

技能的 Markdown 正文部分应包含以下五个核心章节：

```markdown
## When to use this skill
触发条件、适用范围和限制说明。

## Instructions
逐步操作程序。保持明确具体。

## Gotchas
环境特定的事实。违反常规预期的事项。

## Examples
具体的输入→输出示例对。

## Validation
如何验证输出是否正确。
```

资料来源：[website/index.html:1-60](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)

### 最小示例

```yaml
---
name: roll-dice
description: Roll dice using a random number generator. Use when asked to roll a die (d6, d20, etc.).
---

To roll a die, run:
```bash
echo $((RANDOM % <sides> + 1))
```
```

## 规模限制标准

| 指标 | 上限 | 拆分阈值 |
|------|------|----------|
| 代码行数 | 500 行以内 | 超过时拆分为引用文件 |
| Token 数量 | 5,000 token 以内 | 超过时拆分为多个技能 |

> **经验法则：** 超过 500 行或 5,000 token 的技能应拆分为引用文件。

资料来源：[website/index.html:1-50](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)

## 渐进式披露机制

技能采用渐进式披露（Progressive Disclosure）设计，按需加载以保持性能：

```mermaid
graph TD
    A[Agent 启动] --> B[轻量级扫描]
    B --> C[仅加载 name 和 description]
    C --> D{任务匹配?}
    D -->|是| E[加载完整 SKILL.md]
    D -->|否| F[不加载指令]
    E --> G[执行技能指令]
    F --> H[使用通用能力]
```

### 目录扫描位置

Agent 在以下位置扫描技能目录：

| 级别 | 路径 |
|------|------|
| 项目级（共享） | `.agents/skills/` |
| 用户级（个人） | `~/.agents/skills/` |
| Claude Code 专用 | `.claude/skills/` 或 `~/.claude/skills/` |

资料来源：[website/index.html:1-80](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)

## 脚本设计标准

### PEP 723 内联依赖

当技能需要脚本时，推荐使用 Python PEP 723 内联依赖格式：

```python
#!/usr/bin/env -S uv run
# /// script
# requires-python = ">= 3.11"
# dependencies = ["requests", "rich"]
# ///
```

### Agent 友好脚本原则

| 原则 | 具体要求 |
|------|----------|
| 避免交互提示 | Agent 无法响应交互式提示 |
| 结构化输出 | 使用 JSON/CSV 而非自由文本 |
| 错误处理 | 将错误写入 stderr |
| 退出码 | 使用有意义的退出码 |

**推荐模式：**

```mermaid
graph LR
    A[数据] -->|stdout| B[结构化输出]
    C[诊断信息] -->|stderr| D[日志/错误]
    E[执行结果] -->|退出码| F[0=成功, 非0=失败]
```

资料来源：[website/index.html:1-90](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)

## 验证机制标准

### 验证模式

高质量技能应包含内置验证循环：

1. **检查表验证**：多步骤工作流的逐项确认
2. **输出模板匹配**：验证返回结果符合预期格式
3. **计划-验证-执行模式**：破坏性操作的三阶段确认

### 验证示例

> **示例：** "提交前，运行测试并确认全部通过。如果测试失败，修复后重新运行。"

```markdown
## Validation

1. [ ] 步骤一完成
2. [ ] 步骤二完成
3. [ ] 输出格式验证通过
4. [ ] 错误日志为空
```

资料来源：[website/index.html:1-70](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)

## 兼容性标准

### 支持的 Agent 平台

技能作为开放标准，被以下 30+ 平台支持：

| 平台 | 状态 |
|------|------|
| Claude Code | ✅ 官方支持 |
| Claude.ai | ✅ 官方支持 |
| GitHub Copilot | ✅ 官方支持 |
| VS Code | ✅ 官方支持 |
| OpenAI Codex | ✅ 官方支持 |
| Google Antigravity | ✅ 官方支持 |
| Gemini CLI | ✅ 官方支持 |
| Cursor | ✅ 官方支持 |
| Kiro | ✅ 官方支持 |

资料来源：[website/index.html:1-50](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)

## 技能目录结构

```
my-skill/
├── SKILL.md          # 必需：技能定义文件
├── scripts/          # 可选：可执行脚本目录
│   ├── script1.py    # Agent 可调用的脚本
│   └── script2.sh
└── README.md         # 可选：额外文档
```

资料来源：[website/index.html:1-40](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)

## 质量检查清单

创建技能时的自检清单：

- [ ] `name` 字段符合命名规范（小写字母、数字、连字符）
- [ ] `description` 字段包含功能描述和使用场景（1-1024 字符）
- [ ] 包含 `When to use this skill` 章节
- [ ] 包含 `Instructions` 章节
- [ ] 包含 `Gotchas` 章节（环境特定注意事项）
- [ ] 包含 `Examples` 章节
- [ ] 包含 `Validation` 章节
- [ ] 代码行数 ≤ 500 行
- [ ] Token 数量 ≤ 5,000 token
- [ ] 脚本使用非交互式设计
- [ ] 脚本输出结构化数据
- [ ] 脚本使用有意义的退出码

## 与其他技术的对比

| 特性 | Agent Skills | MCP (Model Context Protocol) |
|------|--------------|-------------------------------|
| 核心功能 | 教授 AI **如何**执行任务 | 帮助 AI **访问**资源 |
| 实现方式 | 工作流、最佳实践 | API、数据库、外部工具 |
| 更新难度 | 简单（仅修改指令文件） | 复杂（需要代码修改） |
| 成本 | 低（指令文件） | 高（服务部署） |
| 组合使用 | 可与 MCP 协同 | 可与 Skills 协同 |

资料来源：[website/index.html:1-30](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)

---

<a id='page-quick-start'></a>

## 快速开始

### 相关页面

相关主题：[使用技能](#page-using-skills), [什么是Agent Skills](#page-what-is-agent-skill)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)
- [website/src/components/sections/UsingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/UsingSkills.tsx)
- [website/src/components/sections/CreatingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/CreatingSkills.tsx)
- [website/src/components/sections/QualityStandards.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/QualityStandards.tsx)
- [README.ko.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/README.ko.md)
</details>

# 快速开始

本页面帮助用户快速上手使用 awesome-agent-skills 项目，掌握查找、加载和使用 AI Agent 技能的基础流程。

## 什么是 Agent Skill

Agent Skill 是一个纯文本指令文件（称为 `SKILL.md`），用于教 AI 助手如何完成特定任务。可以将其理解为一张配方卡片：AI 阅读它，按照步骤执行，即可完成任务。技能仅在需要时加载，因此 AI 保持快速响应。

资料来源：[website/index.html:1-50]()

## 三分钟快速上手

以下流程演示了从发现技能到实际使用的完整路径：

```mermaid
graph TD
    A[发现技能] --> B[获取 GitHub URL]
    B --> C[加载到 AI]
    C --> D[用自然语言描述需求]
    D --> E[AI 自动读取技能说明]
    E --> F[执行任务]
```

资料来源：[website/src/components/sections/UsingSkills.tsx:1-50]()

### 步骤一：发现技能

在页面下方的目录中浏览所有技能。技能按类别组织（开发、数据、自动化、安全等），每个卡片直接链接到 GitHub 上的技能。

### 步骤二：加载到 AI

复制技能的 GitHub URL 并添加到 AI 代理中。根据平台不同，命令略有差异：

| 平台 | 命令 |
|-----|------|
| Claude Code | `/skills add <github-url>` |
| Claude.ai | 在对话中粘贴原始 SKILL.md URL |
| Codex (OpenAI) | 参考官方文档 |

资料来源：[README.ko.md:30-45]()

### 步骤三：用自然语言提问

只需告诉 AI 你想要什么——它会自动读取技能说明并开始工作。无需记忆命令，无需配置。

资料来源：[website/index.html:80-100]()

## 使用 npx skills CLI 工具

对于特定技能，可以使用 `npx skills` 命令行工具快速发现、添加和管理技能。

| 命令 | 功能 |
|------|------|
| `npx skills find [query]` | 搜索相关技能 |
| `npx skills add <owner/repo>` | 添加技能（支持 GitHub 简写、完整 URL、本地路径） |
| `npx skills list` | 列出已安装的技能 |
| `npx skills check` | 检查更新 |
| `npx skills update` | 升级所有技能 |
| `npx skills remove [skill-name]` | 移除技能 |

资料来源：[README.ko.md:20-30]()

## 兼容的 AI 代理

| 代理 | 文档链接 |
|-----|---------|
| Claude Code | [code.claude.com/docs/en/skills](https://code.claude.com/docs/en/skills) |
| Claude.ai | [support.claude.com](https://support.claude.com/en/articles/12512180-using-skills-in-claude) |
| Codex (OpenAI) | [developers.openai.com](https://developers.openai.com/codex) |

资料来源：[README.ko.md:48-55]()

## 手动加载技能

如果不想使用 CLI 工具，也可以手动放置技能文件夹：

```bash
# 下载技能后放置到指定目录
cp -r my-downloaded-skill ~/.agents/skills/my-downloaded-skill

# 验证结构：技能必须有 SKILL.md 文件
ls ~/.agents/skills/my-skill/SKILL.md
```

支持的放置路径：

- `~/.claude/skills/`
- `~/.agents/skills/`
- `~/.project/.agents/skills/`
- `.github/skills/`（用于项目级技能）

资料来源：[website/index.html:120-140]()

## 创建你的第一个技能

如果现有技能无法满足需求，可以自行创建：

### 技能目录结构

```
skill-name/
├── SKILL.md        # 必需：技能说明文件
└── scripts/        # 可选：可执行脚本目录
    └── *.py        # 支持 Python、Shell 等
```

### SKILL.md 基本格式

```yaml
---
name: skill-name
description: 技能的简短描述，1-512 字符
---

## When to use this skill
触发条件和使用场景

## Instructions
逐步执行步骤

## Gotchas
特殊注意事项

## Examples
输入输出示例
```

资料来源：[website/src/components/sections/CreatingSkills.tsx:1-40]()

### 创建步骤

1. **创建文件夹**：以技能名称命名（仅限小写字母、数字和连字符）
2. **编写 SKILL.md**：在文件顶部添加 YAML frontmatter，包含 `name` 和 `description`
3. **编写说明**：使用纯英文描述步骤和示例
4. **添加脚本（如需要）**：在 `scripts/` 子目录放置可执行文件

资料来源：[website/index.html:50-70]()

## 技能质量标准

为确保技能有效运行，建议遵循以下结构：

| 章节 | 用途 |
|-----|------|
| `## When to use this skill` | 触发条件、范围和限制 |
| `## Instructions` | 逐步执行过程，明确具体 |
| `## Gotchas` | 环境特定事实，意外情况说明 |
| `## Examples` | 具体的输入输出示例 |
| `## Validation` | 如何验证输出正确性 |

### 良好的指令示例

```markdown
## When to use this skill
当用户需要从 PDF 文件中提取文本和表格时激活

## Instructions
1. 验证输入是有效的 PDF 文件
2. 运行 scripts/extract.py 脚本
3. 验证输出后再返回结果
```

### 应避免的模式

- 模糊的描述，如"做得好一点"
- 缺少具体的执行步骤
- 没有说明错误处理方式

资料来源：[website/src/components/sections/QualityStandards.tsx:1-60]()

## 进阶功能

### allowed-tools 字段

在 frontmatter 中使用 `allowed-tools` 字段预批准工具运行，减少每次操作时的确认提示：

```yaml
---
name: pdf-processing
allowed-tools: Bash(uv:*) Read Write
---
```

资料来源：[website/index.html:150-160]()

### PEP 723 脚本

Python 脚本可使用 PEP 723 内联依赖声明：

```python
#!/usr/bin/env -S uv run
# /// script
# requires-python = ">= 3.11"
# dependencies = ["requests", "rich"]
# ///
import sys, json
```

资料来源：[website/index.html:170-185]()

## 后续步骤

- 探索完整的 [技能目录](#) 找到适合你的技能
- 阅读 [SKILL.md 格式规范](https://agentskills.io/specification) 了解完整规格
- 参考 [贡献指南](https://github.com/heilcheng/awesome-agent-skills/blob/main/CONTRIBUTING.md) 提交你自己的技能

---

<a id='page-using-skills'></a>

## 使用技能

### 相关页面

相关主题：[快速开始](#page-quick-start), [支持的AI代理](#page-compatible-agents)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)
- [website/src/components/sections/UsingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/UsingSkills.tsx)
- [website/src/components/sections/CreatingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/CreatingSkills.tsx)
- [website/src/components/sections/QualityStandards.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/QualityStandards.tsx)
- [website/src/components/Footer.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/Footer.tsx)
</details>

# 使用技能

本文档详细介绍如何在各类 AI Agent 产品中使用 Agent Skills，包括发现、加载、激活的完整流程，以及不同平台的集成方式。

## 什么是 Agent Skills

Agent Skills 是一种可移植的知识包，由包含 `SKILL.md` 文件的文件夹组成。该文件融合了元数据和指令，使 AI Agent 能够按需发现和加载特定技能。Agent Skills 最初由 Anthropic 开发，现已作为开放标准被 30+ Agent 产品采用，包括 Claude、Codex、Cursor、Copilot、Gemini CLI 等。

资料来源：[website/index.html:1-20]()

### 核心特性

| 特性 | 说明 |
|------|------|
| 按需加载 | 仅在需要时加载技能，保持 Agent 响应速度 |
| 零基础设施 | 无需复杂配置，共享在 GitHub 上即可使用 |
| 平台无关 | 兼容所有支持 Skills 标准的 Agent 产品 |
| 版本控制 | 作为 Git 仓库管理，便于追踪变更 |

资料来源：[website/index.html:120-140]()

## 工作原理

### 渐进式披露机制

Agent Skills 采用渐进式披露（Progressive Disclosure）机制，分三个阶段工作：

```mermaid
graph TD
    A[启动 Agent] --> B[发现 Discovery]
    B --> C[激活 Activation]
    C --> D[加载 Loading]
    D --> E[执行任务]
    
    B --> B1[扫描 name + description<br/>~50-100 tokens/技能]
    C --> C1[匹配用户任务]
    D --> D1[读取完整 SKILL.md]
    
    style B fill:#e1f5fe
    style C fill:#f3e5f5
    style D fill:#fff3e0
```

### 三个阶段详解

| 阶段 | 触发时机 | 加载内容 | 位置 |
|------|----------|----------|------|
| **发现** | Agent 启动时 | 仅 `name` 和 `description` | `~/.claude/skills/` |
| **激活** | 任务匹配描述时 | 完整 `SKILL.md` 内容 | 上下文注入 |
| **加载** | 执行相关操作 | `scripts/` 目录中的脚本 | 按需执行 |

资料来源：[website/index.html:280-310]()

## 使用方式

### 方式一：通过 CLI 添加

使用官方命令行工具添加技能，这是最便捷的方式：

```bash
npx skills add anthropics/skills/docx
```

该命令支持以下几种引用格式：

| 格式类型 | 示例 |
|----------|------|
| GitHub 简写 | `anthropics/skills/docx` |
| 完整 URL | `https://github.com/anthropics/skills/docx` |
| 本地相对路径 | `./my-skills/pdf-processing` |

资料来源：[website/src/components/sections/UsingSkills.tsx:1-40]()

### 方式二：手动放置

将技能文件夹直接放置到指定目录，Agent 会自动扫描：

| 平台 | 路径 |
|------|------|
| Claude Code | `.claude/skills/` 或 `.github/skills/` |
| Claude.ai | 粘贴原始 SKILL.md 的 URL |
| 通用 | `~/.agents/skills/` 或 `~/.claude/skills/` |

放置结构示例：

```
.github/skills/skill-name/
├── SKILL.md          # 必需：技能定义文件
└── scripts/          # 可选：可执行脚本目录
    ├── script1.py
    └── script2.sh
```

资料来源：[website/src/components/sections/UsingSkills.tsx:45-60]()

### 方式三：通过 URL 直接引用

在 Claude.ai 等平台，可以直接粘贴原始 `SKILL.md` 文件的 GitHub URL，Agent 会自动读取并应用技能说明。

## 使用流程

### 三步上手指南

```mermaid
graph LR
    A[1. 找到技能] --> B[2. 加载到 AI]
    B --> C[3. 用自然语言提问]
    C --> D[✨ 任务完成]
    
    A --> A1[浏览目录<br/>选择技能]
    B --> B1[复制 GitHub URL<br/>添加到 Agent]
    C --> C1[用自然语言描述需求<br/>Agent 自动读取技能]
    
    style A fill:#e3f2fd
    style B fill:#f3e5f5
    style C fill:#e8f5e9
```

### 步骤详解

#### 步骤一：找到技能

浏览 awesome-agent-skills 目录中的技能列表。技能按类别组织，包括开发、数据、自动化、安全等类别。每个技能卡片都直接链接到 GitHub 上的技能仓库。

#### 步骤二：加载到 AI

根据使用的平台选择合适的加载方式：

- **Claude Code**: 使用 `/skills add <github-url>` 命令
- **Claude.ai**: 直接在聊天窗口粘贴原始 SKILL.md 的 URL
- **其他平台**: 参考各自平台的技能管理文档

#### 步骤三：用自然语言提问

完成上述步骤后，只需用自然语言描述你的需求。Agent 会自动读取技能说明并执行相应操作。无需记忆任何命令或进行额外配置。

资料来源：[website/src/components/sections/UsingSkills.tsx:10-35]()

## 技能结构

### 目录结构规范

```
skill-name/
├── SKILL.md           # 必需：包含 YAML frontmatter + 指令
├── scripts/           # 可选：可执行脚本目录
│   ├── script1.py     # Python 脚本（推荐 PEP 723 格式）
│   └── script2.sh     # Shell 脚本
└── README.md          # 可选：人类可读的说明文档
```

### SKILL.md 文件格式

每个技能的核心是 `SKILL.md` 文件，采用 YAML frontmatter + Markdown 正文的结构：

```yaml
---
name: pdf-processing
description: >
  从 PDF 文件提取文本和表格，填充 PDF 表单，
  合并多个 PDF。当处理 PDF 文档、表单或涉及
  文档提取、表单填充时激活。
license: Apache-2.0
compatibility: Requires Python 3.11+ and uv
metadata:
  author: example-org
  version: "1.0"
allowed-tools: Bash(uv:*) Read Write
---

## 何时使用此技能

激活条件、范围和限制说明。

## 指令

逐步操作步骤，保持清晰明确。

## 注意事项

环境特定的事实，不符合预期的情况。

## 示例

具体的输入 → 输出对。

## 验证

如何验证输出正确性。
```

### Frontmatter 字段说明

| 字段 | 必填 | 说明 |
|------|------|------|
| `name` | 是 | 小写字母 + 连字符，1-64 字符，与父目录名一致 |
| `description` | 是 | 技能描述，说明何时使用此技能 |
| `license` | 否 | 许可证类型 |
| `compatibility` | 否 | 兼容性要求 |
| `metadata` | 否 | 元数据（author、version 等） |
| `allowed-tools` | 否 | 实验性字段，预批准可执行的工具列表 |

资料来源：[website/index.html:30-80]()

## 质量标准

为确保技能的有效性，编写时需遵循以下质量标准：

| 原则 | 说明 |
|------|------|
| **渐进式披露** | 先给概览，再逐步深入细节 |
| **假设最小化** | 明确说明前提条件，减少歧义 |
| **行动导向** | 使用祈使句和动词开头 |
| **适度规定** | 仅在必要时严格规定，其他情况给予自由度 |
| **脚本设计** | 非交互式、结构化输出、有意义的退出码 |
| **验证机制** | 内置验证循环，Agent 自我检查 |

### 好的模式 vs 不好的模式

```mermaid
graph LR
    subgraph 好的模式
    A1[明确的步骤编号] --> A2[可验证的输出]
    A2 --> A3[具体示例]
    end
    
    subgraph 不好的模式
    B1[模糊的描述] --> B2[无验证机制]
    B2 --> B3[缺少上下文]
    end
```

资料来源：[website/src/components/sections/QualityStandards.tsx:1-50]()

## 常见问题

### Q: 什么是 Agent Skill？

Agent Skill 是一个纯文本指令文件（称为 `SKILL.md`），用于教 AI 助手如何完成特定任务。可以将其理解为食谱卡片：AI 读取它，按照步骤执行，然后完成任务。技能仅在需要时加载，因此 AI 保持快速响应。

### Q: 我不是开发者，能使用技能吗？

可以。技能是纯英文指令文件，不是代码。你只需要一个 AI 助手（如 Claude.ai，免费版即可），不需要终端或 GitHub 账户。只需复制技能的 GitHub URL 并粘贴到 AI 聊天中即可。

### Q: 技能免费吗？

技能本身是免费的。但使用某些技能可能需要付费使用底层 API（如使用特定模型）。技能文件本身可以免费复制、使用和修改。

### Q: 如何创建自己的技能？

只需创建一个以技能命名的文件夹，在其中放置 `SKILL.md` 文件，顶部的 frontmatter 包含 `name` 和 `description`，然后在下面的 Markdown 中编写你的指令。将文件夹放在 `.claude/skills/` 或 `.github/skills/` 中即可。

资料来源：[website/index.html:400-450]()

## 获取帮助

| 渠道 | 说明 |
|------|------|
| GitHub Issues | 报告 Bug 或请求新功能 |
| GitHub Discussions | 提问和社区讨论 |
| 官方网站 | [agent-skill.co](https://agent-skill.co) |
| 邮件联系 | haileycheng@proton.me |

资料来源：[website/src/components/Footer.tsx:1-30]()

## 相关资源

- [贡献指南](https://github.com/heilcheng/awesome-agent-skills/blob/main/CONTRIBUTING.md) - 学习如何为项目贡献技能
- [创建技能](CreatingSkills.md) - 了解如何从头创建新技能
- [质量标准](QualityStandards.md) - 掌握编写高质量技能的规范
- [官方教程](https://modelcontextprotocol.io/docs/first-server) - MCP 入门教程

---

<a id='page-creating-skills'></a>

## 创建技能

### 相关页面

相关主题：[技能质量标准](#page-skill-quality-standards), [使用技能](#page-using-skills)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)
- [website/src/components/sections/CreatingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/CreatingSkills.tsx)
- [website/src/components/sections/UsingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/UsingSkills.tsx)
- [website/src/components/sections/QualityStandards.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/QualityStandards.tsx)
- [CONTRIBUTING.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/CONTRIBUTING.md)
</details>

# 创建技能

## 概述

「创建技能」是 awesome-agent-skills 项目中用于指导开发者构建可复用 AI Agent 技能的核心文档模块。该模块详细说明了如何从零开始创建一个符合规范要求的技能（Skill），包括目录结构、文件格式、编写规范以及最佳实践。

技能是一种包含 `SKILL.md` 文件的文件夹，其中融合了元数据和指令，AI Agent 可以按需发现和加载。开发者只需创建一次，即可在支持 Agent Skills 标准的 30+ 个平台上使用，无需修改。

资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)

---

## 技能目录结构

每个技能本质上是一个独立的文件夹，必须遵循统一的目录结构规范。

### 标准目录布局

```
skill-name/
├── SKILL.md          # 必需：技能定义文件
└── scripts/          # 可选：可执行脚本目录
    ├── script1.py
    └── script2.sh
```

资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)

### 目录位置

技能文件夹可放置于以下位置供 Agent 发现：

| 位置 | 说明 |
|------|------|
| `.claude/skills/` | Claude Code 本地技能目录 |
| `.github/skills/` | GitHub 集成技能目录 |
| `~/.claude/skills/` | 用户级全局技能目录 |
| `~/.agents/skills/` | 通用 Agent 技能目录 |

资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)

---

## SKILL.md 文件规范

### 文件结构

`SKILL.md` 采用 YAML 前置数据（Frontmatter）+ Markdown 正文的标准格式：

```markdown
---
name: skill-name
description: 技能描述（1-512字符）
license: Apache-2.0          # 可选
compatibility: Python 3.11+  # 可选
metadata:                   # 可选
  author: example-org
  version: "1.0"
allowed-tools: Bash(git:*) Read Write  # 可选·实验性
---

## 技能正文内容
```

资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)

### 前置数据字段

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `name` | 字符串 | **是** | 小写字母、数字和连字符组成，1-64字符，不能有连续连字符，不能以连字符开头或结尾，必须与父目录名称一致 |
| `description` | 字符串 | **是** | 技能用途描述，1-512字符，用于 Agent 在启动时识别是否需要加载该技能 |
| `license` | 字符串 | 否 | 采用的开源许可证，如 Apache-2.0、MIT |
| `compatibility` | 字符串 | 否 | 环境依赖说明，如 Python 3.11+、Node.js 18+ |
| `metadata` | 对象 | 否 | 扩展元数据，包含 author、version 等信息 |
| `allowed-tools` | 字符串 | 否 | 预批准的可执行工具列表（实验性功能） |

资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)

---

## 编写技能正文

### 推荐正文结构

为了确保 Agent 能清晰理解并执行任务，建议按以下结构组织 Markdown 正文：

```markdown
## When to use this skill
触发条件、适用范围和限制说明。

## Instructions
逐步操作流程，请保持步骤明确且可执行。

## Gotchas
环境特定的事实，容易出错或违背预期的事项。

## Examples
具体的输入→输出示例对。

## Validation
如何验证输出结果是否正确。
```

资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)

### 编写原则

1. **结构化步骤**：使用编号列表，将复杂任务分解为明确的子步骤
2. **具体示例**：提供真实场景下的输入输出示例
3. **错误处理**：说明常见错误及应对方法
4. **验证方式**：定义输出质量的检验标准

资料来源：[website/src/components/sections/QualityStandards.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/QualityStandards.tsx)

---

## 创建技能工作流

### 四步创建流程

```mermaid
graph TD
    A[1. 创建技能文件夹] --> B[2. 编写 SKILL.md]
    B --> C[3. 编写技能指令]
    C --> D[4. 添加脚本可选]
    D --> E[技能创建完成]
```

资料来源：[website/src/components/sections/CreatingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/CreatingSkills.tsx)

### 步骤详解

#### 第一步：创建技能文件夹

在 `.claude/skills/` 或 `.github/skills/` 目录下创建以技能名称命名的文件夹。

```bash
mkdir -p .github/skills/pdf-processing
```

资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)

#### 第二步：编写 SKILL.md

在文件夹内创建 `SKILL.md` 文件，添加 YAML 前置数据：

```yaml
---
name: pdf-processing
description: 从 PDF 文件中提取文本和表格，填充 PDF 表单，合并多个 PDF。
---
```

资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)

#### 第三步：编写技能指令

在 YAML 前置数据下方添加 Markdown 正文，用简洁的英文描述操作步骤：

```markdown
## When to use this skill

当用户需要提取文本、填充表单或合并 PDF 时激活此技能。

## Instructions

1. 验证输入是有效的 PDF 文件
2. 从 scripts/ 目录运行相应的脚本
3. 返回结果前验证输出
```

资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)

#### 第四步：添加脚本（可选）

在 `scripts/` 子目录中放置可执行文件。推荐使用 PEP 723 规范的 Python 脚本，包含内联依赖声明：

```python
#!/usr/bin/env -S uv run
# /// script
# requires-python = ">= 3.11"
# dependencies = ["requests", "rich"]
# ///
import sys, json

# 使用结构化输出
# 将错误写入 stderr
print(json.dumps({"result": "ok"}))
```

资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)

---

## 技能加载机制

### 渐进式加载设计

Agent Skills 采用「渐进式披露」（Progressive Disclosure）设计，在不同阶段加载不同信息：

```mermaid
graph LR
    A[启动阶段] --> B[仅加载 name + description]
    B --> C[任务匹配时]
    C --> D[加载完整 SKILL.md]
    D --> E[必要时加载 scripts/]
```

资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)

### 加载阶段说明

| 阶段 | 加载内容 | Token 消耗 |
|------|----------|------------|
| 启动扫描 | `name` + `description` | ~50-100 字符/技能 |
| 任务激活 | 完整 `SKILL.md` 正文 | 完整内容 |
| 脚本执行 | `scripts/` 目录文件 | 按需加载 |

资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)

---

## 技能质量标准

### 优质技能特征

| 维度 | 要求 |
|------|------|
| 名称规范 | 小写字母+连字符，与目录名一致 |
| 描述准确 | 清晰说明触发场景和功能范围 |
| 指令明确 | 步骤具体、无歧义、可执行 |
| 示例完整 | 提供真实输入输出示例 |
| 错误处理 | 说明常见错误及处理方式 |

资料来源：[website/src/components/sections/QualityStandards.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/QualityStandards.tsx)

### 完整示例

以下是一个符合所有规范的完整技能示例：

```yaml
---
name: pdf-processing
description: >
  从 PDF 文件中提取文本和表格，填充 PDF 表单，
  合并多个 PDF。适用于处理 PDF 文档、表单或
  涉及文档提取的场景。
license: Apache-2.0
compatibility: Requires Python 3.11+ and uv
metadata:
  author: example-org
  version: "1.0"
allowed-tools: Bash(uv:*) Read Write
---

## When to use this skill

当用户需要提取文本、填充表单或合并 PDF 时激活此技能。

## Instructions

1. 验证输入是有效的 PDF
2. 根据任务类型运行相应脚本
3. 验证输出后返回结果

## Gotchas

- 扫描版 PDF 需要 OCR（使用 ocr.py 而非 extract.py）
- 加密 PDF 需要先解密
```

资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)

---

## 与现有系统集成

### 安装技能到本地

使用 `npx skills` CLI 工具可快速添加技能：

```bash
# 通过 GitHub 添加
npx skills add anthropics/skills/docx

# 手动复制到本地
cp -r my-downloaded-skill ~/.claude/skills/my-skill
```

资料来源：[website/src/components/sections/UsingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/UsingSkills.tsx)

### 验证技能安装

```bash
ls ~/.claude/skills/my-skill/SKILL.md
```

资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)

---

## 参与贡献

如果您希望将技能提交到 awesome-agent-skills 仓库，请参考贡献指南：

- 查看 [CONTRIBUTING.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/CONTRIBUTING.md) 了解提交流程
- 确保技能符合质量标准
- 通过 GitHub Pull Request 提交

资料来源：[website/src/components/sections/Contributing.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/Contributing.tsx)

---

## 相关资源

| 资源 | 链接 |
|------|------|
| 官方规范 | [agentskills.io/specification](https://agentskills.io/specification) |
| skills CLI | [vercel-labs/skills](https://github.com/vercel-labs/skills) |
| Claude 技能文档 | [code.claude.com/docs/en/skills](https://code.claude.com/docs/en/skills) |

---

<a id='page-official-skill-categories'></a>

## 官方技能目录分类

### 相关页面

相关主题：[什么是Agent Skills](#page-what-is-agent-skill), [快速开始](#page-quick-start)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/README.md)
- [website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html)
- [website/src/components/sections/SkillDirectory.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/SkillDirectory.tsx)
- [website/src/components/sections/UsingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/UsingSkills.tsx)
- [website/src/components/sections/QualityStandards.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/QualityStandards.tsx)
- [README.ko.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/README.ko.md)
</details>

# 官方技能目录分类

## 概述

官方技能目录（Skill Directory）是 awesome-agent-skills 项目的核心功能模块，提供了 AI Agent Skills 的可发现性浏览界面。该目录将社区贡献的各类技能按照功能领域进行分类组织，使用户能够快速定位所需的技能集合。技能目录支持动态筛选、搜索过滤以及直接的 GitHub URL 链接访问，每个技能卡片都直接关联到 GitHub 仓库上的具体技能实现。资料来源：[website/index.html:1-50]()

## 目录架构设计

### 渐进式加载机制

技能目录采用「渐进式披露」（Progressive Disclosure）设计模式，在不同阶段加载不同层级的技能信息，以优化性能并减少不必要的资源消耗。

```mermaid
graph TD
    A[启动阶段] --> B[轻量级扫描]
    B --> C[仅加载 name 和 description]
    C --> D[约 50-100 tokens/技能]
    E[任务匹配时] --> F[完整加载]
    F --> G[加载完整 SKILL.md]
    G --> H[读取指令、示例和脚本]
```

技能目录的搜索路径包括以下标准位置：

| 路径位置 | 说明 |
|---------|------|
| `~/.claude/skills/` | Claude Code 默认技能目录 |
| `~/.agents/skills/` | 通用代理技能存储 |
| `.github/skills/` | 项目级技能目录 |
| `.agents/skills/` | 本地项目技能目录 |

资料来源：[website/index.html:120-135]()

### 目录扫描与发现机制

目录组件通过静态分析技能元数据实现自动发现功能。在项目启动时，系统仅提取技能的 `name` 和 `description` 字段，这些信息用于构建技能索引和匹配算法。当用户任务与某个技能的描述相匹配时，才会触发完整 `SKILL.md` 文件的加载流程。

## 分类体系结构

### 主分类维度

技能目录按照功能领域划分为多个主分类维度，每个维度对应特定的技能集合：

| 分类名称 | 涵盖范围 | 典型技能示例 |
|---------|---------|-------------|
| **开发** | 代码编写、调试、重构相关技能 | 代码审查、测试生成、文档编写 |
| **数据** | 数据处理、分析、转换相关技能 | PDF 处理、数据分析、表格提取 |
| **自动化** | 工作流自动化、脚本执行相关技能 | CI/CD 集成、部署自动化 |
| **安全** | 安全扫描、合规检查相关技能 | 漏洞扫描、依赖检查 |

资料来源：[website/index.html:80-95]()

### 技能卡片组件

目录中的每个技能以卡片形式展示，卡片包含以下关键信息：

```typescript
interface SkillCard {
  name: string;           // 技能名称（小写字母+连字符）
  description: string;    // 技能描述（触发条件和使用场景）
  category: string;       // 所属分类
  githubUrl: string;      // GitHub 仓库链接
  tags?: string[];        // 可选标签
}
```

技能卡片的设计强调可访问性，每个卡片都包含直接指向 GitHub 仓库的链接，支持用户快速复制技能 URL 并加载到 AI 代理中。资料来源：[website/src/components/sections/SkillDirectory.tsx:1-30]()

## 技能目录交互流程

### 用户发现与加载流程

```mermaid
sequenceDiagram
    participant User as 用户
    participant Directory as 技能目录
    participant Agent as AI 代理
    participant GitHub as GitHub

    User->>Directory: 浏览技能目录
    Directory->>User: 显示分类技能列表
    User->>Directory: 选择目标技能
    Directory->>User: 返回 GitHub URL
    User->>Agent: 粘贴 GitHub URL
    Agent->>GitHub: 请求 SKILL.md 内容
    GitHub->>Agent: 返回技能定义
    Agent->>User: 执行任务
```

### 多平台加载方式

根据不同的 AI 代理平台，技能加载方式存在差异：

| 平台 | 加载命令 | 说明 |
|-----|---------|------|
| Claude Code | `/skills add <github-url>` | 使用斜杠命令添加技能 |
| Claude.ai | 粘贴原始 SKILL.md URL | 直接在聊天窗口粘贴 |
| Cursor | 放入 `.github/skills/` | IDE 自动识别 |
| Claude.ai 免费版 | 支持完整功能 | 无需付费 |

资料来源：[website/src/components/sections/UsingSkills.tsx:1-40]()

## 技能筛选与搜索功能

### 动态过滤机制

目录提供实时搜索和分类筛选功能，用户可以通过关键词快速定位目标技能。搜索算法基于技能名称和描述进行匹配，支持模糊搜索和精确匹配两种模式。

技能目录还实现了分类内搜索功能，允许用户在同一分类下进行二次筛选，进一步缩小搜索范围。

### 筛选状态管理

```mermaid
stateDiagram-v2
    [*] --> 全部技能
    全部技能 --> 按分类筛选
    按分类筛选 --> 搜索关键词
    搜索关键词 --> 精确结果
    精确结果 --> 重置筛选
    重置筛选 --> 全部技能
```

当用户输入搜索关键词时，系统会同时匹配技能名称、描述和标签字段，返回相关性排序的结果列表。资料来源：[website/index.html:95-110]()

## 目录展示组件

### 响应式网格布局

技能目录采用响应式网格布局，根据视口宽度动态调整每行显示的技能卡片数量：

| 视口宽度 | 每行卡片数 | 布局模式 |
|---------|----------|---------|
| ≥1280px | 4 列 | 四列网格 |
| ≥768px | 2-3 列 | 双列/三列网格 |
| <768px | 1 列 | 单列堆叠 |

### 分类标签系统

每个技能可附加多个分类标签，标签系统支持以下功能：

- **多分类归属**：单个技能可属于多个分类
- **标签过滤**：支持按标签快速筛选
- **视觉标识**：不同分类使用不同颜色区分

资料来源：[website/src/components/sections/SkillDirectory.tsx:40-60]()

## 技能目录数据源

### GitHub 仓库集成

技能目录通过集成 GitHub API 获取技能列表和元数据。每个技能对应一个独立的 GitHub 仓库或仓库内的子目录，目录结构要求包含 `SKILL.md` 文件作为技能定义入口。

```
repository/
├── SKILL.md          # 必需：技能定义文件
├── scripts/          # 可选：可执行脚本目录
│   ├── extract.py
│   └── transform.sh
├── assets/           # 可选：资源文件目录
└── README.md         # 可选：技能说明文档
```

### 元数据提取

目录从 GitHub 仓库的 `SKILL.md` 文件中提取以下元数据：

- `name`：技能唯一标识符
- `description`：技能功能描述
- `license`：开源许可证类型
- `compatibility`：兼容性要求
- `allowed-tools`：预批准工具列表
- `metadata`：作者、版本等信息

资料来源：[website/index.html:150-180]()

## 质量标准与分类规范

### 技能描述质量要求

技能目录对收录的技能有明确的质量标准要求：

| 标准项 | 要求 | 说明 |
|-------|------|------|
| 描述完整性 | 必须包含触发条件 | 说明何时应激活该技能 |
| 语言风格 | 使用祈使语气 | "Use this skill when..." |
| 关键词覆盖 | 包含用户可能输入的关键词 | 提高匹配准确度 |
| 示例提供 | 建议包含输入输出示例 | 帮助理解技能用途 |

### 优秀与不良示例对比

资料来源：[website/src/components/sections/QualityStandards.tsx:1-30]()

**优秀描述示例：**
```
Extracts text and tables from PDF files. Use when working with 
PDFs, forms, or document extraction.
```

**不良描述示例：**
```
Helps with PDFs.
```

## 兼容性与扩展性

### 多代理平台兼容

技能目录设计为跨平台兼容，确保同一技能可在多个 AI 代理产品中使用：

```mermaid
graph LR
    A[SKILL.md 标准格式] --> B[Claude Code]
    A --> C[Claude.ai]
    A --> D[OpenAI Codex]
    A --> E[GitHub Copilot]
    A --> F[Cursor]
    A --> G[Gemini CLI]
    
    B --> H[30+ 代理产品]
    C --> H
    D --> H
    E --> H
    F --> H
    G --> H
```

### npx skills CLI 工具支持

技能目录与 `npx skills` 命令行工具深度集成，提供便捷的技能发现和管理能力：

```bash
npx skills find [query]            # 搜索相关技能
npx skills add <owner/repo>        # 添加技能（支持 GitHub 简写）
npx skills list                    # 列出已安装技能
npx skills check                   # 检查更新
npx skills update                  # 更新所有技能
npx skills remove [skill-name]     # 移除指定技能
```

资料来源：[README.ko.md:60-75]()

## 总结

官方技能目录分类模块是 awesome-agent-skills 项目的核心功能，通过清晰的分类体系、渐进式加载机制和跨平台兼容设计，为用户提供了高效的技能发现和管理体验。目录采用模块化架构，支持多种 AI 代理平台的技能共享，是构建可复用 AI 代理能力的标准化解决方案。

---

<a id='page-website-architecture'></a>

## 网站架构

### 相关页面

相关主题：[项目结构](#page-project-structure)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [website/src/app/layout.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/app/layout.tsx)
- [website/src/app/page.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/app/page.tsx)
- [website/src/components/LayoutShell.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/LayoutShell.tsx)
- [website/src/components/Navbar.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/Navbar.tsx)
- [website/src/components/Footer.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/Footer.tsx)
- [website/src/components/sections/WhatIsIt.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/WhatIsIt.tsx)
- [website/src/components/sections/QualityStandards.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/QualityStandards.tsx)
- [website/src/components/sections/UsingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/UsingSkills.tsx)

</details>

# 网站架构

## 概述

awesome-agent-skills 网站是一个基于 Next.js 构建的现代化文档展示平台，用于展示 AI Agent 技能（Agent Skills）的目录和教程。该网站采用 React + TypeScript + Tailwind CSS 技术栈构建，具有响应式设计，支持明暗主题切换，并提供多语言内容展示能力。

## 技术栈

| 技术 | 用途 | 版本要求 |
|------|------|----------|
| Next.js | React 框架与 SSR/SSG 支持 | - |
| React 18 | UI 组件库 | 18.x |
| TypeScript | 类型安全开发 | 5.x |
| Tailwind CSS | 原子化 CSS 样式框架 | 3.x |
| Lucide React | 图标库 | - |

## 整体架构

网站采用标准的 Next.js App Router 架构模式，组件化设计贯穿整个项目。

```mermaid
graph TB
    subgraph "App Router Layer"
        A["app/layout.tsx"] --> B["app/page.tsx"]
    end
    
    subgraph "Layout Shell"
        C["LayoutShell.tsx"] --> D["Navbar.tsx"]
        C --> E["Footer.tsx"]
    end
    
    subgraph "Page Sections"
        F["WhatIsIt.tsx"]
        G["QualityStandards.tsx"]
        H["UsingSkills.tsx"]
        I["CreatingSkills.tsx"]
        J["FindingSkills.tsx"]
        K["Tutorials.tsx"]
    end
    
    B --> C
    C --> F
    C --> G
    C --> H
    C --> I
    C --> J
    C --> K
```

## 核心组件结构

### 布局层组件

#### LayoutShell.tsx

布局容器组件，负责整体页面结构的组织。该组件是页面内容与导航栏、页脚之间的桥梁，协调各部分组件的渲染顺序和布局关系。

#### Navbar.tsx

顶部导航栏组件，提供网站主导航功能，包含 Logo、页面链接和外部社交媒体入口。导航栏组件实现了响应式设计，支持移动端菜单折叠。

#### Footer.tsx

页脚组件，包含以下关键信息：

- 网站版权声明（2026年）
- 出版方信息（GitHub）
- 主要链接入口：
  - agent-skill.co 官方网站
  - GitHub 仓库地址
  - X (Twitter) 社交链接
  - 电子邮件联系方式

```typescript
<a href="https://agent-skill.co" target="_blank" rel="noopener noreferrer">
  agent-skill.co
</a>
<a href="https://github.com/heilcheng/awesome-agent-skills">
  GitHub
</a>
<a href="https://x.com/haileyhmt" target="_blank" rel="noopener noreferrer">
  Twitter
</a>
<a href="mailto:haileycheng@proton.me">
  Mail
</a>
```

资料来源：[website/src/components/Footer.tsx]()

### 页面区块组件 (Sections)

网站内容由多个独立的 Section 组件构成，每个组件负责一个特定的展示区域：

| 组件 | 功能描述 |
|------|----------|
| WhatIsIt.tsx | 介绍 Agent Skills 的核心概念和价值主张 |
| QualityStandards.tsx | 展示技能的质量标准和最佳实践示例 |
| UsingSkills.tsx | 指导用户如何使用现有技能 |
| CreatingSkills.tsx | 提供创建新技能的指南 |
| FindingSkills.tsx | 介绍如何发现和获取技能资源 |
| Tutorials.tsx | 展示教程和高级使用案例 |

#### WhatIsIt.tsx 组件结构

该组件通过 Icon + Title + Description 的标准化卡片布局展示信息：

```typescript
{features.map(({ Icon, title, desc }) => (
  <div key={title} className="flex gap-4 p-5 border rounded-xl bg-white dark:bg-neutral-900">
    <div className="p-2 rounded-lg bg-neutral-100 dark:bg-neutral-800 h-fit">
      <Icon className="w-4 h-4 text-neutral-600 dark:text-neutral-400" />
    </div>
    <div>
      <h3 className="text-sm font-semibold text-neutral-900 dark:text-white mb-1">{title}</h3>
      <p className="text-xs text-neutral-500 dark:text-neutral-400 leading-relaxed">{desc}</p>
    </div>
  </div>
))}
```

资料来源：[website/src/components/sections/WhatIsIt.tsx]()

#### QualityStandards.tsx 组件结构

该组件展示了技能的优劣对比示例，采用双栏布局：

```mermaid
graph LR
    A[QualityStandards] --> B[质量标准卡片列表]
    A --> C[Good Example 面板]
    A --> D[Bad Example 面板]
    
    C --> E["✅ 良好模式示例"]
    D --> F["❌ 错误模式示例"]
```

组件使用 `CheckCircle2` 和 `XCircle` 图标区分良好和不良示例，并通过透明度设置（opacity-70）视觉降级错误示例的显示效果。

资料来源：[website/src/components/sections/QualityStandards.tsx]()

#### UsingSkills.tsx 组件结构

该组件专注于展示技能加载和使用的操作流程，包含以下功能模块：

1. **三步骤说明卡片** - 展示使用技能的标准流程
2. **代码面板** - 提供 CLI 命令示例和手动配置路径
3. **复制功能** - 支持一键复制代码片段

```typescript
<pre className="px-4 py-4 text-sm font-mono text-neutral-700 dark:text-neutral-300 overflow-x-auto">
  <code>npx skills add anthropics/skills/docx</code>
</pre>
```

支持多种添加方式：GitHub 简写格式、完整 URL、本地相对路径。

资料来源：[website/src/components/sections/UsingSkills.tsx]()

## 主题系统

网站实现了完整的明暗主题切换功能，采用 CSS 自定义属性（CSS Variables）实现：

```css
:root{
  --bg:#000;
  --bg1:rgba(255,255,255,0.03);
  --bg2:rgba(255,255,255,0.05);
  --bg3:rgba(255,255,255,0.08);
  --border:rgba(255,255,255,0.08);
  --border2:rgba(255,255,255,0.12);
  --text:rgba(255,255,255,0.95);
}
```

Tailwind CSS 暗黑模式类名映射：

| 亮色类 | 暗黑模式类 | 用途 |
|--------|------------|------|
| text-neutral-900 | dark:text-white | 主文本颜色 |
| text-neutral-500 | dark:text-neutral-400 | 次要文本 |
| bg-white | dark:bg-neutral-900 | 卡片背景 |
| border-neutral-200 | dark:border-neutral-800 | 边框颜色 |

## 页面路由结构

```
website/src/app/
├── layout.tsx    # 根布局，包含全局样式和主题配置
└── page.tsx      # 首页主路由
```

Next.js App Router 模式下，`layout.tsx` 定义的布局会被所有页面共享，确保导航栏和页脚在整个网站中保持一致。

## 组件通信模式

组件间主要通过以下方式进行数据和状态传递：

```mermaid
graph TD
    A[layout.tsx] -->|props| B[LayoutShell]
    B -->|props| C[Navbar]
    B -->|props| D[Footer]
    B -->|children| E[Page Sections]
    
    F[Feature Data] -->|map| E
    G[i18n] -->|translations| E
```

## 响应式设计策略

网站采用移动优先的响应式设计原则，关键断点如下：

| 断点前缀 | 屏幕宽度 | 典型设备 |
|----------|----------|----------|
| 无前缀 | < 768px | 手机 |
| md: | ≥ 768px | 平板 |
| lg: | ≥ 1024px | 桌面 |

常用响应式布局类：

- `md:grid-cols-2` - 中等屏幕双栏布局
- `gap-4` → `md:gap-6` - 间距随屏幕放大
- `px-4` → `md:px-8` - 水平内边距递增

## 开发规范

### 组件文件组织

```
website/src/components/
├── LayoutShell.tsx      # 布局容器
├── Navbar.tsx           # 导航栏
├── Footer.tsx           # 页脚
└── sections/           # 页面区块
    ├── WhatIsIt.tsx
    ├── QualityStandards.tsx
    ├── UsingSkills.tsx
    ├── CreatingSkills.tsx
    ├── FindingSkills.tsx
    └── Tutorials.tsx
```

### 样式编写规范

1. **优先使用 Tailwind 原子类** - 减少自定义 CSS 文件
2. **使用 CSS 变量管理主题色** - 便于暗黑模式切换
3. **组件内样式隔离** - 避免样式冲突
4. **统一使用 neutral 色系** - 配合暗色主题

### 国际化考虑

网站内容通过翻译对象结构组织，便于扩展多语言支持。现有包含韩语版本（README.ko.md），说明项目有多语言文档需求。

## 总结

awesome-agent-skills 网站采用了现代化的前端架构设计，通过 Next.js App Router 实现服务端渲染和客户端导航的平衡。组件化的设计使得各功能模块高度解耦，便于维护和扩展。明暗主题支持、响应式布局和多语言文档能力共同构成了这个文档网站的技术基础。

---

---

## Doramagic 踩坑日志

项目：heilcheng/awesome-agent-skills

摘要：发现 10 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。

## 1. 身份坑 · 仓库名和安装名不一致

- 严重度：medium
- 证据强度：runtime_trace
- 发现：仓库名 `awesome-agent-skills` 与安装入口 `skills` 不完全一致。
- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。
- 复现命令：`npx skills`
- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。
- 证据：identity.distribution | github_repo:1124920990 | https://github.com/heilcheng/awesome-agent-skills | repo=awesome-agent-skills; install=skills

## 2. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
- 证据：capability.host_targets | github_repo:1124920990 | https://github.com/heilcheng/awesome-agent-skills | host_targets=claude

## 3. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:1124920990 | https://github.com/heilcheng/awesome-agent-skills | README/documentation is current enough for a first validation pass.

## 4. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:1124920990 | https://github.com/heilcheng/awesome-agent-skills | last_activity_observed missing

## 5. 安全/权限坑 · 下游验证发现风险项

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:1124920990 | https://github.com/heilcheng/awesome-agent-skills | no_demo; severity=medium

## 6. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:1124920990 | https://github.com/heilcheng/awesome-agent-skills | no_demo; severity=medium

## 7. 安全/权限坑 · 来源证据：Add Rug Munch Intelligence - Crypto Security & Analytics Agent Skills (x402, Base + Solana)

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add Rug Munch Intelligence - Crypto Security & Analytics Agent Skills (x402, Base + Solana)
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_dc99192b4a9b4b8089f4f6696f332a7d | https://github.com/heilcheng/awesome-agent-skills/issues/218 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。

## 8. 安全/权限坑 · 来源证据：⚡ Pay-per-call web search, scraping & AI tools for your agent — VERITY (L402)

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：⚡ Pay-per-call web search, scraping & AI tools for your agent — VERITY (L402)
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_0703404b82014fe3baddd3eaab1100bd | https://github.com/heilcheng/awesome-agent-skills/issues/226 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

## 9. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:1124920990 | https://github.com/heilcheng/awesome-agent-skills | issue_or_pr_quality=unknown

## 10. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:1124920990 | https://github.com/heilcheng/awesome-agent-skills | release_recency=unknown

<!-- canonical_name: heilcheng/awesome-agent-skills; human_manual_source: deepwiki_human_wiki -->