Agent Skills 技能目录Codex 技能发现、安装与分发实战指南【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills本文聚焦 Skills Catalog for CodexGitHub_Trending/skills4/skills的定位与使用方法它是一套面向 AI Agent 的技能目录仓库将“指令、脚本与资源”打包为可复用的 Skill供 Codex 在特定任务中自动发现与调用。读完本文你将掌握 Skill 的三种分级目录结构、在 Codex 中按名称或按 GitHub 路径安装 Skill 的完整命令流程以及 Skill 内部 SKILL.md、agents 元数据与 scripts/references/assets 资源的组织规范并能结合仓库源码理解其安装校验与上下文加载原理。[!IMPORTANT]本仓库已标记为废弃deprecated。官方建议迁移到 OpenAI Plugins 仓库获取当前 Codex skill 与插件示例如需为 Codex 添加自定义 skills请遵循官方“Build plugins”指南中关于创建 skill-only plugin 的说明。本文所述安装与结构原理仍适用于理解 Agent Skills 目录这一经典形态但在生产环境中请以官方最新迁移指引为准。一、仓库概览Agent Skills 是什么根据 README.md 的定义Agent Skills 是“指令、脚本和资源的文件夹”AI Agent 可以自主发现并使用它们来完成特定任务——核心理念是 “Write once, use everywhere”一次编写处处可用。Codex 使用 Skills 来封装团队和个人可以重复完成特定任务的能力。本仓库Skills Catalog for Codex正是这些 Skills 的目录与分发载体。从仓库目录结构看Skills 被分为三个层级对应skills/目录下的三个子目录目录定位是否需要手动安装skills/.system/系统级 Skills随最新版 Codex自动安装否skills/.curated/官方精选curatedSkills是skills/.experimental/实验性 Skills当前仓库快照中为空目录仅作占位是其中.system目录下实际包含skill-installer、skill-creator、plugin-creator、imagegen、openai-docs等系统级 Skill.curated下则有gh-address-comments、playwright、sentry、figma-generate-design、migrate-to-codex、winui-app等精选 Skill每个 Skill 都是一个自包含的目录。二、安装 Skill两种途径与完整命令README 明确了安装规则.system目录中的 Skills 在最新版 Codex 中会自动安装无需手动处理而.curated与.experimental的 Skills 则需要通过 Codex 内置的$skill-installer来安装。2.1 按名称安装 curated Skills默认源为skills/.curated$skill-installer gh-address-comments这是最简洁的用法直接给出 Skill 名称安装器默认从skills/.curated目录查找并安装。2.2 按目录路径安装 experimental Skills$skill-installer install the create-plan skill from the .experimental folder当你需要安装实验性 Skills 时可以用自然语言明确指定.experimental目录下的 Skill 文件夹。2.3 按 GitHub 目录 URL 安装$skill-installer install https://github.com/openai/skills/tree/main/skills/.experimental/create-plan第三种方式支持直接提供 GitHub 仓库的目录 URL适用于从其他仓库安装 Skill。2.4 安装完成后的必要步骤安装完成后重启 Codex以加载新安装的 Skills。这一点在 README.md 中明确标注After installing a skill, restart Codex to pick up new skills.三、源码视角skill-installer 的底层实现原理README 只是入口真正理解安装机制需要深入.system/skill-installer/系统级 Skill 的源码与说明。该 Skill 的元数据在 SKILL.md 中定义--- name: skill-installer description: Install Codex skills into $CODEX_HOME/skills from a curated list or a GitHub repo path. Use when a user asks to list installable skills, install a curated skill, or install a skill from another repo (including private repos). metadata: short-description: Install curated skills from openai/skills or other repos ---它由两个核心 Python 脚本组成均依赖github_utils.py中的 GitHub API 封装3.1 列出可安装 Skillsscripts/list-skills.pylist-skills.py 用于列出仓库中可安装的 Skill其关键行为默认源DEFAULT_REPO openai/skills、DEFAULT_PATH skills/.curated、DEFAULT_REF main——即默认从skills/.curated路径拉取清单安装状态标注通过_installed_skills()读取$CODEX_HOME/skills默认~/.codex/skills下的子目录为已安装的 Skill 添加(already installed)标注文本与 JSON 两种输出默认输出为带编号的文本列表1. skill-1、2. skill-2 (already installed)通过--format json可输出机器可读的 JSON指定其他路径--path skills/.experimental可列出实验性 Skills若路径不存在HTTP 404会明确报错并退出。# 文本列表含已安装标注 scripts/list-skills.py # JSON 格式输出 scripts/list-skills.py --format json # 列出实验性 Skills scripts/list-skills.py --path skills/.experimental3.2 从 GitHub 安装 Skillscripts/install-skill-from-github.pyinstall-skill-from-github.py 是安装动作的真正执行者支持--repo、--url两种来源参数完整参数如下参数含义默认值--repo owner/repo以owner/repo格式指定 GitHub 仓库无--url github_url直接提供 GitHub 目录 URL无--path path [path ...]仓库内 Skill 路径可传多个一次安装多个 Skill无--ref ref指定 git 分支/引用main--dest path指定目标安装目录$CODEX_HOME/skills默认~/.codex/skills--name name覆盖安装后的 Skill 名称多路径时不可用默认取路径 basename无--method auto\|download\|git安装方式自动 / 直接下载 zip / git sparse checkoutauto# 从 curated 列表安装指定 Skill scripts/install-skill-from-github.py --repo openai/skills --path skills/.curated/gh-address-comments # 从 URL 安装含 ref 与路径解析 scripts/install-skill-from-github.py --url https://github.com/openai/skills/tree/main/skills/.experimental/create-plan # 一次安装多个 Skill scripts/install-skill-from-github.py --repo openai/skills --path skills/.curated/a skills/.curated/b该脚本的关键安全与容错逻辑可从源码确认路径校验_validate_relative_path()拒绝绝对路径与..越界路径_validate_skill_name()拒绝包含路径分隔符或./..的名称Skill 结构校验_validate_skill()要求目标目录下必须存在SKILL.md否则报SKILL.md not found in selected skill directory.下载优先、git 兜底auto模式下先用 codeload 下载仓库 zip_download_repo_zip()若遇到 401/403/404 等权限错误自动回退到 git sparse checkout_git_sparse_checkout()先 HTTPS 后 SSHzip 解压时通过_safe_extract_zip()校验所有条目均在目标目录内防止路径穿越攻击目标已存在即中止_copy_skill()与main()均检查Destination already exists不会覆盖已安装的 Skill私有仓库支持可通过已有 git 凭据或可选的环境变量GITHUB_TOKEN/GH_TOKEN访问私有仓库安装目标默认安装到$CODEX_HOME/skills/skill-name$CODEX_HOME未设置时回退到~/.codex/skills多路径安装时分别以路径 basename 命名除非显式传入--name。3.3 目录清单的获取方式注意 SKILL.md 中的说明curated 清单通过 GitHub API 从https://github.com/openai/skills/tree/main/skills/.curated获取.system下的 Skills 已预装无需帮助用户安装若用户坚持要求可以下载后覆盖。所有脚本均需要网络因此在沙箱中运行时需要请求权限升级。四、Skill 的标准结构从仓库实例看 AnatomyREADME 本身没有展开 Skill 内部结构但仓库中每一个 Skill 目录都是活生生的规范示例。以.curated/gh-address-comments/为例gh-address-comments/ ├── SKILL.md # 必需frontmatter Markdown 指令 ├── agents/ │ └── openai.yaml # 推荐UI 元数据列表/芯片展示 ├── scripts/ │ └── fetch_comments.py # 可选可执行脚本 ├── assets/ │ ├── github.png │ └── github-small.svg # 可选输出用资源 └── LICENSE.txt # 每个 Skill 的独立许可这与.system/skill-creator/SKILL.md中定义的 “Anatomy of a Skill” 完全一致其核心规范如下。4.1 SKILL.md必需每个 SKILL.md 由两部分组成YAML frontmatter必须包含name与description两个字段。这是Codex 判断何时触发该 Skill 的唯一依据仅约 100 词常驻上下文因此描述必须清晰全面同时写明“技能做什么”和“何时使用”Markdown body使用指令与流程说明仅在 Skill 被触发后才会加载。以gh-address-comments的 frontmatter 为例--- name: gh-address-comments description: Help address review/issue comments on the open GitHub PR for the current branch using gh CLI; verify gh auth first and prompt the user to authenticate if not logged in. metadata: short-description: Address comments in a GitHub PR review ---body 部分则按步骤组织1. 检查待处理的评论 → 2. 请用户澄清 → 3. 应用修复并给出gh auth status鉴权前置要求等操作性细节。4.2 agents/openai.yaml推荐面向 UI 的元数据用于 Skill 列表与芯片展示。以 gh-address-comments/agents/openai.yaml 为例interface: display_name: GitHub Address Comments short_description: Address comments in a GitHub PR review icon_small: ./assets/github-small.svg icon_large: ./assets/github.png default_prompt: Address all actionable GitHub PR review comments in this branch and summarize the updates.字段包括人类可读的display_name、short_description、default_prompt以及图标资源引用可由skill-creator的scripts/generate_openai_yaml.py或scripts/init_skill.py通过--interface keyvalue确定性生成。4.3 捆绑资源可选资源目录用途何时使用scripts/可执行代码Python/Bash 等要求确定性可靠或反复重写的任务同一段代码被反复重写、需要确定性输出时可执行而无需载入上下文节省 tokenreferences/按需载入上下文的参考文档数据库 schema、API 文档、领域知识等文档较大时保持 SKILL.md 精简仅在 Codex 判定需要时加载大文件1 万词应在 SKILL.md 中给出 grep 检索模式assets/不载入上下文、而是在输出中使用的文件模板、图标、字体、样板代码需要生成带品牌资源、模板的输出时五、Skill 的设计原则从 skill-creator 源码看规范.system/skill-creator/系统级 Skill 是本仓库对“如何编写好 Skill”的完整方法论其 SKILL.md 给出了四条核心原则与完整创建流程。5.1 核心设计原则简洁为王Concise is Key上下文窗口是公共资源Skill 与系统提示、对话历史、其他 Skill 元数据共享上下文。默认假设 Codex 已经足够聪明只补充它没有的信息并质疑每一段内容的 token 成本优先用简洁示例而非冗长解释。设置合适的自由度Degrees of Freedom按任务的脆弱性与可变性匹配具体程度——高风险窄路径用低自由度的固定脚本开放场景用高自由度的纯文本指令介于两者之间用带参数的伪代码/脚本。渐进式披露Progressive Disclosure三级加载体系——元数据namedescription常驻上下文约 100 词→ SKILL.md body 在触发时加载建议 5k 词、500 行以内→ 捆绑资源按需加载脚本可执行而无需读入上下文近乎无限。当 body 接近限制时应拆分到 references 并在 SKILL.md 中明确说明何时读取引用保持一层深度超过 100 行的 reference 文件应在顶部加目录。不做多余内容Skill 内禁止放置 README.md、INSTALLATION_GUIDE.md、CHANGELOG.md 等辅助文档只保留完成任务所必需的信息。5.2 创建流程六步理解 Skill用具体示例明确功能边界与触发场景避免一次问太多问题规划可复用内容分析示例识别需要scripts/、references/、assets/中的哪些资源如“旋转 PDF”→ 存scripts/rotate_pdf.py“品牌规范”→ 存assets/模板“BigQuery 查询”→ 存references/schema.md初始化运行scripts/init_skill.py生成模板骨架scripts/init_skill.py my-skill --path skills/public scripts/init_skill.py my-skill --path skills/public --resources scripts,references scripts/init_skill.py my-skill --path skills/public --resources scripts --examples编辑 Skill先实现可复用资源脚本必须实际运行测试再编写 SKILL.mdfrontmatter 只保留name与descriptionbody 使用祈使/不定式语气校验运行scripts/quick_validate.py path/to/skill-folder检查 YAML frontmatter 格式、必需字段与命名规则失败则修复后重跑迭代在真实任务中使用、观察问题、更新 SKILL.md 或资源、再次测试。5.3 命名规范Skill 命名使用小写字母、数字与连字符名称控制在 64 字符以内优先采用以动词开头的简短短语描述动作当能提升清晰度或触发效果时按工具加命名空间如gh-address-comments、linear-address-issueSkill 文件夹名必须与 skill 名完全一致。六、许可与参与贡献许可每个 Skill 的许可证直接存放在其目录内的LICENSE.txt文件中如 gh-address-comments/LICENSE.txt这是 README 明确规定的查找位置与仓库整体许可证相互独立。贡献参见 contributing.md社区价值观强调友善包容、假设善意、教学相长发现漏洞或对模型输出有疑虑时可通过 securityopenai.com 联系官方。七、总结与实践要点围绕 README.md 这一定位文档结合仓库源码可以得出以下可落地的实践结论目录分层决定安装方式.system自动预装.curated/.experimental需要通过$skill-installer按名称、路径或 GitHub URL 安装安装后必须重启 Codex安装器有完整的安全校验install-skill-from-github.py 会校验相对路径、Skill 名称、SKILL.md 存在性与目标目录冲突并通过 zip 解压安全检查和 download→git sparse checkout 的自动回退保障安装可靠性Skill 是自包含目录SKILL.mdfrontmatter body是唯一触发依据agents/openai.yaml提供 UI 元数据scripts/、references/、assets/按需承载可执行代码、参考文档与输出资源质量由设计原则保证简洁、合适自由度、渐进式披露与禁止冗余文档共同决定了 Skill 在 Codex 上下文窗口中的效率注意迁移状态该仓库当前已标记 deprecated正式使用应转向 OpenAI Plugins 仓库与官方 Build plugins 指南本文内容更适合作为理解 Agent Skills 目录结构与安装机制的参考。【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考