企业官网建设流程全解析

thepopebot 是一款可以 24/7 全天候运行的自主 AI Agent 平台，而「技能（Skills）」就是为它扩展能力的最简单方式——写一个SKILL.md，再建一条软链接，你的 Agent 立刻学会一项新本领。本文从技能的双目录原理讲起，带你一步步完成 SKILL.md 编写、脚本打包、软链接激活和禁用回滚，全程不需要编译、不需要注册新工具。

thepopebot 技能（Skill）是什么？

一个技能就是一个文件夹，里面包含一个SKILL.md说明文件，外加可选的脚本文件：

skills-library/my-skill/ ├── SKILL.md # 给 Agent 看的说明书 ├── run.sh # bash 脚本（最常见） └── package.json # 仅 Node.js 依赖时才需要

技能的核心特点是按需加载（渐进式披露）：系统提示词里只写入每个技能的「名称 + 一句话描述」，Agent 判断某个技能和当前任务相关时，才会去读取完整的SKILL.md并执行脚本。也就是说，装几十个技能也不会显著占用上下文。

另一大优势：一套技能，所有 Agent 通用。thepopebot 通过各 Agent 专属的软链接桥（.claude/skills、.pi/skills、.codex/skills、.gemini/skills、.kimi/skills→../skills）共享同一个skills/目录，你在 Claude Code、Codex、Gemini CLI 之间切换时技能自动跟着走。

为什么要有两个目录：skills-library 与 skills

thepopebot 刻意把技能拆成两个目录，各司其职：

这样设计的好处是开关技能极其廉价：

• ✅ 激活 = 建一条软链接
• ✅ 禁用 = 删掉软链接，源码原封不动，随时可再激活
• ✅ 无需复制、归档，也不会产生"删除即丢失"的风险

两个目录的官方说明分别在 templates/skills-library/CLAUDE.md.template 和 templates/skills/CLAUDE.md.template，建议各读一遍。

编写 SKILL.md：frontmatter 是灵魂

每个技能必须有SKILL.md，结构分两部分：YAML frontmatter（元数据）+Markdown 正文（完整用法）。

--- name: my-skill description: 一句话说明技能做什么、什么时候用。 --- # My Skill ## Setup 需要 MY_API_KEY 环境变量。 ## Usage skills/my-skill/run.sh <参数>

三条关键规则：

1. name用 kebab-case，且必须与文件夹名一致；
2. description要短促、面向行动——它会被渲染进系统提示词的 "Active skills" 区块，是 Agent 决定"要不要用这个技能"的唯一依据，写得越精准，触发越可靠；
3. 正文里的路径一律用项目根相对路径skills/my-skill/...（Agent 看到的是软链接路径），不要写skills-library/...。

一个真实参考：内置的 templates/skills-library/agent-job-background/SKILL.md 的 description 甚至列出了触发短语（"create a background job"、"check job status"），让 Agent 在用户说出特定措辞时精准命中——这是很值得借鉴的写法。

编写技能脚本：bash 优先

官方约定是Bash first：技能本质是胶水代码——调 API、搬数据、处理文件，bash + curl（配合 python3 处理 JSON）能覆盖绝大多数场景。

• bash 脚本以#!/bin/bash开头，并加set -euo pipefail；
• 创建后记得chmod +x；
• 仅在依赖库没有替代方案时才用 Node.js（比如需要特定 npm 包做 HTML 解析），此时附一个package.json声明依赖，Docker 环境会在 entrypoint 中自动安装；
• ⚠️ 根目录package.json是"type": "module"，Node 脚本请命名为.cjs（CommonJS）或.mjs（ESM），不要用裸.js，否则会被静默破坏。

一个典型的 bash 技能脚本（以语音转写为例，完整案例见 docs/HOW_TO_BUILD_SKILLS.md）：

#!/bin/bash set -euo pipefail if [ -z "$1" ]; then echo "Usage: transcribe.sh <audio-file>"; exit 1; fi if [ -z "$GROQ_API_KEY" ]; then echo "Error: GROQ_API_KEY not set"; exit 1; fi curl -s -X POST "https://api.groq.com/openai/v1/audio/transcriptions" \ -H "Authorization: Bearer $GROQ_API_KEY" \ -F "file=@${1}" \ -F "model=whisper-large-v3-turbo" \ -F "response_format=text"

软链接激活技能：一条命令搞定

这是整个流程最关键、也最简单的一步。在项目根目录执行：

# 1. 给脚本加执行权限 chmod +x skills-library/my-skill/run.sh # 2. 建立软链接，激活技能 ln -s ../skills-library/my-skill skills/my-skill

完成后 Agent 就能通过skills/my-skill/run.sh调用它了。禁用时只需删除软链接：

rm skills/my-skill # 源码在 skills-library/ 中原封不动

📌 关于npx thepopebot init：它只在首次安装时为所有内置技能批量创建激活软链接；之后的每次升级，新内置技能都会以「未激活」状态落在skills-library/里，由你自己决定是否建链接——这让你始终掌握技能开关的主动权。

内置的 4 个默认技能

首次安装后自动激活的内置技能，既是开箱即用的能力，也是现成的学习范本：

它们的源码模板位于 templates/skills-library/，比如浏览器自动化技能 templates/skills-library/playwright-cli/SKILL.md 就演示了如何把几十个 CLI 子命令组织成清晰的分节文档。

运行时是如何发现你的技能的

技能加载由{{skills}}模板变量驱动，解析逻辑在 lib/utils/render-md.js：它会扫描skills/目录（跟随软链接进入skills-library/），提取每个SKILL.mdfrontmatter 中的description，注入到系统提示词里。以 agent-job 为例，templates/agent-job/SYSTEM.md 的 "Active Skills" 区块末尾就是一句{{skills}}，运行时自动展开。

完整链路只有 4 步：

1. 渲染器扫描skills/，把各技能描述放进系统提示词；
2. 用户提出请求，Agent 根据描述判断技能相关；
3. Agent 读取完整SKILL.md学习命令；
4. Agent 通过软链接路径执行脚本，读取输出并回复。

常见问题与注意事项

• ❌不要把真实文件直接放进skills/——那里只放软链接，真实文件一律放skills-library/；
• 🔑技能需要 API Key？在管理后台 Admin > Event Handler > Agent Jobs 里添加 secret，它会被注入为 Docker 容器的环境变量；配合agent-job-secrets技能，Agent 还能自行发现可用密钥；
• 🔒安全提示：技能通过 bash 运行，Agent 理论上能读取环境变量。带AGENT_前缀的受保护密钥会被 env-sanitizer 过滤，无法在 bash 中直接读取，放心使用即可；
• 🔄 修改技能结构后，顺手更新根目录的CLAUDE.md，让下一个接手的 Agent 看到准确的实例地图。

参考资料

• 技能开发完整文档：docs/HOW_TO_BUILD_SKILLS.md
• 规范存储目录说明：templates/skills-library/CLAUDE.md.template
• 激活面目录说明：templates/skills/CLAUDE.md.template
• Agent 运行时环境约定：templates/agent-job/SYSTEM.md
• 技能描述渲染实现：lib/utils/render-md.js

写一个SKILL.md、建一条软链接，五分钟就能给你的 thepopebot 装上一项新技能——去skills-library/里动手试试吧。