如何从零开发自定义AI技能：zylos-core Skill编写完全指南

在 zylos-core 这个开源 AI Agent 基础设施中，Skill（技能） 是扩展 AI 能力的核心机制——它能让 Claude 或 Codex 掌握你自定义的专业知识、工作流和工具集成。本文是一份从零开始的 AI 技能编写完全指南：你不需要写复杂代码，只需理解 SKILL.md 的结构、Frontmatter 配置和渐进式披露原则，就能在几十分钟内做出自己的第一个自定义 AI 技能。

什么是 Skill：AI 技能的工作原理

可以把 Skill 理解成给 AI 的"上岗培训手册"。一个技能是一个自包含的模块，通常包含：

• 专业工作流：面向特定领域的多步骤操作流程
• 工具集成：如何操作特定文件格式或 API 的说明
• 领域知识：公司内部规范、数据库结构、业务逻辑
• 捆绑资源：可执行脚本、参考文档、输出模板

技能放在项目的技能目录中，例如 skills/scheduler/SKILL.md 中的任务调度技能，就是一个典型的"核心工作流写在 SKILL.md、细节拆到 references/"的范例。

三级加载机制：技能如何节省上下文

zylos-core 的 Skill 采用渐进式披露（Progressive Disclosure） 设计，分三层加载：

层级	内容	何时加载	体积建议
第 1 级	Frontmatter 元数据（name + description）	始终在上下文中	约 100 词
第 2 级	SKILL.md 正文	技能被触发后	小于 5000 词
第 3 级	scripts/、references/、assets/ 捆绑资源	AI 按需读取或执行	无限制

这个设计意味着：description 是技能唯一的"触发器"——AI 靠它判断何时该调用技能；而正文和资源只在需要时才进入上下文。写技能时，第一原则就是简洁：上下文窗口是公共资源，只写 AI 本身不知道的信息。

Skill 目录结构：一个技能的完整解剖

每个技能都由一个必需的 SKILL.md 和可选的捆绑资源组成：

skill-name/
├── SKILL.md          （必需）
│   ├── YAML Frontmatter（必需：name、description）
│   └── Markdown 正文（必需）
└── 捆绑资源（可选）
    ├── scripts/      可执行代码（Node/Bash/Python）
    ├── references/   按需加载进上下文的参考文档
    └── assets/       用于输出的模板、图片、字体等文件

三个资源目录各有分工，选错地方会白白浪费上下文：

• scripts/：需要确定性结果的重复操作。比如"每次都要重写一遍 PDF 旋转代码"，就该沉淀成 scripts/rotate_pdf.py。脚本可以直接执行，不必读进上下文，非常省 token。
• references/：AI 干活时需要查阅的文档——数据库表结构、API 文档、公司政策。只在 AI 判断需要时才加载。
• assets/：不会进入上下文、只用于最终产出的文件，如 PPT 模板、HTML 脚手架、品牌图片。

⚠️ 技能里不要放 README.md、CHANGELOG.md 这类辅助文档——技能只服务于 AI Agent 执行任务，多余文档只会增加干扰。

Frontmatter 配置详解：技能的触发器怎么写

SKILL.md 开头的 YAML 元数据是技能最关键的部分。以 skills/create-skill/SKILL.md 本身为例：

---
name: create-skill
description: Guide for creating effective skills. Use when asked to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.
allowed-tools: Read, Write, Bash, Glob, Grep
---

description 的写法决定技能能否被正确触发，要包含两部分：这个技能做什么 + 什么场景下应该使用它。注意"何时使用"的信息必须写在 description 里，而不是正文——正文只有在触发之后才会被加载。

校验脚本 scripts/validate.js 内置了完整的命名规范，写技能前先记住这几条硬性规则：

• name 必须为 kebab-case（小写字母、数字、连字符），长度不超过 64 字符
• description 不能包含尖括号 < >，长度不超过 1024 字符
• description 中若出现 : 、# 等 YAML 敏感字符，要用引号包裹或改用 >- 折叠块写法
• 只允许官方字段：name、description、allowed-tools、model、context、agent、hooks、license 等

进阶字段示例：

allowed-tools: Read, Grep     # 无需授权提示即可使用的工具
model: sonnet                 # 技能激活时使用的模型
context: fork                 # 在隔离子代理中运行
argument-hint: [args]         # 参数提示

从零创建技能：init-skill.js 五步工作流

zylos-core 内置了完整的技能创建工作流，完整定义见 skills/create-skill/SKILL.md。五个步骤按顺序执行：

第 1 步：用具体例子理解技能。 先问自己：用户会对 AI 说哪句话来触发这个技能？比如做"图片编辑"技能，先想清楚它该支持"去红眼"、"旋转图片"等哪些具体请求。

第 2 步：规划可复用的内容。 逐个分析使用场景，判断哪些东西值得沉淀：反复手写的代码 → scripts/；反复要查的表结构和 API 文档 → references/；反复要复制的模板 → assets/。

第 3 步：初始化技能骨架。 运行初始化脚本 scripts/init-skill.js：

node scripts/init-skill.js my-new-skill

脚本默认在 ~/zylos/.claude/skills/ 下创建目录，也可以 --path 指定其他位置。它会生成带 TODO 占位符的 SKILL.md 模板，并创建 scripts/、references/、assets/ 三个示例目录（用不上的示例文件记得删掉）。

第 4 步：编辑技能。 记住技能是给"另一个 AI 实例"看的，补充它不知道的流程知识和领域细节。写作时始终保持祈使句风格。写完后务必运行校验：

node scripts/validate.js ~/zylos/.claude/skills/my-new-skill

第 5 步：迭代。 在真实任务中使用技能，发现卡壳或低效之处，回到 SKILL.md 或资源文件上修改，再测一遍。

进阶技巧：工作流模式与渐进式披露

正文怎么写：两种经典模式

多步骤任务建议在正文开头给 AI 一个流程总览，两种写法沉淀在 references/workflows.md：

• 顺序工作流：1. 分析表单 → 2. 建立字段映射 → 3. 校验 → 4. 填充 → 5. 验证输出
• 条件工作流：先判断分支——"新建内容？走创建流程；编辑现有内容？走编辑流程"，再分别给出各分支的步骤

如果技能需要稳定、高质量的输出格式（如报告、commit message），模板和示例的写法见 references/output-patterns.md。核心结论：给出输入/输出示例对风格对齐的帮助，远大于文字描述。

控制自由度：窄桥与开阔地

把 AI 想象成在探路：悬崖边的窄桥需要具体护栏（低自由度，给出精确脚本、少参数）；开阔地允许多条路线（高自由度，只给文字指导）。操作越脆弱、越容易出错，约束就越要具体。

拆分大型技能：SKILL.md 保持 500 行以内

当技能支持多个变体或框架时，正文只保留核心工作流和选择指引，变体细节拆进独立的参考文件，并在 SKILL.md 中明确写出"何时去读哪个文件"。例如 cloud-deploy 技能下按 references/aws.md、gcp.md 分文件组织——用户选了 AWS，AI 就只读 aws.md。两条补充准则：参考文件保持一级深度（全部直接从 SKILL.md 链接）；超过 100 行的参考文件在开头放目录。

常见问题：技能不触发怎么办

症状	常见原因	解决方法
技能从不被调用	description 没写清"何时使用"	在 description 中补充具体触发场景和示例说法
validate 报错	name 不是 kebab-case、字段名不在白名单	对照 validate.js 的规则逐项修正
上下文膨胀	正文过长、参考文档与正文重复	细节移入 references/，正文只留流程骨架
输出不稳定	缺少格式约束	按模板模式在正文中给出固定结构或输入/输出示例

总结：zylos-core 技能编写最佳实践清单

📋 回顾一下这份 Skill 编写指南的核心要点：

1. description 是触发器——写清"做什么 + 何时用"，这是技能成败的关键
2. 目录分工明确——scripts 放确定性代码，references 放按需文档，assets 放输出模板
3. 渐进式披露——元数据常驻、正文精炼（< 500 行）、资源按需加载
4. 先初始化后编辑——init-skill.js 生成骨架，validate.js 把关规范
5. 在实战中迭代——每次使用后立刻修补技能，让它越用越聪明

跟着这个流程走，你从零开发的第一个自定义 AI 技能就能顺利上线。想深入源码细节，可以继续研读 skills/create-skill/scripts/init-skill.js 的模板生成逻辑，以及仓库内 skills/scheduler/SKILL.md、skills/health-check/SKILL.md 等官方技能的实际写法——最好的老师就是这些现成的范例。