Skills

Skill 是一份 Markdown 文件，用来教会智能体做好某一件具体的事：跑通你们的发布检查清单、审计一个 Rust crate、按你仓库的习惯写一份 migration。之所以需要 Skill，是因为 prompt 并不适合存放流程——流程应该只写一次、在仓库里有版本管理，并且只在真正相关时才被拉进上下文。ORG-2 会扫描一组目录来收集 Skill，每一轮只向智能体展示一份简短的名称与描述列表，只有某个 Skill 被选中时才加载它的完整正文。

Skill 在磁盘上是什么

一个 Skill 就是一个目录，其中必须有 SKILL.md，此外可以放任意它想引用的文件：

code-review/
├── SKILL.md          # required — the instructions the agent reads
├── review-checklist.md
└── scripts/validate.py

目录名就是这个 Skill 的名称。SKILL.md 以一段 YAML frontmatter 开头，后面跟 Markdown 正文。

---
name: code-review
description: Review code changes for quality, security, and maintainability. Use when reviewing pull requests, diffs, or checking code before commit.
version: 1.0.0
---

# Code Review

## Review Order

1. Correctness — does the code do what it claims?
2. Security — injection, auth, or data-leak risks?
3. Tests — are edge cases covered?

See [review-checklist.md](review-checklist.md) for the full checklist.

Frontmatter 字段

如果缺少 description，ORG-2 会退回到正文中第一行非标题文本——但编辑器会警告你，因为没有描述的 Skill，智能体永远不会选中。只要 bins 中有任何一项不在 PATH 上，或 env 中有任何变量未设置，该 Skill 就会被标记为不可用，并从智能体能看到的范围中排除。

注意： 让 SKILL.md 保持聚焦。预估超过 5,000 个 Token 时编辑器会标记出来，并建议把细节拆分到参考文件里，让智能体只在需要时才读。

Skill 从哪里加载

ORG-2 会扫描若干个根目录并合并结果，名称冲突时以最先匹配到的为准：

扫描还会探查仓库根目录下其他以点开头的目录里有没有 skills/ 子目录，这样你原本为别的工具维护的一套 Skill 不用复制就能被识别；.git、.cache、.venv、.vscode 以及包管理器缓存这类噪音目录会被跳过。每个构建都内置的 Skill 有 create-skill、create-rule、create-orgii-agent、setup-repo、manage-skills 和 manage-agents-and-orgs。

智能体如何发现并加载 Skill

三套机制同时起作用。

1. 逐轮列表。 每个已启用且可用的 Skill 都会向当轮附带的列表贡献一行——名称、来源、描述。指令会要求模型浏览这些描述，最多挑一个明显适用的 Skill，读取它的 SKILL.md，然后照着执行。正文不会内联，所以提示词缓存保持稳定。
2. 常驻清单。 带 always: true 的 Skill 会另外进入一个 # Active Skills 区块，列出名称、来源、描述和 SKILL.md 路径。正文仍然按需读取。
3. 预取（Prefetch）。 每轮开始时，ORG-2 会发起一次旁路查询，只把 Skill 的名称和描述连同你最新的消息交给模型，问它哪些相关。最多三个被选中的 Skill 会把完整的 SKILL.md 内联到 # Prefetched Skills 标题下，并标注来源和路径，这样模型不必再去翻找文件。这次旁路查询在后台运行：主循环立刻开始，并在结果就绪的那一轮迭代中把它接上。如果查询失败或返回 NONE，本轮就退回到普通列表。

你也可以直接调用某个 Skill。在输入框中键入 / 打开斜杠菜单，它会按来源给 Skill 分组——ORGII Skills、Cursor Skills、Claude Skills，仓库级的则用仓库文件夹名分组。

Skill 加载在轨迹中长什么样

加载 Skill 本质上是对某个 SKILL.md 路径的一次 read_file 调用，所以它在会话轨迹里表现为一个普通的文件读取块——但 ORG-2 认得出这种路径形态，并会重新标注它。你看到的不是文件名，而是带公文包图标的 Skill 名称：运行中显示 正在使用 skill，完成后显示 使用 skill，出错时显示 使用 skill 失败。被预取的 Skill 不会产生读取块，因为它们的内容已经注入到提示词里了。

浏览与安装 Skill

打开 集成（Integrations），进入 Skills, MCPs & Plugins 分类下的 Skills 标签页。它有两个视图：

• 已安装（Installed） —— 扫描器找到的所有 Skill，附带来源、路径、依赖状态、Token 开销，以及逐个 Skill 的启用/禁用和删除。
• 发现（Discover） / 浏览（Browse） —— 搜索公开的 skills.sh 目录。结果会显示下载量、收藏数和版本；点 安装（Install） 会下载该 Skill 的快照并写入 ~/.orgii/skills/<name>/。你也可以粘贴形如 owner/repo/skill 的 skills.sh id。

从 Hub 安装的 Skill 会在 SKILL.md 旁边保留一个小的 .skills-sh-detail.json，记录 slug 和快照哈希；正是它让 ORG-2 能提示你有可用更新并就地重新下载。从其他应用导入 Skills 会扫描你本地的智能体工具目录，把检测到的 Skill 复制进来。

编写你自己的 Skill

你可以手写这些文件，也可以让智能体来写——/create-skill 和 /manage-skills 是内置的，覆盖整个生命周期。在界面里操作：

1. 进入 集成（Integrations）→ Skills, MCPs & Plugins → Skills，选择 创建 Skill（Create Skill）。
2. 填写 名称（Name）（kebab-case，在所有被扫描的范围内唯一）和 描述（Description）。描述用第三人称写，同时说清它做什么和什么时候用，并写出具体的触发词。
3. 选择 范围（Scope）：User 写入 ~/.orgii/skills/，Repo-specific 写入 <repo>/.orgii/skills/。
4. 编写 内容（Content）——Markdown 格式的 SKILL.md 正文。预览（Preview） 标签页会显示渲染结果和 Token 估算。
5. 如果这个 Skill 要调用外部命令，声明 所需可执行文件（Required binaries） 和 所需环境变量（Required env vars）。用 附带文件（Bundled files） 添加脚本、参考资料和资源；脚本会被执行，但永远不会加载进上下文窗口。
6. 可以打开 始终激活（Always active），把该 Skill 固定进每条提示词。除非它确实每一轮都用得上，否则保持关闭。

修改已有 Skill 的范围会把整个文件夹一起移走，附带文件也跟着走。

把 Skill 限定到项目、智能体或智能体团队

范围分三个层级，而且可以叠加：

• 项目。 位于 <repo>/.orgii/skills/ 的 Skill 只在会话工作于该仓库时加载。所有人都该共享的约定放这里最合适，因为 Skill 会和代码一起提交。
• 用户。 位于 ~/.orgii/skills/ 的 Skill 在你这台机器上的每个项目里都可用。
• 智能体。 每份智能体定义都带一套 Skill 配置：一个 include 白名单、一个 exclude 列表，以及额外的来源目录。当 include 非空时，只有其中列出的 Skill 会展示给该智能体。在某个智能体的 Skills 区块里切换开关，写入的是该智能体的排除列表；在集成中心里切换则是全局禁用，对所有智能体生效。禁用优先于 include 白名单。

还有两个开关：Skill 自身 frontmatter 中的 include-agent / exclude-agent 让 Skill 声明哪些智能体可以看到它；每个智能体上的 自动加载工作区 Skills、MCP 和插件 开关则会为该智能体关掉来自仓库的资源，同时保留用户级的资源。由于智能体是按智能体团队分组的，要让整个团队用上同一套 Skill，做法是在该团队模板链的父级上设置 Skill 配置——子定义如果自己提供了 Skill 配置，会替换父级的，而不是与之合并。

下一步

• 智能体 —— 智能体定义、智能体团队结构，以及 Skill 配置所在的位置
• 记忆（Memory） —— 面向跨会话知识的姊妹系统，使用同一套预取机制
• 工具 —— Skill 的指令可以调用的内置工具
• 项目 —— 一个仓库如何成为带有自己 .orgii/ 目录的工作区