企业官网建设流程全解析

yichen-skills 开发者指南：从 SKILL.md 到脚本，自建一个 AI Agent 技能全流程

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

yichen-skills是一个面向内容创作者的开源 AI Agent 技能仓库，收录了 20 多个可直接安装到 Claude Code / Codex 的 Skill，覆盖内容切片、音视频转写、网页调研、微信数据导出等真实工作流。这篇文章带你以它为范本，从零理解一个 AI Agent 技能的完整构成：SKILL.md 定义行为、scripts/ 提供执行力、references/ 与 tests/ 保障质量，让你也能自建自己的技能。

📁 先看懂：一个 AI Agent 技能的标准目录结构

打开仓库中任意一个技能目录，都会发现高度一致的组织方式。以音视频转写技能为例：

yichen-volc-asr/ ├─ SKILL.md # 技能的"大脑"：行为规则与流程 ├─ agents/ # Agent 界面配置（可选） ├─ scripts/ │ └─ transcribe.py # 真正干活的脚本 └─ references/ # 深度参考文档（按需加载）

• SKILL.md是入口，Agent 靠它判断"什么时候该用我、该怎么用我"
• scripts/存放可执行脚本，是技能的能力边界
• references/放进阶文档，避免每次对话都加载全部内容
• 复杂技能还会带tests/目录做离线验证，例如 yichen-asr/tests/test_contract.py

这种分层结构在 README.zh.md 的"目录结构"一节有完整展示，20 多个技能都遵循同一套范式，非常适合作为新手的模板库。

✍️ 第一步：写好 SKILL.md，给技能装上"大脑"

每个技能的 SKILL.md 开头是一段 YAML frontmatter，只有两个必填字段，却决定了技能能否被正确触发：

--- name: yichen-volc-asr description: 火山引擎音视频转写 + 口播自动粗剪 skill…… 触发场景：用户说"帮我转写这个视频"时使用。 ---

新手最容易踩的坑就在这里，记住三条写法规则：

1. name 与目录名保持一致：Agent 用目录名定位技能，名称对不上就不会加载
2. description 写清"做什么 + 什么时候触发"：既写功能，也写触发词（如"转写视频"、"自动粗剪"），这是自然语言路由的关键
3. 正文写流程与边界，不写废话：比如 yichen-volc-asr/SKILL.md 明确列出"原片不动、不得直接删文件"等安全规则，再给出纯转写、自动粗剪两套标准流程和输出文件清单

一份好的 SKILL.md 应该是"规则手册"，而不是"功能介绍页"。

🔧 第二步：写辅助脚本，给技能长出"双手"

SKILL.md 负责"想"，脚本负责"做"。技能目录下的scripts/就是执行层：

• 转写技能的核心是 yichen-volc-asr/scripts/transcribe.py，支持--dry-run、--no-cache等参数，Agent 只需按 SKILL.md 的用法拼命令即可
• Mac 微信双开技能的 yichen-mac-wechat-dual-open/scripts/wechat_dual_open.py 提供status/create/repair等子命令，状态检查先行、危险操作留给人工确认

写给 Agent 调用的脚本，有两条新手必读的设计原则：

• 参数化入口：把路径、目标 App、Bundle ID 等都做成参数，避免写死个人路径（本仓库明确要求公开版不保留个人绝对路径）
• 安全默认：默认只读、默认不覆盖、删除类操作需显式确认。例如双开脚本的launch命令被刻意禁用，打开应用永远是用户手动完成的步骤

🧩 第三步：补齐 references、agents 与 tests

当技能变复杂后，把细节下沉到子目录是保持 SKILL.md 精简的关键：

• references/：按需加载的深度文档。例如 yichen-unified-search/references/routes.md 集中了各搜索后端的参数与限制，SKILL.md 只在路由命中时才让它读取
• agents/：面向不同 Agent 平台的界面配置，如 yichen-agent-memory/agents/openai.yaml 声明了展示名、简介和默认提示词
• tests/：离线测试守护行为契约。yichen-asr/tests/test_contract.py 直接调用路由脚本断言"纯文本走 Step、需要 SRT 走豆包"，改脚本前先跑测试，改动才不会跑偏

如果技能会持续迭代，建议同时保留一份 README（面向人类）和 SKILL.md（面向 Agent），职责分开互不干扰。

🚀 安装与验证：让技能真正跑起来

写好技能后，验证流程比编写本身更重要：

1. 放入加载路径：把技能目录整体复制到~/.claude/skills/（Claude Code）或~/.agents/skills/（通用 Agents 路径），目录名保持不变
2. 重启会话：新技能通常需要重新加载会话才生效
3. 自然语言触发测试：对 Agent 说出 SKILL.md 里写的触发词，观察是否正确路由
4. 只读差异检查：仓库自带 scripts/compare_installed_skills.py，可以对 Git 已跟踪的技能文件做哈希比对，确认"源码版"和"安装版"一致且不读取任何密钥

需要完整源码做参考时，可以克隆仓库：

git clone https://gitcode.com/gh_mirrors/yi/yichen-skills

⚠️ 常见问题与维护建议

• 技能没触发？检查是否在"当前真实加载路径"、是否重启会话、SKILL.md 的name/description是否正确——这是 README.zh.md 高频 FAQ
• 脚本路径找不到？不同 Agent 安装路径不同，参考双开技能的做法：先定位SKILL.md所在目录再拼相对路径，而不是写死~下的某个位置
• 版本同步怎么管？仓库将本仓库定位为"发布源"，安装目录只是运行副本：修复先改源码、测试通过再安装，不做双向自动覆盖。完整流程见 docs/skill-maintenance.md

最后提醒：本仓库许可为个人学习和非商业使用，公开版不包含任何真实凭据，自建技能时请务必把 Token、Cookie 等敏感配置留在环境变量或私有文件中。

按照"SKILL.md 定规则 → scripts/ 给能力 → references/ 沉细节 → tests/ 守契约"这四步走下来，你就能照着 yichen-skills 的范式，搭建出第一个属于自己的 AI Agent 技能了 🎉

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