如何编写你自己的Agent Skill：基于second-brain-os的5个SKILL.md实战技巧

【免费下载链接】second-brain-osAn AI second brain that maintains itself. Full guide, starter vault, agent skills and scripts for a self-organizing knowledge base in Claude Code and Obsidian.项目地址https://gitcode.com/gh_mirrors/se/second-brain-os点击查看免费下载second-brain-os是一个会用 AI 自我维护的第二大脑项目内置了 18 个开箱即用的 Agent Skill纯SKILL.md文件配合 72 个斜杠命令让 Claude Code 自动维护一个会自我组织的 Obsidian 知识库。这篇文章带你读懂这些 Skill 背后的编写方法——学完 5 个实战技巧你就能为自己写出第一个SKILL.md。一、先判断什么任务值得写成 Agent Skill不是每个任务都值得沉淀成一个 Skill。second-brain-os 官方给出的判断标准只有三条Skills 与命令指南 的原文是一个值得写的 Skill 有三个特质你反复做这件事、你对做法有观点、而且这些观点不显然到模型无法自己猜到。反过来以下任务不值得写一次性任务做完就不做了做法众所周知、模型默认就会做好的任务只需要改个参数就能覆盖的变体那应该做成 Command见文末。二、SKILL.md 完整结构frontmatter 五段式正文每个 Skill 都是一个目录加一个文件例如 skills/second-brain-ingest/SKILL.md。文件分两部分1. YAML frontmattername 和 description--- name: my-skill-name description: - 这个 Skill 做什么。什么时候该用它——写得大胆、主动因为智能体会 少触发 Skill。不要用于哪些场景把诱人的近似场景明确排除。 ---字段作用nameSkill 名称与所在目录名保持一致description智能体判断是否加载本 Skill的唯一依据写法见技巧 3其中-是 YAML 的块标量语法表示多行文本合并成一段在仓库的 18 个 Skill 中全部沿用。2. 正文五段式结构官方推荐的结构骨架docs/06-agents/skills-and-commands.md小节写什么# 标题 开篇段这个 Skill 为什么存在它防止什么失败。这是后面所有规则没覆盖时的评判标准## Core rule一条不可协商的底线规则一两句话## Workflow编号步骤智能体每一步做什么## Output format固定的输出模板方便人一眼验收## Calibration失败模式与灰度校准太激进会怎样、太保守会怎样## Example一对具体的输入 → 输出照着能对三、技巧 1description 写得pushy把触发场景写全官方直言description 写得 pushy主动因为智能体天生会少触发 Skill。看 second-brain-ingest 的 frontmatter 是怎么写的它其实包含三层信息做什么把raw/里的原始素材变成带链接的 wiki 页面触发词清单用户把文件丢进raw/、粘贴文章/转录稿/PDF、说 ingest this、add this to my second brain、process raw 时都要用——即使用户没有点名这个命令明确禁区不用于回答 vault 里的问题、不用于 lint 修复、不用于编辑用户手写的笔记。第 3 点最容易忽略。Skill 之间会抢活ingest 的 description 里划出不要用于回答问题query 的 description 里才敢写任何问题都该从你自己的笔记里回答。每个 Skill 把相邻场景排除干净触发才稳定。四、技巧 2用防止什么失败开头而不是罗列规则正文第一行不是规则而是一段这个 Skill 为什么存在。对比两个真实开篇ingestsecond-brain-ingest/SKILL.md只写总结页面的摄入会让 vault 只长大、不变聪明。全部价值在后半程把新素材和已有内容连起来。querysecond-brain-query/SKILL.md悄悄回退到通用知识的查询是这个系统能做出的最有害行为。官方解释得很直白规则覆盖你想到的情况原因覆盖剩下的情况。这也是官方反复强调的解释 why原则docs/06-agents/skills-and-commands.md永远不要覆盖矛盾会被字面执行在边缘情况上翻车而永远不要覆盖矛盾因为你相信过什么的轨迹正是这个 vault 区别于搜索引擎的东西能泛化到从没有描述过的场景。没有理由的 NEVER通常说明解释缺失。五、技巧 3Core rule 写成一条带边界的底线Core rule 只写一条但要具体到能当边界。三个实例SkillCore ruleingest没有建立链接就不算摄入完成每次运行结束时新页面必须双向连接到已有页面lintsecond-brain-lint/SKILL.md先报告再修复机械问题自动修但未经确认绝不删除或合并任何页面——因为用户可能手写过它metricssecond-brain-metrics/SKILL.md只记录四个数字追加到带日期的日志并与上次对比永远不用页面数或字数Workflow 紧随其后用编号步骤展开每一步以加粗动词领起。ingest 的 Workflow 是教科书式的示范second-brain-ingest/SKILL.md先完整读完源文件再动笔 →先查已有页面向空 vault 摄入和向 300 页的 vault 摄入是两份不同的工作→ 写源页面 → 拆概念与实体 →双向加链接→ 同一次运行内更新index.md和log.md→ 汇报。Output format 则是一个固定模板让每次运行的产出可被肉眼验收Ingested: source name New pages: n (list) Updated pages: n (list) Links added: n Contradictions found: none | description Gaps created: list of linked pages that do not exist yet六、技巧 4Calibration 写失败模式Example 写可对照的一对Calibration专门回答规则没覆盖的灰度问题——通常会指出最常见的失败方向。例如 ingest 的校准second-brain-ingest/SKILL.md过度提取是常见失败一篇文章拆出十个薄页面每个只是复述段落。一个来源通常只产出一到三个值得独立成页的概念。Example给一对具体输入输出用户把一篇关于 LLM wiki 的文章丢进raw/vault 里已有 Obsidian 和 Claude Code 两个页面 → 产出一篇源页面、一个新概念页、一个实体页、两个已有页面的更新、11 条新链接并更新 index 与 log。有了这两节Skill 才不只是流程说明书而是一份手感说明。七、技巧 5Skill 管行为Command 管入口git 管版本second-brain-os 把 18 个 Skill 放在 skills/、72 个 Command 放在 commands/两者的分工值得直接抄作业Skill 行为教会智能体一套可重复的做法在相关时自动加载Command 入口一个薄文件指向某个 Skill 并设定作用范围。看 commands/ingest.md 全文只有三行有效内容一句任务描述 一句 Follow thesecond-brain-ingestskill.。这就是官方说比例是刻意的docs/06-agents/skills-and-commands.md行为集中在少数写好的 Skill 里Command 很廉价没必要让用户记住怎么措辞每周都要做的请求。维护建议同样来自官方文档随 vault 版本化把 Skill 装进 vault 的.claude/skills/团队共享或装到全局~/.claude/skills/个人使用skills/README.md 给出了两种安装方式用真实案例测过再上自动化官方建议用三四个真实案例测试 Skill再交给定时任务——每晚自动跑的 Skill 里的一个缺陷一年后会变成三百页页面的缺陷质量变了先查 diffSkill 在 git 里输出质量变化时Skill 的 diff 是第一个要查的地方。八、照着抄18 个现成 Skill 是最佳教材用途Skill 目录摄入源文件skills/second-brain-ingest从 vault 查询skills/second-brain-query结构体检skills/second-brain-lint周期审查skills/second-brain-review指标快照skills/second-brain-metrics项目搭建skills/second-brain-project完整清单见 skills/README.md配套的 Agent 角色定义Ingestor、Linker、Reviewer 等六个角色其中四个只读在 agents/想理解为什么角色要拆细值得一读 docs/06-agents/agent-roles.md。最后总结判断三问重复做有观点不显然→ 套五段式结构Why、Core rule、Workflow、Output format、Calibration Example→ description 写触发词和禁区 → 规则带理由 → 真实案例测过再上自动化。仓库本身就是一本 SKILL.md 教材建议先通读 second-brain-ingest再照着写出你的第一个。赞分享【免费下载链接】second-brain-osAn AI second brain that maintains itself. Full guide, starter vault, agent skills and scripts for a self-organizing knowledge base in Claude Code and Obsidian.项目地址https://gitcode.com/gh_mirrors/se/second-brain-os点击查看免费下载相关推荐如何编写自己的 Agent SkillHugging Face Skills 的 SKILL.md 规范与开发实战如何编写自己的 Agent SkillHugging Face Skills 的 SKILL.md 规范与开发实战 核心关键词Agent Skill、SKIAI 技能人工智能AI 评测模型评测如何为自己的 Agent 编写 SKILL.md 技能文件frontmatter 格式与按需加载机制如何为自己的 Agent 编写 SKILL.md 技能文件frontmatter 格式与按需加载机制 当你有一批领域规范、审查清单或操作流程希望自己的 Ag示例工程教程人工智能AI Agent代码智能体如何写出你的第一个Agent Skill拆解OPC Skills的SKILL.md结构、脚本编排与依赖设计如何写出你的第一个Agent Skill拆解OPC Skills的SKILL.md结构、脚本编排与依赖设计 想让你的 AI 编程助手学会一项新本事本文以开源创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考