目录

🚀 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>;
     }
   }

  1. 使用 TypeScript

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

  2. 组件拆分

    • 容器组件：管理状态和逻辑
    • 展示组件：只负责渲染
    • 每个组件不超过 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;

参考资源

### 📦 打包发布

```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篇）]

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

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

Logo
龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

从OpenClaw和Claude code的设计上学习Agent编排

ubagent编排OpenClaw里内置了子agent机制，核心就是sessions_spawn和subagents两个工具，它们会被加入OpenClaw的工具集合里，都在src/agents/tools目录下，也就是说，OpenClaw的多agent编排不是硬编码好的固定supervisor-worker流程，顶层agent拿到一套工具，它自己决定要不要调用sessions_spawn；

avatar 龙虾开发者社区
cover

【AI Agent 全栈开发】LLM的接入方式

avatar 龙虾开发者社区
cover

Harness 架构企业工程落地指南

avatar 龙虾开发者社区