🚀 Codex CLI Skills 技能系统：从安装到开发完全指南

📅 更新于 2026年5月 | ✍️ 原创文章，转载请注明出处

本系列共12篇，本文是第7篇

---

---

1. 什么是 Skills

📖 Skills 定义

Skills 是 Codex CLI 的可复用知识模块，包含：

• 特定领域的专业知识
• 预定义的工作流程
• 最佳实践和模板
• 常见问题的解决方案

简单说：Skills 让 AI 在特定领域变得更专业。

🔧 Skills 组成

skill-name/
├── SKILL.md          # 技能说明文档（必需）
├── references/       # 参考文档
├── templates/        # 模板文件
├── scripts/          # 辅助脚本
└── assets/           # 其他资源

💡 工作原理

用户请求 → 加载相关 Skills → AI 结合专业知识 → 更专业的回答

🌟 示例

没有 Skills：

> 帮我写一个 React 组件
AI：这是一个基本的 React 组件...（通用回答）

有 React Skills：

> 帮我写一个 React 组件
AI：根据项目规范，使用 TypeScript + Hooks + Styled Components...（专业回答）

---

2. 为什么使用 Skills

🎯 核心价值

没有 Skills	有 Skills
AI 用通用知识回答	AI 用专业知识回答
每次都要解释规范	规范已内置
质量参差不齐	质量稳定一致
效率较低	效率提升 5-10 倍

📊 使用场景

场景	Skills	效果
代码审查	code-review skill	按照团队规范审查
测试编写	testing skill	生成符合规范的测试
文档生成	documentation skill	生成标准格式文档
API 开发	api-development skill	遵循 RESTful 规范
数据库设计	database-design skill	符合最佳实践
安全审计	security-audit skill	检查安全漏洞

✅ 什么时候用 Skills

• 项目有特定的技术栈和规范
• 团队有统一的开发流程
• 需要高质量的一致性输出
• 重复性的开发任务

❌ 什么时候不用 Skills

• 一次性的小任务
• 探索性的实验
• 不需要特定专业知识的任务

---

3. Skills vs MCP vs Plugins

📊 对比表

特性	Skills	MCP	Plugins
用途	知识和流程	工具和数据	功能扩展
格式	Markdown	服务器进程	代码模块
安装	文件复制	配置服务器	安装包
运行	注入上下文	独立进程	运行时加载
示例	代码审查规范	数据库查询	语音识别

💡 如何选择

需求	选择
让 AI 更懂某个领域	Skills
让 AI 访问外部数据	MCP
让 AI 有新功能	Plugins
预定义工作流程	Skills
调用外部 API	MCP
自定义 UI	Plugins

🔗 组合使用

Codex CLI
├── Skills（知识层）
│   ├── code-review
│   ├── testing
│   └── api-development
├── MCP（工具层）
│   ├── postgres
│   ├── github
│   └── filesystem
└── Plugins（功能层）
    ├── voice
    └── visualization

---

4. 内置 Skills 介绍

📦 Codex CLI 内置 Skills

Skill	说明	使用场景
code-review	代码审查	PR 审查、代码质量检查
testing	测试编写	单元测试、集成测试
documentation	文档生成	API 文档、README
refactoring	代码重构	优化代码结构
debugging	调试辅助	定位和修复 bug
git-workflow	Git 工作流	分支管理、提交规范
api-design	API 设计	RESTful API 设计
database	数据库操作	SQL 优化、迁移
security	安全审计	漏洞检查、安全加固
performance	性能优化	性能分析、优化建议

🔍 查看内置 Skills

# 列出所有 Skills
/skills list

# 查看 Skill 详情
/skills info code-review

# 加载 Skill
/skills load code-review

---

5. 安装和管理 Skills

📥 安装 Skills

方式一：从 npm 安装

# 安装官方 Skills
npm install -g @anthropic/skill-code-review
npm install -g @anthropic/skill-testing

# 安装社区 Skills
npm install -g @community/skill-react-best-practices

方式二：从 GitHub 安装

# 克隆 Skills 仓库
git clone https://github.com/anthropic/codex-skills.git

# 复制到 Skills 目录
cp -r codex-skills/code-review ~/.codex/skills/

方式三：手动创建

# 创建 Skills 目录
mkdir -p ~/.codex/skills/my-custom-skill

# 创建 SKILL.md
cat > ~/.codex/skills/my-custom-skill/SKILL.md << 'EOF'
# My Custom Skill

## 触发条件
当用户请求...
EOF

📁 Skills 目录结构

~/.codex/
├── config.json
└── skills/
    ├── code-review/
    │   └── SKILL.md
    ├── testing/
    │   └── SKILL.md
    └── my-custom-skill/
        └── SKILL.md

🔧 管理 Skills

# 列出所有 Skills
/skills list

# 查看 Skill 详情
/skills info <skill-name>

# 加载 Skill
/skills load <skill-name>

# 卸载 Skill
/skills unload <skill-name>

# 删除 Skill
/skills remove <skill-name>

# 更新 Skills
/skills update

📋 配置自动加载

在 ~/.codex/config.json 中配置：

{
  "skills": {
    "autoLoad": ["code-review", "testing"],
    "path": "~/.codex/skills"
  }
}

---

6. 使用 Skills

🎯 基本使用

方式一：自动触发

codex

> 审查 src/auth/service.py 的代码
# Codex 自动加载 code-review skill

方式二：手动加载

codex

/skills load code-review

> 审查这个 PR 的代码

方式三：指定 Skill

codex

> 使用 testing skill 为 UserService 编写单元测试

📝 使用示例

1. 代码审查

/skills load code-review

> 审查 src/ 目录下的所有修改
> 重点关注：
> 1. 安全漏洞
> 2. 性能问题
> 3. 代码规范

输出：

## 代码审查报告

### 🔴 严重问题
1. **SQL 注入漏洞** - src/dao/user.py:45
   - 问题：直接拼接 SQL 字符串
   - 建议：使用参数化查询

### 🟡 警告
1. **未使用的导入** - src/service/order.py:12
2. **魔法数字** - src/utils/helper.py:78

### ✅ 优点
1. 错误处理完善
2. 日志记录规范

2. 测试编写

/skills load testing

> 为 src/service/user_service.py 编写单元测试
> 要求：
> - 使用 pytest
> - 覆盖所有公开方法
> - 测试边界条件

输出：

# tests/test_user_service.py

import pytest
from unittest.mock import Mock, patch
from src.service.user_service import UserService

class TestUserService:
    @pytest.fixture
    def service(self):
        return UserService()
    
    def test_create_user_success(self, service):
        # 测试正常创建
        user = service.create_user("alice", "alice@example.com")
        assert user.username == "alice"
    
    def test_create_user_duplicate(self, service):
        # 测试重复创建
        with pytest.raises(DuplicateUserError):
            service.create_user("alice", "alice@example.com")
    
    def test_create_user_invalid_email(self, service):
        # 测试无效邮箱
        with pytest.raises(InvalidEmailError):
            service.create_user("bob", "invalid-email")

3. 文档生成

/skills load documentation

> 为 src/api/ 目录生成 API 文档
> 格式：Markdown
> 包含：请求/响应示例

💡 使用技巧

1. 明确指定 Skill

   # ❌ 不明确
   > 帮我写测试
   
   # ✅ 明确
   > 使用 testing skill 为 UserService 写单元测试
   

2. 组合多个 Skills

   /skills load code-review
   /skills load security
   
   > 审查这个 PR，重点关注安全问题
   

3. 提供上下文

   /skills load testing
   
   > 这是一个 Spring Boot 项目，使用 JUnit 5 + Mockito
   > 请为 OrderService 编写测试
   

---

7. 开发自定义 Skills

🛠️ 开发准备

1. 创建 Skills 目录
2. 编写 SKILL.md
3. 添加辅助文件
4. 测试 Skill

📝 SKILL.md 结构

# Skill 名称

> 简短描述

## 触发条件

描述什么时候应该加载这个 Skill：
- 条件 1
- 条件 2

## 核心知识

### 概念 1
解释...

### 概念 2
解释...

## 工作流程

1. 步骤 1
2. 步骤 2
3. 步骤 3

## 最佳实践

### ✅ 推荐做法
- 做法 1
- 做法 2

### ❌ 避免事项
- 事项 1
- 事项 2

## 模板

### 模板 1
```代码```

## 参考资源

- [链接 1](url)
- [链接 2](url)

📋 示例：React 开发 Skill

# React Development Skill

> React + TypeScript 项目开发规范

## 触发条件

当用户请求以下任务时加载此 Skill：
- 创建 React 组件
- 编写 React Hooks
- React 状态管理
- React 性能优化

## 核心知识

### 组件规范

1. **使用函数组件**
   ```typescript
   // ✅ 推荐
   const UserCard: React.FC<UserCardProps> = ({ user }) => {
     return <div>{user.name}</div>;
   };
   
   // ❌ 避免
   class UserCard extends React.Component {
     render() {
       return <div>{this.props.user.name}</div>;
     }
   }

2. 使用 TypeScript

   interface UserCardProps {
     user: TUser;
     onSelect: (id: string) => void;
   }
   

3. 组件拆分

   • 容器组件：管理状态和逻辑
   • 展示组件：只负责渲染
   • 每个组件不超过 200 行

Hooks 规范

1. 自定义 Hooks

   const useUser = (id: string) => {
     const [user, setUser] = useState<TUser | null>(null);
     const [loading, setLoading] = useState(true);
     
     useEffect(() => {
       fetchUser(id).then(setUser).finally(() => setLoading(false));
     }, [id]);
     
     return { user, loading };
   };
   

2. 依赖数组

   • 始终提供完整的依赖数组
   • 使用 useCallback/useMemo 优化

状态管理

1. 本地状态：useState
2. 复杂状态：useReducer
3. 全局状态：Zustand / Redux Toolkit
4. 服务端状态：React Query / SWR

工作流程

1. 需求分析

   • 确定组件职责
   • 设计 Props 接口
   • 选择状态管理方案

2. 组件开发

   • 创建组件文件
   • 实现核心逻辑
   • 添加样式

3. 测试验证

   • 单元测试
   • 集成测试
   • 快照测试

最佳实践

✅ 推荐做法

• 使用 TypeScript 严格模式
• 组件文件使用 PascalCase
• 导出使用 default export
• 使用 React.memo 优化渲染
• 使用 useCallback/useMemo 避免不必要的渲染

❌ 避免事项

• 不要使用 any 类型
• 不要在循环中使用 Hooks
• 不要直接修改 state
• 不要在组件内发请求（用 Hooks）
• 不要使用 index 作为 key

模板

基础组件模板

import React from 'react';

interface Props {
  // 定义 Props
}

const ComponentName: React.FC<Props> = ({ prop1, prop2 }) => {
  return (
    <div>
      {/* 组件内容 */}
    </div>
  );
};

export default ComponentName;

自定义 Hook 模板

import { useState, useEffect } from 'react';

interface UseHookNameResult {
  data: TData | null;
  loading: boolean;
  error: Error | null;
}

const useHookName = (param: string): UseHookNameResult => {
  const [data, setData] = useState<TData | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<Error | null>(null);

  useEffect(() => {
    fetchData(param)
      .then(setData)
      .catch(setError)
      .finally(() => setLoading(false));
  }, [param]);

  return { data, loading, error };
};

export default useHookName;

参考资源

• React 官方文档
• TypeScript React 文档
• 项目 AGENTS.md

### 📦 打包发布

```bash
# 1. 创建目录
mkdir my-skill
cd my-skill

# 2. 创建 SKILL.md
cat > SKILL.md << 'EOF'
# My Skill
...
EOF

# 3. 添加辅助文件
mkdir references templates scripts
# 添加文件...

# 4. 发布到 npm
npm init -y
npm publish

# 5. 或者发布到 GitHub
git init
git add .
git commit -m "feat: add my-skill"
git push

🔧 配置使用

# 从 npm 安装
npm install -g @anthropic/my-skill

# 或者手动复制
cp -r my-skill ~/.codex/skills/

# 验证安装
/skills list

---

8. Skills 最佳实践

✅ DO - 推荐做法

1. 明确触发条件

   ## 触发条件
   当用户请求以下任务时加载此 Skill：
   - 创建 React 组件
   - 编写 React Hooks
   

2. 提供具体示例

   ## 示例
   ```typescript
   // ✅ 推荐
   const Component: React.FC<Props> = ({ prop }) => {...};
   

3. 包含最佳实践

   ## 最佳实践
   ### ✅ 推荐做法
   - 使用 TypeScript
   
   ### ❌ 避免事项
   - 不要使用 any
   

4. 提供模板

   ## 模板
   ```typescript
   // 组件模板
   

5. 保持更新

   • 定期检查内容是否过时
   • 更新到最新版本

❌ DON’T - 避免事项

1. 不要过于冗长

   • 保持精炼
   • 每个章节不超过 50 行

2. 不要包含敏感信息

   • 不要包含密码、密钥
   • 不要包含内部信息

3. 不要重复通用知识

   • 只包含特定领域的知识
   • 通用知识让 AI 自己处理

4. 不要忽略格式

   • 使用正确的 Markdown
   • 保持格式一致

📋 Skills 质量检查清单

• 触发条件明确
• 核心知识完整
• 示例代码正确
• 最佳实践清晰
• 模板可用
• 格式规范
• 没有过时信息

---

9. 常见问题

❓ Q1：Skills 目录在哪里？

A：

# 全局 Skills
~/.codex/skills/

# 项目级 Skills
.codex/skills/

# 查看路径
/skills path

❓ Q2：如何知道加载了哪些 Skills？

A：

# 查看当前加载的 Skills
/skills list

# 查看详细信息
/skills info <skill-name>

❓ Q3：Skills 会被上传到 OpenAI 吗？

A：是的，Skills 内容会作为上下文发送到 OpenAI 服务器。

安全建议：

• 不要包含敏感信息
• 使用公开的知识
• 企业用户考虑使用 Enterprise 版本

❓ Q4：Skills 多大合适？

A：建议控制在 100-500 行。

• 太短（< 50 行）：信息不足
• 太长（> 1000 行）：消耗过多上下文

❓ Q5：如何调试 Skills？

A：

# 启用详细模式
codex --verbose

# 查看加载的 Skills
/skills list

# 测试 Skill
/skills load my-skill
> 测试任务

❓ Q6：Skills 可以继承吗？

A：目前不支持继承，但可以：

• 在 SKILL.md 中引用其他 Skills
• 使用 include 语法（部分实现）

❓ Q7：如何分享 Skills？

A：

# 方式1：发布到 npm
npm publish

# 方式2：发布到 GitHub
git push

# 方式3：直接分享文件
cp -r my-skill /path/to/share/

---

10. 总结

🎯 核心要点

1. Skills 是什么：可复用的知识模块
2. 为什么用：让 AI 在特定领域更专业
3. 怎么安装：npm install 或手动复制
4. 怎么使用：自动触发或手动加载
5. 怎么开发：编写 SKILL.md + 辅助文件

📋 快速开始

1. 查看内置 Skills：/skills list
2. 加载一个 Skill：/skills load code-review
3. 测试效果：执行一个任务
4. 开发自己的 Skill：创建 SKILL.md

📚 下一步

• 📖 第8篇：[非交互模式：自动化你的开发工作流]
• 🔧 实践：开发一个适合你项目的 Skills
• 💬 社区：分享你的 Skills

---

📝 系列文章导航

• 上一篇：[第6篇 - MCP 集成：扩展 AI 能力的正确姿势]
• 下一篇：[第8篇 - 非交互模式：自动化你的开发工作流]
• 系列目录：[Codex CLI 中文官方手册与使用指南（12篇）]

---

💡 遇到问题？ 欢迎在评论区留言，我会及时回复！

👍 觉得有用？ 点赞收藏，帮助更多开发者！