background-agents Managed Skills教程：5分钟创建可复用Agent指令集的完整指南-平芜编程栈

background-agents Managed Skills教程：5分钟创建可复用Agent指令集的完整指南

【免费下载链接】background-agentsAn open-source background agents coding system项目地址: https://gitcode.com/GitHub_Trending/ba/background-agents

background-agents 是一款开源的后台 Agent 编码系统，其Managed Skills（托管技能）功能让你把部署流程、代码评审、事故响应等工作流沉淀为可复用的 Agent 指令集，一次编写、所有会话共享，再也不用在每条 Prompt 里重复粘贴相同指导。本教程用 5 个步骤带你从零创建、分配并管理自己的技能。

📦 什么是 Managed Skills

Managed Skills 为 Agent 提供可复用的指令和配套文件，适合标准化以下场景：

部署与预检流程
代码评审规范
事故响应手册
项目特定的编码约定

系统围绕三个核心概念设计，理解它们后所有功能一目了然：

概念	作用	谁能使用
Shared Skill（共享技能）	存放可复用指令和配套文件	实例内所有用户
Assignment（分配规则）	控制技能应用到哪些会话目标	使用共享技能的任何人
Personal Profile（个人档案）	保存你偏好的技能子集	仅档案所有者

⚠️ 安全提示：Managed Skills 是受信内容，不是权限边界。技能可以指示 Agent 使用会话中已有的工具、凭据和网络访问权限，启用前请先审查其中的指令和脚本。

🚀 快速上手：5步创建第一个共享技能

进入Settings > Skills，在Shared skills中点击New skill。
填写规范名称、描述和指令内容（写法见下一节）。
选择技能适用的仓库或环境——新技能默认All sessions (global)，对全部会话生效。
点击Validate，预览生成的SKILL.md并检查内容大小与内容摘要。
点击Create skill保存，然后新建一个会话，将技能选择器保持为All applicable即可自动包含所有匹配技能。

整个流程无需任何代码改动，验证和安装都会自动完成。

✍️ 怎么写出让 Agent 看懂的技能

创建时只需填写三个结构化字段，平台会自动生成标准SKILL.md，你无需手写该文件：

字段	填写说明
Canonical name（规范名称）	必填。小写字母、数字和单个连字符组成，如`deploy-service`。最长 64 字符，创建后不可修改
Description（描述）	必填。简要说明 Agent 何时、为何使用该技能，最长 1,024 字符
Instructions（指令）	工作流、规则、示例和预期结果，使用 Markdown 编写

💡 好的指令应让"触发条件"和"预期结果"清晰。建议包含When to use（何时使用）和Workflow（分步工作流）两节，让每一步可执行、可验证。

添加配套文件

点击Add file可加入文本类参考资料、模板或脚本，使用相对路径，例如：

references/runbook.md（事故手册）
scripts/preflight.sh（预检脚本）
assets/review-template.md（评审模板）

配套文件要求 UTF-8 纯文本（不支持二进制和压缩包）；只有scripts/目录下的文件才能标记为可执行。文件也可以直接在编辑器中编写，或从仓库导入。

🎯 分配技能：全局 / 仓库 / 环境三级作用域

分配规则决定技能"什么时候可用"，任意一条匹配即生效（多规则是叠加关系）：

分配类型	生效范围
All sessions (global)	所有会话，包括无仓库会话
Repository	包含所选仓库的会话
Environment	从所选环境启动的会话

可以同时勾选多个仓库和环境。环境会话可能同时命中全局、环境本身以及环境内仓库的分配。若删掉全部分配，技能仍保留在目录中，只是不再匹配任何新会话，随时可以重新分配。

👤 创建个人档案（Profile）：一键选择你的偏好

个人档案是过滤器而非覆盖器，适合"只想要其中几个技能"的用户：

进入Settings > Skills > My profiles，点击New profile。
输入唯一档案名。
勾选最多 20 个共享技能。
点击Save profile。

创建会话时，档案只会保留同时启用且匹配目标的技能；被禁用的条目会带(disabled)后缀提示。档案仅自己可见，不会影响其他用户，删除档案也不会删除其中的共享技能。

🎛️ 会话创建时的三种选择方式

在新建会话页选好目标（仓库/环境）后，打开模型和推理级别旁的技能选择器：

选项	结果
All applicable	包含所有匹配且启用的技能（默认）
None	不带任何托管技能启动
Personal profile	仅包含档案中启用且匹配目标技能

选择器旁的数字会实时预览将包含的技能数量；若档案显示N ignored，说明有 N 个条目被禁用或未分配给当前目标。自动化和集成未提供选择器时默认使用 All applicable；Agent 派生的子会话会原样继承父会话的技能集。

🔍 检查 Agent 实际收到了什么

会话创建时技能即被**固定（pin）**到特定版本。展开会话右侧边栏的Managed skills可以看到：

使用的选择方式（All applicable / None / 档案名）
每个技能的规范名称和描述
固定的修订版本号和摘要内容
匹配原因，如Global、Repository、Environment

重启或恢复会话仍沿用同一版本，不会自动获取新编辑——想要最新内容请新建会话。这正是可复现性的来源：已运行或已创建的会话永远不会被后续编辑影响。

📥 进阶：从仓库导入技能

技能通常已经在 Git 仓库里维护。通过Settings > Skills > Shared skills > Import from repository，可直接读取仓库中的SKILL.md及配套文件，免手敲：

Repository：实例可读的任意仓库
Ref：分支、标签或提交（留空用默认分支）
Subdirectory：仓库中技能所在子目录
Name：留空时默认取SKILL.md中的 name

导入前会完整预览解析出的提交、每个文件大小、内容摘要和映射警告；源仓库在预览后发生变化会拒绝保存。确认后再看一遍预览中的scripts/内容——导入等于把第三方指令引入全实例目录。导入会记录来源仓库、提交和摘要，之后可随时"重新导入"拉取更新，但不会自动同步。

📏 限制速查表

约束	上限
规范名称	64 字符
描述 / License / Compatibility	1,024 / 200 / 500 字符
配套文件数（每技能）	99 个
单文件大小	256 KiB
单个技能修订总量	1 MiB
档案或会话中的技能数	20 个
单会话托管技能总内容	5 MiB

配套文件路径必须是相对路径（使用/），不超过 10 级深度或 240 字节，且不能占用SKILL.md。另外agent-browser、record-video、upload-screenshot、visual-verification、customize-opencode五个名称被沙箱运行时保留，不可用于自定义技能。

🛠️ 常见问题排查

现象	原因与处理
档案提示"技能被忽略"	检查条目是否被禁用，以及分配是否匹配会话的仓库/环境
现有会话看不到最新修改	技能在会话创建时固定，新建会话才能获取新修订
某托管技能缺失	与仓库/内置技能同名冲突时，平台保留发现的技能并丢弃托管技能（仅告警，会话照常启动）。请重命名或改用新规范名
保存被拒绝	其他用户并发编辑了该技能，重新加载最新版本再应用修改