Codex 使用指南

Appearance

skill-creator - 技能创建指南 ​

skill-creator 技能提供了创建新 Codex 技能的完整指导，帮助你设计、编写和部署高质量的自定义技能。

何时使用 ​

以下场景适合触发 skill-creator 技能：

  • 创建全新的 Codex 技能
  • 更新或改进已有技能
  • 验证技能是否有效
  • 了解 SKILL.md 文件格式
  • 设计技能的信息架构

技能结构 ​

每个技能的核心是一个 SKILL.md 文件，可选地包含脚本和参考资源：

skill-name/
├── SKILL.md              # 必须 - 主指令文件
├── scripts/              # 可选 - 自动化脚本
│   └── helper.py
├── references/           # 可选 - 参考文档
│   ├── api-guide.md
│   └── examples.md
└── assets/               # 可选 - 资源文件
    └── template.html

SKILL.md 格式 ​

SKILL.md 文件应包含以下部分：

markdown
---
title: skill-name
description: 简要描述技能的功能和触发条件
---

# 技能名称

简要介绍技能的核心能力。

## 何时使用

描述触发该技能的条件。

### 适用场景
### 不适用场景

## 使用方法

说明如何使用该技能完成任务的步骤。

## 配置（如适用）

列出必要的配置项。

关键规则 ​

规则说明
描述要简短Skill 列表中的描述应精炼，完整内容在 SKILL.md 中
触发条件清晰明确说明何时该用、何时不该用
组织有条理按逻辑分段，使用标题和列表
提供示例包含用法示例和提示词模板
链接相关资源引用相关的脚本、文档或其他技能

使用示例 ​

创建新技能 ​

帮我创建一个技能，用于自动化 Jira 项目管理
创建一个新的技能，帮助团队进行代码审查
编写一个技能，集成 Slack 通知功能

改进已有技能 ​

这个技能的组织结构如何优化？
如何改进这个技能的触发条件描述？
帮我为这个技能添加示例和最佳实践

验证技能 ​

检查这个 SKILL.md 文件是否符合规范
验证这个技能是否能被正确触发
测试这个技能的渐进式披露是否有效

渐进式披露规则 ​

技能应遵循渐进式披露原则：

  1. 标题和描述 — 最外层信息，用于触发检测
  2. 主要内容 — 被触发后读取的完整指令
  3. 引用文件 — 按需引用的详细文档和示例
  4. 脚本和资源 — 仅在需要执行时才加载

为什么重要 ​

  • 节省 Token — 不会一次性加载不必要的内容
  • 响应更快 — 减少处理无关信息的时间
  • 上下文精准 — 只包含与当前任务相关的指令

最佳实践 ​

内容编写 ​

  • 使用中文或英文 — 保持语言一致
  • 避免歧义 — 触发条件要精确，避免与其他技能冲突
  • 提供反面示例 — 列出不适用场景同样重要
  • 包含标题层级 — 使用 ##、### 合理分层

文件组织 ​

  • 脚本优先 — 有现成脚本时直接运行，而非重新输入代码
  • 复用模板 — 如有模板文件，基于模板创建而非从零开始
  • 引用不过度 — 只引用直接相关的文件，避免深度追踪

安全考虑 ​

  • 不扫描外部文件 — 技能内容不应引入安全风险
  • 明确工具使用 — 列出技能需要使用的工具权限
  • 避免敏感数据 — 不在技能中硬编码密码或密钥

相关技能 ​

基于 Codex CLI v0.142.5

Made with VitePress