尧图网站建设 
Gemini CLI 技能工厂skill-creator 内置技能全解——从 SKILL.md 结构、渐进式披露到打包安装的完整工程实践【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cliGemini CLI 通过「Skills技能」机制把特定领域的流程性知识、脚本和参考资料打包注入 Agent而仓库内置的 skill-creator 技能正是官方提供的造技能的技能。本文以 packages/core/src/skills/builtin/skill-creator/SKILL.md 为主体完整梳理技能的设计原则、目录结构、渐进式披露Progressive Disclosure模式与七步创建流程并结合init_skill.cjs、package_skill.cjs、validate_skill.cjs三个内置脚本及skillLoader/skillManager/activate-skill源码实现讲清每一个校验规则与加载机制背后的真实行为。一、技能是什么为通用 Agent 注入入职手册skill-creator 的 SKILL.md 对技能给出的定义是模块化、自包含的包通过提供专业知识、工作流和工具来扩展 Gemini CLI 的能力——可以把它理解为面向特定领域或任务的入职指南onboarding guides把 Gemini CLI 从通用 Agent 变身为具备流程性知识procedural knowledge的专用 Agent。一个技能具体提供四类价值专业化工作流——面向特定领域的多步骤流程工具集成——处理特定文件格式或 API 的操作说明领域专长——企业专有知识、数据 Schema、业务逻辑捆绑资源——面向复杂重复任务的脚本、参考资料和素材。源码视角技能如何被发现、加载与激活文档描述的元数据常驻、正文按需加载并非空谈仓库源码可以逐层印证解析skillLoader.ts 中的FRONTMATTER_REGEX从SKILL.md中切出 frontmatter 与正文两部分parseFrontmatter先尝试 YAML 解析失败时回退到简单的键值解析专门处理 description 中含冒号的情况。loadSkillsFromDir用 glob 匹配SKILL.md和*/SKILL.md两种层级忽略node_modules与.git。发现与优先级skillManager.ts 的discoverSkills按固定优先级合并各来源技能内置技能最低→ 扩展技能 → 用户级技能Storage.getUserSkillsDir()→ 用户.agents/skills别名目录 → 工作区级技能最高且仅在文件夹被信任时加载。同名技能后来者覆盖前者若覆盖了内置技能会打印警告覆盖非内置同名技能则通过coreEvents发出冲突提示。激活activate-skill.ts 是技能触发的实际工具。当模型调用activate_skill时它会校验技能名存在把技能目录加入工作区上下文授予读取捆绑资源的权限然后把技能正文与目录结构一起以如下结构返回给模型activated_skill nameskill-name instructions !-- SKILL.md 正文 -- /instructions available_resources !-- 技能目录的文件树 -- /available_resources /activated_skill这正是 SKILL.md 中使用available_resources部分提供的脚本绝对路径这句话的由来——init/package 脚本执行时所需的路径就是技能被激活后返回的这棵目录树里的绝对路径。此外非内置技能在激活前还会弹出确认卡片展示技能描述与即将共享给模型的目录结构内置技能如 skill-creator 本身则跳过确认直接激活。二、核心设计原则把上下文窗口当作公共资源简洁至上Concise is KeySKILL.md 开篇即声明上下文窗口是公共资源public good技能要与系统提示词、对话历史、其他技能的元数据、用户请求共享这有限空间。默认假设是模型本身已经很聪明只补充模型不具备的上下文。文档要求对每一段内容追问两个问题模型真的需要这段解释吗这个段落值得它消耗的 token 吗并明确优先使用简洁示例而非冗长解释。自由度分级Degrees of Freedom文档提出按任务的脆弱性与变化度匹配指令的具体程度用一个很形象的比喻收尾——模型是在探路带悬崖的窄桥需要具体护栏低自由度开阔原野则允许很多路线高自由度自由度级别形式适用场景高纯文本指令多种做法都有效、决策依赖上下文、靠启发式引导中带参数的伪代码或脚本存在推荐模式、允许一定变化、配置影响行为低具体脚本、极少参数操作脆弱易错、一致性关键、必须按固定顺序执行三、技能解剖一个目录里能放什么、不能放什么目录结构总览每个技能由必需的 SKILL.md与可选的捆绑资源组成skill-name/ ├── SKILL.md (必需) │ ├── YAML frontmatter 元数据 (必需) │ │ ├── name: (必需) │ │ └── description: (必需) │ └── Markdown 指令正文 (必需) └── 捆绑资源 (可选) ├── scripts/ - 可执行代码Node.js/Python/Bash 等 ├── references/ - 按需载入上下文的参考文档 └── assets/ - 用于产出的文件模板、图标、字体等SKILL.md 的两部分frontmatter 与正文FrontmatterYAML只含name和description两个字段。它们是唯一参与何时触发技能判定的信息因此必须清楚、全面地描述技能是什么、何时使用。不要加入任何其他字段文档在更新 SKILL.md一节再次强调。BodyMarkdown使用技能及其捆绑资源的指令仅在技能触发之后才会被加载。这意味着写正文时应聚焦如何做而不是什么时候用。三类捆绑资源的定位差异scripts/可执行代码用于需要确定性可靠、或每次都要重复重写代码的任务。收益是 token 高效、结果确定、可以不读入上下文直接执行。文档特别提出Agentic ErgonomicsAgent 人体工学要求脚本必须输出对 LLM 友好的 stdout——抑制原始 traceback输出清晰简洁的成功/失败信息对长输出分页或截断例如输出Success: First 50 lines of processed file...以防撑爆上下文。注意脚本仍可能被模型读取以便打补丁或做环境适配。仓库中 init_skill.cjs 生成的example_script.cjs模板就是这一规范的示范实现try/catch包裹后成功走process.stdout.write(Success: ...)失败则向 stderr 输出Failure: message并以非零码退出。references/参考文档供模型在工作过程中按需读入上下文包括数据库 Schema、API 文档、领域知识、公司政策、详细工作流指南等。文档给出两条硬建议文件很大10k 词时在 SKILL.md 中写明 grep 搜索模式避免信息重复——同一信息只放在 SKILL.md 或 references 之一细节优先放 referencesSKILL.md 只留核心流程指令保持精简的同时可被发现。assets/输出用素材不读入上下文、直接用于最终产出的文件如品牌 logo、PPT 模板、HTML/React 脚手架、字体文件等。价值在于把产出资源与说明文档分离。技能里不该有什么SKILL.md 明确列出禁止创建的文件README.md、INSTALLATION_GUIDE.md、QUICK_REFERENCE.md、CHANGELOG.md等一切辅助文档。理由很直接技能只应包含 AI Agent 完成手头工作所需的信息创作过程、安装测试步骤、面向人类用户的文档只会带来混乱。渐进式披露Progressive Disclosure三级加载模型这是整个技能体系管理上下文的核心机制元数据name description——常驻上下文约 100 词SKILL.md 正文——技能触发时加载应小于 5k 词、控制在 500 行以内接近上限就拆分文件捆绑资源——按需加载理论上无上限因为脚本可以不读入上下文直接执行。拆分文件时必须在 SKILL.md 中引用并说明何时读它确保读者知道其存在与使用时机。核心原则支持多种变体/框架/选项时SKILL.md 只保留核心工作流与选择指引变体细节拆到独立参考文件。文档给出三个模式模式 1高层指南 参考文件——SKILL.md 只写快速上手与导航具体指南放在 FORMS.md / REFERENCE.md / EXAMPLES.md 中按需加载。模式 2按领域/变体组织——多领域技能如bigquery-skill把 finance/sales/product/marketing 拆到各自文件或多框架技能如cloud-deploy的 aws/gcp/azure 分文件用户问销售指标就只读sales.md选了 AWS 就只读aws.md。模式 3条件化细节——基础内容直接给出高级内容超大文件流式处理、时间戳归一化等用链接指向独立文件仅当用户需要时才读。两条重要约束参考文件保持单层深度全部直接从 SKILL.md 链接不要 A→B→C 的深嵌套超过 100 行的参考文件在开头放目录TOC让模型预览时就能看到全貌。四、技能命名规范SKILL.md 的命名规则与 validate_skill.cjs 第 67 行的正则^[a-z0-9-]$完全对应只用小写字母、数字、连字符把用户给的标题归一化为 hyphen-case如 Plan Mode →plan-mode生成的名称长度小于 64 字符优先使用短小的、动词开头的短语描述动作在有助于清晰表达或触发时按工具加命名空间如gh-address-comments、linear-address-issue;技能文件夹名必须与技能名完全一致。五、七步创建流程技能创建按以下顺序执行仅在明确不适用时才能跳过某步用具体示例理解技能规划可复用的技能内容scripts/references/assets初始化技能运行node init_skill.cjs编辑技能实现资源并撰写 SKILL.md打包技能运行node package_skill.cjs安装并重新加载技能基于真实使用迭代Step 1用具体示例理解技能只有在技能的使用模式已经清晰理解时才跳过此步——即便为已有技能迭代它仍有价值。理解来源可以是用户直接给的示例也可以是生成后经用户确认的示例。以构建 image-editor 技能为例文档给出了应当追问的问题样本这个技能要支持哪些功能编辑、旋转还有别的吗能举几个这个技能会被使用的例子吗我想象用户会说去掉这张照片的红眼或旋转这张图还有别的用法吗用户说什么样的话应该触发这个技能同时警告避免审讯式循环一次最多问一两个澄清问题偏向行动——基于初步理解先提出一份具体的功能/示例清单再请用户修订。当对技能应支持的功能有清晰感觉时此步结束。Step 2规划可复用内容把每个具体示例过一遍两问从零开始如何执行这个示例重复执行这些工作流时哪些脚本、参考、素材会派上用场文档给出三个分析范例pdf-editor处理帮我旋转这个 PDF→ 每次都要重写同一段旋转代码 → 存入scripts/rotate_pdf.cjsfrontend-webapp-builder处理给我写个 todo app→ 每次都写同样的 HTML/React 样板 → 存入assets/hello-world/模板目录big-query处理今天多少用户登录了→ 每次都要重新发现表结构与关系 → 存入references/schema.md。对每个示例做此分析后产出一份要包含的可复用资源清单。Step 3初始化技能只有当技能尚不存在时才走这步已存在、只需迭代或打包时直接进入下一步。新建技能时始终运行init_skill.cjsnode path-to-skill-creator/scripts/init_skill.cjs skill-name --path output-directory从 init_skill.cjs 源码看该脚本做了以下事情参数校验位置参数顺序必须是skill-name --path path否则打印用法并以退出码 1 结束安全防御技能名不允许包含路径分隔符并二次校验解析后的技能目录确实位于--path之内防止路径穿越目标目录已存在则报错退出创建技能目录及scripts/、references/、assets/三个子目录生成带正确 frontmatter 和 TODO 占位符的 SKILL.md 模板其中Structuring This Skill一节预置了 Workflow-Based / Task-Based / Reference-Guidelines / Capabilities-Based 四种常见正文结构供选择并要求完成后删除该节写入示例文件scripts/example_script.cjs以0o755权限写入即可执行、references/example_reference.md、assets/example_asset.txt。初始化完成后按需定制或删除生成的 SKILL.md 与示例文件——多数技能并不需要全部三类资源。Step 4编辑技能编辑时要记住技能是写给另一个 Gemini CLI 实例用的。要包含对另一个实例有益且非显然的信息——流程性知识、领域细节、可复用资产。SKILL.md 正文还提到可参考references/workflows.md顺序工作流与条件逻辑与references/output-patterns.md模板与示例模式两份设计模式指南。实现顺序上先做可复用内容scripts/references/assets 文件这一步可能需要用户输入例如brand-guidelines技能需要用户提供的品牌素材或文档。新增脚本必须实际运行测试确认无 bug、输出符合预期脚本较多时测试代表性样本即可。最后删除技能用不到的示例文件与目录。Frontmatter 写法name技能名description技能的主要触发机制帮助模型判断何时使用。要求同时写明技能做什么 具体的触发时机/上下文必须是单行字符串如description: Data ingestion...引号可选所有何时使用信息放在这里不要放正文——正文只在触发后才加载正文里的 When to Use This Skill 章节对触发毫无帮助文档示例description: Data ingestion, cleaning, and transformation for tabular data. Use when Gemini CLI needs to work with CSV/TSV files to analyze large datasets, normalize schemas, or merge sources.frontmatter 中不要出现name与description之外的任何字段。Body 写法用祈使句/不定式形式撰写使用技能及其捆绑资源的指令。Step 5打包技能开发完成后必须打包成可分发的.skill文件本质是带.skill扩展名的 zip。打包前会自动先做校验node path-to-skill-creator/scripts/package_skill.cjs path/to/skill-folder可选地指定输出目录node path-to-skill-creator/scripts/package_skill.cjs path/to/skill-folder ./dist从 package_skill.cjs 源码看其完整行为参数中若包含..直接以路径穿越报错退出先调用validateSkill校验校验失败validfalse或以 TODO 警告形式返回时都会退出码 1 且不产出任何包要求先修复再重跑校验通过后在技能目录内执行zip -r output-dir/skill-name.skill .cwd 设为技能目录保证包内是SKILL.md而非skill-name/SKILL.md的嵌套结构若系统没有zip命令Windows 回退到 PowerShellCompress-Archive先压成.zip再改名类 Unix 系统回退到tar -a -c --formatzip成功后打印包的最终路径。打包产出的文件以技能命名如my-skill.skill包含全部文件并保持目录结构以供分发。Step 6安装与重新加载打包完成后询问用户安装到哪个作用域然后立即用run_shell_command执行工作区当前文件夹workspace scopegemini skills install path/to/skill-name.skill --scope workspace用户级user scopegemini skills install path/to/skill-name.skill --scope user关键约束安装完成后必须告知用户他们需要在自己的交互式 Gemini CLI 会话中手动执行/skills reload才能启用新技能随后可用/skills list验证安装。文档特别强调Agent 自己不能代为执行/skills reload它只能在交互式实例中由用户完成不要替用户尝试运行。Step 7迭代测试后用户常会要求改进且往往发生在刚用过技能、对表现记忆还热乎的时候。迭代循环是在真实任务上使用技能 → 注意到挣扎点或低效之处 → 判断 SKILL.md 或捆绑资源应如何更新 → 实施修改并再次测试。六、校验规则速查validate_skill.cjs 到底检查什么validate_skill.cjs 既是独立命令node validate_skill.cjs skill_directory同样拒绝含..的路径也是打包流程的内部前置步骤。把源码逐条翻译成校验清单#检查项失败结果1路径存在且为目录❌Path is not a directory2目录下存在SKILL.md❌SKILL.md not found3文件以---开头且能切出 frontmatter 段❌No YAML frontmatter found/Invalid frontmatter format4frontmatter 含name❌Missing name in frontmatter5frontmatter 含单行description支持引号包裹含换行直接判负❌Description must be a single-line string/no newlines6name匹配^[a-z0-9-]$hyphen-case❌Name ... should be hyphen-case7description长度 ≤ 1024 字符❌Description is too long (max 1024)8全目录扫描跳过node_modules、.git、__pycache__任何文件中不含字面量TODO:⚠️ 判定valid: true但附带warning: Found unresolved TODO in file打包时该警告会阻止出包注意第 8 条的微妙设计TODO 不算致命错误技能结构上有效但打包脚本会把 warning 当作拦截条件提示Please resolve all TODOs before packaging。这与init_skill.cjs模板中大量TODO:占位符形成闭环——脚手架保证你一开始必然带 TODO校验器保证你带着 TODO 发不出去。七、端到端验证仓库如何测试这条流水线仓库自带一个集成测试 integration-tests/skill-creator-scripts.test.ts把初始化 → 校验 → 打包完整跑了一遍可视为本流程的权威验收标准在临时目录执行init_skill.cjs e2e-test-skill --path tmp断言技能目录、SKILL.md、scripts/example_script.cjs均存在立即运行validate_skill.cjs期望输出包含⚠️ Found unresolved TODO模板必然带 TODO此时运行package_skill.cjs期望失败被 TODO 拦截全局替换掉 SKILL.md 与示例脚本里的所有TODO:模式后再次校验期望输出Skill is valid!重新打包断言tmp/e2e-test-skill.skill生成用unzip -l不可用时回退tar -tf列出包内容断言含SKILL.md且不含e2e-test-skill/SKILL.md——即验证 zip 是在目录内打包、没有多套一层父目录。八、小结skill-creator 的价值在于把写好一个技能从凭感觉变成有工程约束的流程frontmatter 单行 description 是唯一的触发面对应skillLoader的解析与activate-skill的元数据注入正文与资源通过三级渐进式披露控制上下文成本命名与结构由validate_skill.cjs硬性把关.skill包由package_skill.cjs在通过校验后才产出最终经gemini skills install落位到 workspace 或 user 作用域——而这两条安装路径正对应skillManager.discoverSkills中用户目录与工作区目录两个发现源。按七步流程走一遍并用仓库自带 e2e 测试的断言作为交付前的最后核对清单就能产出结构合规、上下文经济、可分发的 Gemini CLI 技能。【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Gemini CLI 技能工厂：skill-creator 内置技能全解——从 SKILL.md 结构、渐进式披露到打包安装的完整工程实践
Gemini CLI 技能工厂skill-creator 内置技能全解——从 SKILL.md 结构、渐进式披露到打包安装的完整工程实践【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cliGemini CLI 通过「Skills技能」机制把特定领域的流程性知识、脚本和参考资料打包注入 Agent而仓库内置的 skill-creator 技能正是官方提供的造技能的技能。本文以 packages/core/src/skills/builtin/skill-creator/SKILL.md 为主体完整梳理技能的设计原则、目录结构、渐进式披露Progressive Disclosure模式与七步创建流程并结合init_skill.cjs、package_skill.cjs、validate_skill.cjs三个内置脚本及skillLoader/skillManager/activate-skill源码实现讲清每一个校验规则与加载机制背后的真实行为。一、技能是什么为通用 Agent 注入入职手册skill-creator 的 SKILL.md 对技能给出的定义是模块化、自包含的包通过提供专业知识、工作流和工具来扩展 Gemini CLI 的能力——可以把它理解为面向特定领域或任务的入职指南onboarding guides把 Gemini CLI 从通用 Agent 变身为具备流程性知识procedural knowledge的专用 Agent。一个技能具体提供四类价值专业化工作流——面向特定领域的多步骤流程工具集成——处理特定文件格式或 API 的操作说明领域专长——企业专有知识、数据 Schema、业务逻辑捆绑资源——面向复杂重复任务的脚本、参考资料和素材。源码视角技能如何被发现、加载与激活文档描述的元数据常驻、正文按需加载并非空谈仓库源码可以逐层印证解析skillLoader.ts 中的FRONTMATTER_REGEX从SKILL.md中切出 frontmatter 与正文两部分parseFrontmatter先尝试 YAML 解析失败时回退到简单的键值解析专门处理 description 中含冒号的情况。loadSkillsFromDir用 glob 匹配SKILL.md和*/SKILL.md两种层级忽略node_modules与.git。发现与优先级skillManager.ts 的discoverSkills按固定优先级合并各来源技能内置技能最低→ 扩展技能 → 用户级技能Storage.getUserSkillsDir()→ 用户.agents/skills别名目录 → 工作区级技能最高且仅在文件夹被信任时加载。同名技能后来者覆盖前者若覆盖了内置技能会打印警告覆盖非内置同名技能则通过coreEvents发出冲突提示。激活activate-skill.ts 是技能触发的实际工具。当模型调用activate_skill时它会校验技能名存在把技能目录加入工作区上下文授予读取捆绑资源的权限然后把技能正文与目录结构一起以如下结构返回给模型activated_skill nameskill-name instructions !-- SKILL.md 正文 -- /instructions available_resources !-- 技能目录的文件树 -- /available_resources /activated_skill这正是 SKILL.md 中使用available_resources部分提供的脚本绝对路径这句话的由来——init/package 脚本执行时所需的路径就是技能被激活后返回的这棵目录树里的绝对路径。此外非内置技能在激活前还会弹出确认卡片展示技能描述与即将共享给模型的目录结构内置技能如 skill-creator 本身则跳过确认直接激活。二、核心设计原则把上下文窗口当作公共资源简洁至上Concise is KeySKILL.md 开篇即声明上下文窗口是公共资源public good技能要与系统提示词、对话历史、其他技能的元数据、用户请求共享这有限空间。默认假设是模型本身已经很聪明只补充模型不具备的上下文。文档要求对每一段内容追问两个问题模型真的需要这段解释吗这个段落值得它消耗的 token 吗并明确优先使用简洁示例而非冗长解释。自由度分级Degrees of Freedom文档提出按任务的脆弱性与变化度匹配指令的具体程度用一个很形象的比喻收尾——模型是在探路带悬崖的窄桥需要具体护栏低自由度开阔原野则允许很多路线高自由度自由度级别形式适用场景高纯文本指令多种做法都有效、决策依赖上下文、靠启发式引导中带参数的伪代码或脚本存在推荐模式、允许一定变化、配置影响行为低具体脚本、极少参数操作脆弱易错、一致性关键、必须按固定顺序执行三、技能解剖一个目录里能放什么、不能放什么目录结构总览每个技能由必需的 SKILL.md与可选的捆绑资源组成skill-name/ ├── SKILL.md (必需) │ ├── YAML frontmatter 元数据 (必需) │ │ ├── name: (必需) │ │ └── description: (必需) │ └── Markdown 指令正文 (必需) └── 捆绑资源 (可选) ├── scripts/ - 可执行代码Node.js/Python/Bash 等 ├── references/ - 按需载入上下文的参考文档 └── assets/ - 用于产出的文件模板、图标、字体等SKILL.md 的两部分frontmatter 与正文FrontmatterYAML只含name和description两个字段。它们是唯一参与何时触发技能判定的信息因此必须清楚、全面地描述技能是什么、何时使用。不要加入任何其他字段文档在更新 SKILL.md一节再次强调。BodyMarkdown使用技能及其捆绑资源的指令仅在技能触发之后才会被加载。这意味着写正文时应聚焦如何做而不是什么时候用。三类捆绑资源的定位差异scripts/可执行代码用于需要确定性可靠、或每次都要重复重写代码的任务。收益是 token 高效、结果确定、可以不读入上下文直接执行。文档特别提出Agentic ErgonomicsAgent 人体工学要求脚本必须输出对 LLM 友好的 stdout——抑制原始 traceback输出清晰简洁的成功/失败信息对长输出分页或截断例如输出Success: First 50 lines of processed file...以防撑爆上下文。注意脚本仍可能被模型读取以便打补丁或做环境适配。仓库中 init_skill.cjs 生成的example_script.cjs模板就是这一规范的示范实现try/catch包裹后成功走process.stdout.write(Success: ...)失败则向 stderr 输出Failure: message并以非零码退出。references/参考文档供模型在工作过程中按需读入上下文包括数据库 Schema、API 文档、领域知识、公司政策、详细工作流指南等。文档给出两条硬建议文件很大10k 词时在 SKILL.md 中写明 grep 搜索模式避免信息重复——同一信息只放在 SKILL.md 或 references 之一细节优先放 referencesSKILL.md 只留核心流程指令保持精简的同时可被发现。assets/输出用素材不读入上下文、直接用于最终产出的文件如品牌 logo、PPT 模板、HTML/React 脚手架、字体文件等。价值在于把产出资源与说明文档分离。技能里不该有什么SKILL.md 明确列出禁止创建的文件README.md、INSTALLATION_GUIDE.md、QUICK_REFERENCE.md、CHANGELOG.md等一切辅助文档。理由很直接技能只应包含 AI Agent 完成手头工作所需的信息创作过程、安装测试步骤、面向人类用户的文档只会带来混乱。渐进式披露Progressive Disclosure三级加载模型这是整个技能体系管理上下文的核心机制元数据name description——常驻上下文约 100 词SKILL.md 正文——技能触发时加载应小于 5k 词、控制在 500 行以内接近上限就拆分文件捆绑资源——按需加载理论上无上限因为脚本可以不读入上下文直接执行。拆分文件时必须在 SKILL.md 中引用并说明何时读它确保读者知道其存在与使用时机。核心原则支持多种变体/框架/选项时SKILL.md 只保留核心工作流与选择指引变体细节拆到独立参考文件。文档给出三个模式模式 1高层指南 参考文件——SKILL.md 只写快速上手与导航具体指南放在 FORMS.md / REFERENCE.md / EXAMPLES.md 中按需加载。模式 2按领域/变体组织——多领域技能如bigquery-skill把 finance/sales/product/marketing 拆到各自文件或多框架技能如cloud-deploy的 aws/gcp/azure 分文件用户问销售指标就只读sales.md选了 AWS 就只读aws.md。模式 3条件化细节——基础内容直接给出高级内容超大文件流式处理、时间戳归一化等用链接指向独立文件仅当用户需要时才读。两条重要约束参考文件保持单层深度全部直接从 SKILL.md 链接不要 A→B→C 的深嵌套超过 100 行的参考文件在开头放目录TOC让模型预览时就能看到全貌。四、技能命名规范SKILL.md 的命名规则与 validate_skill.cjs 第 67 行的正则^[a-z0-9-]$完全对应只用小写字母、数字、连字符把用户给的标题归一化为 hyphen-case如 Plan Mode →plan-mode生成的名称长度小于 64 字符优先使用短小的、动词开头的短语描述动作在有助于清晰表达或触发时按工具加命名空间如gh-address-comments、linear-address-issue;技能文件夹名必须与技能名完全一致。五、七步创建流程技能创建按以下顺序执行仅在明确不适用时才能跳过某步用具体示例理解技能规划可复用的技能内容scripts/references/assets初始化技能运行node init_skill.cjs编辑技能实现资源并撰写 SKILL.md打包技能运行node package_skill.cjs安装并重新加载技能基于真实使用迭代Step 1用具体示例理解技能只有在技能的使用模式已经清晰理解时才跳过此步——即便为已有技能迭代它仍有价值。理解来源可以是用户直接给的示例也可以是生成后经用户确认的示例。以构建 image-editor 技能为例文档给出了应当追问的问题样本这个技能要支持哪些功能编辑、旋转还有别的吗能举几个这个技能会被使用的例子吗我想象用户会说去掉这张照片的红眼或旋转这张图还有别的用法吗用户说什么样的话应该触发这个技能同时警告避免审讯式循环一次最多问一两个澄清问题偏向行动——基于初步理解先提出一份具体的功能/示例清单再请用户修订。当对技能应支持的功能有清晰感觉时此步结束。Step 2规划可复用内容把每个具体示例过一遍两问从零开始如何执行这个示例重复执行这些工作流时哪些脚本、参考、素材会派上用场文档给出三个分析范例pdf-editor处理帮我旋转这个 PDF→ 每次都要重写同一段旋转代码 → 存入scripts/rotate_pdf.cjsfrontend-webapp-builder处理给我写个 todo app→ 每次都写同样的 HTML/React 样板 → 存入assets/hello-world/模板目录big-query处理今天多少用户登录了→ 每次都要重新发现表结构与关系 → 存入references/schema.md。对每个示例做此分析后产出一份要包含的可复用资源清单。Step 3初始化技能只有当技能尚不存在时才走这步已存在、只需迭代或打包时直接进入下一步。新建技能时始终运行init_skill.cjsnode path-to-skill-creator/scripts/init_skill.cjs skill-name --path output-directory从 init_skill.cjs 源码看该脚本做了以下事情参数校验位置参数顺序必须是skill-name --path path否则打印用法并以退出码 1 结束安全防御技能名不允许包含路径分隔符并二次校验解析后的技能目录确实位于--path之内防止路径穿越目标目录已存在则报错退出创建技能目录及scripts/、references/、assets/三个子目录生成带正确 frontmatter 和 TODO 占位符的 SKILL.md 模板其中Structuring This Skill一节预置了 Workflow-Based / Task-Based / Reference-Guidelines / Capabilities-Based 四种常见正文结构供选择并要求完成后删除该节写入示例文件scripts/example_script.cjs以0o755权限写入即可执行、references/example_reference.md、assets/example_asset.txt。初始化完成后按需定制或删除生成的 SKILL.md 与示例文件——多数技能并不需要全部三类资源。Step 4编辑技能编辑时要记住技能是写给另一个 Gemini CLI 实例用的。要包含对另一个实例有益且非显然的信息——流程性知识、领域细节、可复用资产。SKILL.md 正文还提到可参考references/workflows.md顺序工作流与条件逻辑与references/output-patterns.md模板与示例模式两份设计模式指南。实现顺序上先做可复用内容scripts/references/assets 文件这一步可能需要用户输入例如brand-guidelines技能需要用户提供的品牌素材或文档。新增脚本必须实际运行测试确认无 bug、输出符合预期脚本较多时测试代表性样本即可。最后删除技能用不到的示例文件与目录。Frontmatter 写法name技能名description技能的主要触发机制帮助模型判断何时使用。要求同时写明技能做什么 具体的触发时机/上下文必须是单行字符串如description: Data ingestion...引号可选所有何时使用信息放在这里不要放正文——正文只在触发后才加载正文里的 When to Use This Skill 章节对触发毫无帮助文档示例description: Data ingestion, cleaning, and transformation for tabular data. Use when Gemini CLI needs to work with CSV/TSV files to analyze large datasets, normalize schemas, or merge sources.frontmatter 中不要出现name与description之外的任何字段。Body 写法用祈使句/不定式形式撰写使用技能及其捆绑资源的指令。Step 5打包技能开发完成后必须打包成可分发的.skill文件本质是带.skill扩展名的 zip。打包前会自动先做校验node path-to-skill-creator/scripts/package_skill.cjs path/to/skill-folder可选地指定输出目录node path-to-skill-creator/scripts/package_skill.cjs path/to/skill-folder ./dist从 package_skill.cjs 源码看其完整行为参数中若包含..直接以路径穿越报错退出先调用validateSkill校验校验失败validfalse或以 TODO 警告形式返回时都会退出码 1 且不产出任何包要求先修复再重跑校验通过后在技能目录内执行zip -r output-dir/skill-name.skill .cwd 设为技能目录保证包内是SKILL.md而非skill-name/SKILL.md的嵌套结构若系统没有zip命令Windows 回退到 PowerShellCompress-Archive先压成.zip再改名类 Unix 系统回退到tar -a -c --formatzip成功后打印包的最终路径。打包产出的文件以技能命名如my-skill.skill包含全部文件并保持目录结构以供分发。Step 6安装与重新加载打包完成后询问用户安装到哪个作用域然后立即用run_shell_command执行工作区当前文件夹workspace scopegemini skills install path/to/skill-name.skill --scope workspace用户级user scopegemini skills install path/to/skill-name.skill --scope user关键约束安装完成后必须告知用户他们需要在自己的交互式 Gemini CLI 会话中手动执行/skills reload才能启用新技能随后可用/skills list验证安装。文档特别强调Agent 自己不能代为执行/skills reload它只能在交互式实例中由用户完成不要替用户尝试运行。Step 7迭代测试后用户常会要求改进且往往发生在刚用过技能、对表现记忆还热乎的时候。迭代循环是在真实任务上使用技能 → 注意到挣扎点或低效之处 → 判断 SKILL.md 或捆绑资源应如何更新 → 实施修改并再次测试。六、校验规则速查validate_skill.cjs 到底检查什么validate_skill.cjs 既是独立命令node validate_skill.cjs skill_directory同样拒绝含..的路径也是打包流程的内部前置步骤。把源码逐条翻译成校验清单#检查项失败结果1路径存在且为目录❌Path is not a directory2目录下存在SKILL.md❌SKILL.md not found3文件以---开头且能切出 frontmatter 段❌No YAML frontmatter found/Invalid frontmatter format4frontmatter 含name❌Missing name in frontmatter5frontmatter 含单行description支持引号包裹含换行直接判负❌Description must be a single-line string/no newlines6name匹配^[a-z0-9-]$hyphen-case❌Name ... should be hyphen-case7description长度 ≤ 1024 字符❌Description is too long (max 1024)8全目录扫描跳过node_modules、.git、__pycache__任何文件中不含字面量TODO:⚠️ 判定valid: true但附带warning: Found unresolved TODO in file打包时该警告会阻止出包注意第 8 条的微妙设计TODO 不算致命错误技能结构上有效但打包脚本会把 warning 当作拦截条件提示Please resolve all TODOs before packaging。这与init_skill.cjs模板中大量TODO:占位符形成闭环——脚手架保证你一开始必然带 TODO校验器保证你带着 TODO 发不出去。七、端到端验证仓库如何测试这条流水线仓库自带一个集成测试 integration-tests/skill-creator-scripts.test.ts把初始化 → 校验 → 打包完整跑了一遍可视为本流程的权威验收标准在临时目录执行init_skill.cjs e2e-test-skill --path tmp断言技能目录、SKILL.md、scripts/example_script.cjs均存在立即运行validate_skill.cjs期望输出包含⚠️ Found unresolved TODO模板必然带 TODO此时运行package_skill.cjs期望失败被 TODO 拦截全局替换掉 SKILL.md 与示例脚本里的所有TODO:模式后再次校验期望输出Skill is valid!重新打包断言tmp/e2e-test-skill.skill生成用unzip -l不可用时回退tar -tf列出包内容断言含SKILL.md且不含e2e-test-skill/SKILL.md——即验证 zip 是在目录内打包、没有多套一层父目录。八、小结skill-creator 的价值在于把写好一个技能从凭感觉变成有工程约束的流程frontmatter 单行 description 是唯一的触发面对应skillLoader的解析与activate-skill的元数据注入正文与资源通过三级渐进式披露控制上下文成本命名与结构由validate_skill.cjs硬性把关.skill包由package_skill.cjs在通过校验后才产出最终经gemini skills install落位到 workspace 或 user 作用域——而这两条安装路径正对应skillManager.discoverSkills中用户目录与工作区目录两个发现源。按七步流程走一遍并用仓库自带 e2e 测试的断言作为交付前的最后核对清单就能产出结构合规、上下文经济、可分发的 Gemini CLI 技能。【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考