读懂pi-skillsSKILL.md格式、name/description字段与{baseDir}占位符的运行原理【免费下载链接】pi-skillsSkills for pi coding agent (compatible with Claude Code and Codex CLI)项目地址: https://gitcode.com/gh_mirrors/pi/pi-skillspi-skills 是一个面向 pi coding agent 的即用型技能Skills集合兼容 Claude Code、Codex CLI 等 AI 命令行工具。每个技能只需一个SKILL.md文件本文完整拆解它的三大核心机制——SKILL.md 格式、name/description 字段与{baseDir} 占位符帮你读完后就能自己写出第一个技能。pi-skills 是什么8 个内置技能一览技能Skill可以理解为教会 AI 编码助手完成某类任务的小包一个文件夹 一项能力。pi-skills 内置了 8 个常用技能覆盖搜索、浏览器、Google 服务与音视频等场景技能能力文档入口网页搜索与正文提取基于 Brave Search API无需浏览器brave-search/SKILL.md浏览器自动化通过 Chrome DevTools 协议操作页面browser-tools/SKILL.md谷歌日历 CLI日程查看、创建与空闲查询gccli/SKILL.md谷歌网盘 CLI文件上传下载、搜索与分享gdcli/SKILL.mdGmail CLI收发邮件、草稿与标签管理gmcli/SKILL.md语音转文字调用 Groq Whisper APItranscribe/SKILL.mdVS Code 集成可视化 diff 与文件对比vscode/SKILL.mdYouTube 字幕抓取获取视频带时间戳的字幕youtube-transcript/SKILL.mdSKILL.md 文件结构拆解frontmatter 正文每个技能都由一个SKILL.md文件定义整体分为两部分YAML frontmatter文件顶部的元数据区用两行---包裹Markdown 正文写给 agent 看的详细操作说明以 brave-search/SKILL.md 为例一个标准的技能文件长这样--- name: brave-search description: Web search and content extraction via Brave Search API. Use for searching documentation, facts, or any web content. --- # Brave Search Web search and content extraction using the official Brave Search API. No browser required. ## Usage {baseDir}/search.js query -n 10官方给出的最小格式模板见 README.md核心思想就是元数据 说明。name 与 description 字段如何被 AI 读取和触发这两个字段是整个技能格式的开关各自承担不同职责name技能唯一标识用于让 agent 识别并调用对应技能惯例为小写 连字符且与技能文件夹同名如brave-search/对应name: brave-searchdescription决定何时被触发的关键这句话会直接展示给 AIagent 依据它判断当前任务是否该调用该技能好的 description 同时回答两个问题能做什么什么时候用对比两个真实示例就能看出差异transcribe/SKILL.mdSpeech-to-text transcription using Groq Whisper API. Supports m4a, mp3, wav, ogg, flac, webm.——既说明能力也列出支持格式browser-tools/SKILL.md...Use when you need to interact with web pages, test frontends, or when user interaction with a visible browser is required.——明确写出使用时机 实用技巧如果 agent 该用技能时没想起来先检查 description 是否覆盖了用户的常见说法这比修改正文更有效。{baseDir} 占位符如何被替换让技能随迁随用浏览 transcribe/SKILL.md 的命令示例时会看到{baseDir}{baseDir}/transcribe.sh audio-file它的运行时机制非常简单agent 加载某个技能时记录该技能所在文件夹的绝对路径将SKILL.md中所有{baseDir}替换为这个路径最终执行的命令形如~/.pi/agent/skills/pi-skills/transcribe/transcribe.sh meeting.m4a这样设计的核心价值是可移植性无论技能被安装到用户级~/.pi/agent/skills/还是项目级.pi/skills/SKILL.md 里的命令一个字都不用改。同样的写法在 youtube-transcript/SKILL.md 和 browser-tools/SKILL.md 中反复出现。配套的脚本自身也做了自愈transcribe/transcribe.sh 通过dirname $0自行定位所在目录即使工作目录切换相对文件引用依然正确。三步安装 pi-skillsclone 到扫描目录即可所有 agent 的安装原理一致——把技能文件夹放进它的扫描路径就行。以 pi-coding-agent 为例# 用户级安装所有项目都可用 git clone https://gitcode.com/gh_mirrors/pi/pi-skills ~/.pi/agent/skills/pi-skillspi-coding-agent / Codex CLI直接 clone 到对应 skills 目录即可Codex 为~/.codex/skills/pi-skillsClaude Code因为它只扫描一级目录需要把每个技能文件夹软链到~/.claude/skills/下各工具的具体安装路径见 README.md。四步写出你的第一个 SKILL.md 技能--- name: skill-name description: 能做什么 何时使用写给 agent 看 --- # Instructions 详细操作步骤... Helper files available at: {baseDir}/在 skills 目录下新建文件夹skill-name/与name字段同名写好 frontmatterdescription 要agent 能读懂正文写清操作步骤引用同目录文件时一律使用{baseDir}/文件名若含脚本如 brave-search/search.js与 SKILL.md 同放一个文件夹 记住一句话description 是广告决定技能会不会被调用正文是说明书决定任务能不能办成。常见问题安装后还要做什么需要额外配置吗部分技能需要一次性npm install或全局安装 CLI完整清单见 README.md通常 agent 会在首次使用时引导你完成配置。为什么不在 SKILL.md 里写绝对路径安装位置随机器和项目而变{baseDir}正是解决这个问题的标准做法。可以只改 description 不动正文吗可以frontmatter 与正文相互独立改触发条件只需改元数据。【免费下载链接】pi-skillsSkills for pi coding agent (compatible with Claude Code and Codex CLI)项目地址: https://gitcode.com/gh_mirrors/pi/pi-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考