yichen-skills 开发者指南从 SKILL.md 到脚本自建一个 AI Agent 技能全流程【免费下载链接】yichen-skills项目地址: https://gitcode.com/gh_mirrors/yi/yichen-skillsyichen-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…… 触发场景用户说帮我转写这个视频时使用。 ---新手最容易踩的坑就在这里记住三条写法规则name 与目录名保持一致Agent 用目录名定位技能名称对不上就不会加载description 写清做什么 什么时候触发既写功能也写触发词如转写视频、自动粗剪这是自然语言路由的关键正文写流程与边界不写废话比如 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职责分开互不干扰。 安装与验证让技能真正跑起来写好技能后验证流程比编写本身更重要放入加载路径把技能目录整体复制到~/.claude/skills/Claude Code或~/.agents/skills/通用 Agents 路径目录名保持不变重启会话新技能通常需要重新加载会话才生效自然语言触发测试对 Agent 说出 SKILL.md 里写的触发词观察是否正确路由只读差异检查仓库自带 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考