项目概述

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

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

核心价值主张

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

资料来源：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

前端技术栈

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

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

Agent Skills 协议

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

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）设计理念，遵循四阶段加载模型：

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 客户端：

资料来源：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

技能质量标准

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

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

命令行工具支持

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

资料来源：README.ko.md:15-25

兼容的 Agent 平台

项目支持的 Agent 产品矩阵：

资料来源：README.ko.md:30-40

快速入门

使用现有技能

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.zh-CN.md:1 README.ko.md:1

相关资源

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

概述

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

技术栈概览

资料来源：README.ko.md:1-20

目录结构

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 模块架构

组件层级结构

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 实现布局动画，支持按名称和描述进行技能搜索。

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

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

#### QualityStandards 组件

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

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

#### UsingSkills 组件

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

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

#### FindingSkills 组件

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

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

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

#### Footer 组件

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

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

主题与样式系统

暗色模式支持

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

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

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

色彩系统

资料来源：website/index.html:1-100

技能目录组织

目录结构规范

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

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

SKILL.md 格式规范

每个技能必须包含 YAML frontmatter：

概述

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

核心特点

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

资料来源：website/index.html

SKILL.md 文件格式规范

文件结构

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

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

Frontmatter 元数据

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

概述

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

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

支持的AI代理列表

主流支持的代理

资料来源：website/index.html:1-10

代理兼容性说明

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

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. 指令执行：根据技能指令和可选脚本完成任务

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 代理有所不同：

资料来源：website/index.html:180-200

技能格式规范

SKILL.md 结构

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

概述

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

资料来源：website/index.html

核心质量维度

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

资料来源：website/index.html:1-150

SKILL.md 元数据标准

必需字段

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

什么是 Agent Skill

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

资料来源：website/index.html:1-50

三分钟快速上手

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

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 代理中。根据平台不同，命令略有差异：

资料来源：README.ko.md:30-45

步骤三：用自然语言提问

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

资料来源：website/index.html:80-100

使用 npx skills CLI 工具

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

资料来源：README.ko.md:20-30

兼容的 AI 代理

资料来源：README.ko.md:48-55

手动加载技能

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

# 下载技能后放置到指定目录
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 基本格式

什么是 Agent Skills

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

资料来源：website/index.html:1-20

核心特性

资料来源：website/index.html:120-140

工作原理

渐进式披露机制

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

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

三个阶段详解

资料来源：website/index.html:280-310

使用方式

方式一：通过 CLI 添加

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

npx skills add anthropics/skills/docx

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

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

方式二：手动放置

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

放置结构示例：

.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 会自动读取并应用技能说明。

使用流程

三步上手指南

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 正文的结构：

概述

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

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

资料来源：website/index.html

概述

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

目录架构设计

渐进式加载机制

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

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

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

资料来源：website/index.html:120-135

目录扫描与发现机制

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

分类体系结构

主分类维度

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

资料来源：website/index.html:80-95

技能卡片组件

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

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

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

技能目录交互流程

用户发现与加载流程

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 代理平台，技能加载方式存在差异：

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

技能筛选与搜索功能

动态过滤机制

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

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

筛选状态管理

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

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

目录展示组件

响应式网格布局

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

分类标签系统

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

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

资料来源：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

质量标准与分类规范

技能描述质量要求

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

优秀与不良示例对比

资料来源：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 代理产品中使用：

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 命令行工具深度集成，提供便捷的技能发现和管理能力：

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 代理能力的标准化解决方案。

概述

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

技术栈

整体架构

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

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) 社交链接
• 电子邮件联系方式

<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:[email protected]">
  Mail
</a>

资料来源：website/src/components/Footer.tsx

页面区块组件 (Sections)

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

#### WhatIsIt.tsx 组件结构

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

{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 组件结构

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

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. 复制功能 - 支持一键复制代码片段

<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）实现：

: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 暗黑模式类名映射：

页面路由结构

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

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

组件通信模式

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

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

响应式设计策略

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

常用响应式布局类：

• 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 实现服务端渲染和客户端导航的平衡。组件化的设计使得各功能模块高度解耦，便于维护和扩展。明暗主题支持、响应式布局和多语言文档能力共同构成了这个文档网站的技术基础。

Pitfall Log / 踩坑日志

项目：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