Agent 技能(skills)
为什么存在
技能是给 agent 的上下文,不是给程序的配置。一个 SKILL.md 说明某个子系统的
流程、边界与命令;agent 打开对应目录时读到它,就知道该怎么干活,不必让用户每次重复交代。
技能一旦被发现就会进入上下文,因此它是有成本的。放在哪个作用域,决定了 「谁会看到它、要为它付多少 token」。所以这里的原则不是「能装就装」, 而是装在该看到它的那一层。
职责边界
归 linxira-skills:
- 可执行文件
linxira-skills:init/status/update/uninstall。 - profile 与 payload:把选定的 profile 物化成
.agents/skills/下的三级路由树, 并生成.linxira/manifest.json与AGENTS.md标记块。 - 每个 profile 的技能清单、来源与许可记录(
THIRD_PARTY_NOTICES.md、docs/SOURCES.md)。
不归它:
- 运行时如何发现技能;那是 Zeta 的 provider 优先级与开关。
- 系统技能目录的安装;那由发行包的 PKGBUILD 完成。
- 工作区技能的物化;那由组件自己完成(目前是崩溃监视)。
- 生成 agent 会话或执行技能内容。
已实现的作用域
| 作用域 | 路径 | 谁安装 | 谁能看到 |
|---|---|---|---|
| 系统 | /usr/share/linxira/agent/skills/<name>/SKILL.md |
发行包(PKGBUILD) | 全系统;包拥有、只读,随包升级 |
| 工作区 | <ws>/.agents/skills/<name>/SKILL.md |
组件在创建工作区时物化 | 只在该工作区(agent 的 --cwd)内;.agents/skills/ 被 gitignore |
| 项目 | <repo>/.agents/skills/ |
linxira-skills init |
只在该仓库;同时生成 .linxira/manifest.json 与 AGENTS.md 标记块 |
linxira-skills 没有用户作用域的安装入口。 ~/.agents/skills/ 是 Zeta 的 agents
provider 会扫描的用户级目录,但只有在 Zeta 打开 enableAgentsUser 时才加载;
linxira-skills 不会往那里写任何东西,安装包也不得写入。需要跨项目复用的技能,
目前只能由用户自行放置并承担上下文成本。
当前的实际内容很少,这是有意的:
- 系统作用域目前只有一个技能:
linxira-config,由linxira-config-hub的 PKGBUILD 安装。配套清单/usr/share/linxira/agent/capabilities.json记录它能做什么、哪些命令需要 root。 - 工作区作用域目前也只有一个:崩溃监视物化的
diagnose-crash。 - 项目作用域由用户自己决定装哪个 profile,系统不预置。
布局是一层,不是一棵树
Zeta 的 provider 发现只看 <skills-root>/<name>/SKILL.md 这一层;写成
<skills-root>/<group>/<name>/SKILL.md 的嵌套结构不会被默认加载。
linxira-skills 因此把三级路由树放在 .agents/skills/ 下,并用生成的
AGENTS.md 标记块与相对 INDEX.md 链接把 agent 从 router 带到 index、再到叶子,
而不是依赖递归扫描。
谁可以写哪里
| 写入方 | 可以写 | 不可以写 |
|---|---|---|
| 发行包(PKGBUILD) | 系统技能目录与 capabilities.json |
~/.zeta/agent/skills、~/.agents/skills、任何用户目录 |
| 组件(如崩溃监视) | 只把自己那一个技能物化进自己的工作区 | 别的子系统的技能、系统技能目录 |
linxira-skills CLI |
目标 Git 仓库的项目作用域(.agents/skills/、.linxira/manifest.json、AGENTS.md 标记块) |
系统技能目录、~/.agents/skills、~/.zeta/agent/skills |
| 用户 | 任何作用域,但项目作用域应通过 CLI 安装,便于追踪与卸载 | — |
包不得写用户作用域
~/.agents/skills 属于用户,不属于包。包往里写会让一份技能出现在用户的
每个项目里,用户既没有选择过,也无法通过 linxira-skills uninstall 干净移除。
~/.zeta/agent/skills 同理——那是 Zeta 自己的用户数据,包不得写入。
为什么默认项目作用域
用户级技能对每个项目可见:在任何仓库里启动 agent,只要开关打开,它都会被加载, 哪怕这次任务完全用不上。这既是上下文成本,也是名字冲突的来源—— 同一个技能名在多个来源出现时,只有优先级最高的那一份生效,排查起来很不直观。
项目作用域没有这个问题:技能跟着用得上它的仓库走,换项目就自然消失,而且
uninstall 能把受管目录清干净。home 目录也不是仓库,不该被塞进 AGENTS.md
标记块或 .gitignore 条目——这也是 CLI 只在 Git 仓库里工作的原因之一。
发现顺序
Zeta 启动时按 provider 优先级依次加载技能,同名先到先得:
- 原生
.zeta技能(用户级与项目级,优先级 100); zeta-plugins(90),然后是claude(80)、claude-plugins/agents/codex(70 组);opencode(55)、github(30);- 最后是 Zeta 的自动学习(managed)技能(5),它总是让位于同名的作者技能。
结果就是:原生的 .zeta 版本会盖过同名的 .agents 版本;而 .agents/
这一层正是 linxira-skills 与各组件物化技能的地方。系统技能目录不在默认扫描
路径里,它通过 capabilities.json 的 skill 字段被显式引用——agent 读清单就能找到它。
agents provider 有自己的用户级与项目级开关(enableAgentsUser /
enableAgentsProject);关闭 Claude、Codex 等 provider 不会连带关闭它。
命令
# 项目作用域(唯一支持的作用域):在目标 Git 仓库内运行
npx @linxiraos/linxira-skills init
npx @linxiraos/linxira-skills init --profile core
npx @linxiraos/linxira-skills init --layout namespaced # 默认;router 落在 .agents/skills/linxira-<root>/
npx @linxiraos/linxira-skills init --layout flat # router 落在 .agents/skills/<root>/
# 查看、升级、卸载:跟随 manifest 记录的 profile 与布局
npx @linxiraos/linxira-skills status
npx @linxiraos/linxira-skills update [--force]
npx @linxiraos/linxira-skills uninstall [--force]
init、update、uninstall 都支持 --dry-run。update 只更新 manifest 记录且
未被改动过的条目,遇到用户修改会要求 --force。status / update / uninstall
读取安装时写下的 .linxira/manifest.json,因此换过 --layout 不需要手工清理旧目录。
profile:
core(默认):10 个一方软件、完整性、Linux、传输与计算技能。bioinformatics-core:core加 10 个一方生物信息与 bulk RNA-seq 技能。biology-research-core:在上一级之上加 19 个生物学发现、实验设计、湿实验治理与 学术交付技能。science-research-core:再扩展化学、物理、作物/植物、生态、动物生理、生化与 医学/转化研究设计。research-communication-core:core加 44 个文稿、引用、排版、图表、文档、LaTeX、 演示与中文科研文档技能(含 vendored 的 Apache-2.0 / MIT 改编,见THIRD_PARTY_NOTICES.md)。
尚未发布到 npm
安装架构文档标注该包尚未发布到 npm。上面的 npx 形式以发布为前提;
在发布之前只能使用本地构建的包,不要假定 @linxiraos/linxira-skills 已可下载。
分离规则
系统管理类技能(如 linxira-config)留在系统目录,不复制进工作区。
工作区只物化本子系统需要的那一个技能。自 crash-watch 0.1.4 起,崩溃监视不再把
linxira-config 复制进调试工作区:同一份技能存在两个副本会随时间漂移,
而系统技能随包升级,工作区副本不会。要让 agent 知道系统配置能力,应该读系统技能,
而不是在每个工作区里养一份过期副本。
权限
linxira-skills不需要 root,也不调用sudo;它只在目标 Git 仓库内写受管文件。- 系统技能由包管理器以 root 安装,属于普通系统升级路径。
- 组件物化工作区技能用的是用户自己的权限,不提升。
已知限制
init必须在 Git 仓库(或其子目录)里运行;非 Git 目录会直接报错。- 已初始化的仓库再次
init会报错,要求改用update或uninstall。 linxira-skills没有用户作用域安装入口;~/.agents/skills是否被加载取决于 Zeta 的enableAgentsUser开关,手工放到那里也不等于一定生效。- 系统技能目录不在 Zeta 的默认扫描路径中,只能通过
capabilities.json的skill字段被引用。 - 技能发现只看一层目录;嵌套目录必须靠 router 与
AGENTS.md引导,而不是自动扫描。 - CLI 不运行
git add、不修改源码 submodule、不抓取上游、不发网络请求。 - 只有列出的五个 profile;未通过评审的第三方内容不进入可安装 payload。
深入设计
- 安装器与布局:
linxira-skills仓库的docs/INSTALLATION_ARCHITECTURE.md与docs/SKILL_LOADING_POLICY.md。 - 工作区物化:
linxira-crash-watch仓库的src/linxira_crash_watch/workspace.py。 - 系统技能与清单:
linxira-config-hub仓库的agent/目录。