企业官网建设流程全解析

如何编写自己的AI编程技能：MiniMax Skills技能开发与贡献完全教程

【免费下载链接】skills项目地址: https://gitcode.com/gh_mirrors/skills18/skills

MiniMax Skills 是一个面向 AI 编程工具的开发技能库，让 Claude Code、Cursor、Codex 等 AI 编程 Agent 获得结构化的生产级开发指导。本教程教你从零编写一个属于自己的AI编程技能（Skill），并顺利提交到社区。你只需要会写 Markdown，就能在 skills/ 目录下创建技能，让 AI 按你的规范工作——这是提升 AI 编程效率最划算的一步。

一、MiniMax Skills 是什么？

MiniMax Skills 采用"技能包（Skill）"的形式：每个技能就是一个目录，内含一份入口文件SKILL.md，AI Agent 在对话中判断到相关意图后，会自动加载该技能并严格按其中的流程执行。

目前仓库已收录 16 个官方与社区技能，覆盖：

完整技能清单可参考中文文档 README_zh.md。

二、克隆仓库：搭建你的技能开发环境

在本地克隆仓库开始开发（一个技能 = 一个目录 = 一份 SKILL.md）：

git clone https://gitcode.com/gh_mirrors/skills18/skills.git

开发前务必通读两份官方规范文档：

• CONTRIBUTING.md —— PR 格式、技能结构要求与开发指南
• .claude/skills/pr-review/SKILL.md —— 自动校验检查与质量审核标准

三、技能的标准目录结构（一分钟看懂）

所有技能都遵循统一布局，这也是审核脚本检查的核心结构：

skills/<skill-name>/ ├── SKILL.md # 必需 —— 带 YAML 头信息的入口文件 ├── references/ # 可选 —— 详细参考资料 │ └── *.md └── scripts/ # 可选 —— 辅助脚本 ├── *.py └── requirements.txt # 若存在 scripts/ 则必需

三条硬性规则（来自 CONTRIBUTING.md）：

1. 📁 目录名即技能标识，必须用小写kebab-case，如gif-sticker-maker
2. ✅SKILL.md是唯一必需文件，其余全部可选
3. ⚠️ 若包含scripts/目录，必须提供requirements.txt

四、编写 SKILL.md：技能的核心入口

SKILL.md由两部分组成：文件顶部的YAML 前置信息（Frontmatter）+ 正文指引。

4.1 前置信息：AI 识别你的技能靠它

--- name: my-skill description: > One-paragraph description. Include trigger conditions so the agent knows when to activate this skill. license: MIT metadata: version: "1.0" category: productivity sources: - Relevant documentation or standards ---

字段说明：

4.2 触发条件写得越准，技能激活越稳

description里的触发条件决定 AI 何时加载你的技能。参考社区技能 skills/vision-analysis/SKILL.md 的写法——它明确列出了触发关键词（analyze、OCR、review…）和触发场景（用户分享图片路径），激活率非常高。

🎯技巧：先想清楚"用户会用什么话术请求这个能力"，把这些话术和文件扩展名写进description，效果立竿见影。

五、辅助资料与脚本：references 和 scripts 怎么写

控制篇幅是关键——技能会被整体加载进 AI 上下文窗口，每一个 token 都有成本：

• 📝 单个.md文件保持聚焦；超长文档拆分成多部分，参考 skills/minimax-docx/references/ 的openxml_encyclopedia_part1/2/3.md拆分方式
• 🚫 不要在 Markdown 里内嵌 base64 图片、完整 API 响应等大块数据
• 🔑严禁硬编码密钥。涉及外部 API 时，指引 AI 从环境变量读取密钥，并在SKILL.md中把环境变量列为前置条件

脚本规范（适用于scripts/目录）：

1. 首行写 shebang（如#!/usr/bin/env python3）
2. 提供requirements.txt声明全部依赖
3. 出错时给出清晰提示，而非裸抛异常堆栈
4. 在SKILL.md或参考资料中写明脚本用法

可参考 skills/gif-sticker-maker/scripts/ 中的 Python 脚本组织方式。

六、提交PR前的完整检查清单

6.1 本地运行自动校验（最重要的一步）

python .claude/skills/pr-review/scripts/validate_skills.py

该脚本会检查（详见 .claude/skills/pr-review/references/structure-rules.md）：

• 每个技能目录都有SKILL.md
• YAML 前置信息可解析、name与目录名一致
• 未检测到硬编码密钥（sk-、AKIA、Bearer Token 等模式）

ERROR 级问题必须清零，WARNING 级（缺license、metadata）建议一并修复。

6.2 PR 规范三要素

新增技能时，记得同步更新 README.md 和 README_zh.md 的技能表格，社区技能 Source 列填Community。

七、新手常犯的 5 个错误

1. ❌name与目录名不一致 —— 校验直接报 ERROR
2. ❌description只写功能不写触发条件 —— 技能激活率低
3. ❌ 与现有技能功能重叠 —— 优先扩展已有技能而非新建，并在 PR 中说明差异
4. ❌ 参考文档过长 —— 撑爆上下文，AI 反而抓不住重点
5. ❌ 忘了同步 README —— 审核时被退回重改

八、审核流程与常见问题

提交 PR 后的流程很清晰：提交 PR → 至少一名维护者审核 → 处理反馈 → 合并。

你还可以让 AI 编程 Agent 用仓库内置的 pr-review 技能先帮你自查一遍。有疑问直接开 issue，维护者乐于解答。

💡最后提醒：技能名称与文件名仅用 ASCII 小写 kebab-case，SKILL.md与代码用英文编写，所有文件保持 UTF-8 编码。

现在，打开仓库，创建你的第一个skills/<your-skill>/SKILL.md，把你的经验变成 AI 的能力吧！

【免费下载链接】skills项目地址: https://gitcode.com/gh_mirrors/skills18/skills