团队用 Jira 跟需求、用 Confluence 沉淀文档的工程师，最近让编码型 Agent 干活时多半撞过同一堵墙：Agent 代码写得飞快，却对你们的项目结构、空间约定一无所知，让它"把这个改动关联到 DEV-123"，你得先花半小时教它什么是 workitem、什么是空间。Atlassian 在官方开发者文档里给出了正式答案——TWG CLI 的 agent skills：一组可安装的上下文文件，专门教编码型 Agent 与 Atlassian 产品协作。本文按"是什么 → 怎么装 → 怎么发现 → 实战与边界"组织全文。
1、Skills 是什么
官方定义很直白：skills 是一组上下文文件，教编码型 Agent 如何与 Atlassian 产品打交道。安装一次之后，你用自然语言描述任务，Agent 自动读取对应技能，不需要任何特殊的提示词前缀。
它和"再手写一段 prompt"的差别在于维护主体：这些文件由 Atlassian 官方维护，内容跟着产品语义走。Jira 的 workitem、Confluence 的内容树，都被拆解成 Agent 可直接执行的命令契约，而不是散落在提示词里的自然语言描述。技能的定义与安装方式见官方的 agent skills 开发者文档。
从设计上看有三个特点：
- 官方维护，随产品迭代更新，不靠社区口口相传
- 命令契约结构化，Agent 拼参数有据可依
- 安装一次，对所有检测到的编码 Agent 生效
2、TWG CLI 背景速览
skills 是 TWG CLI 的一个子命令能力，要理解它得先花一分钟认识宿主。TWG CLI 全称 Teamwork Graph CLI，是 Atlassian 官方的命令行工具，底层连接 Teamwork Graph——Atlassian 的企业知识与上下文图谱，把人、内容、活动和关系以权限感知的方式映射成图。数据源不止自家产品：Jira、Confluence、Google Drive、Slack、GitHub、Salesforce 都在图里。
可操作的产品面相当宽，包括 Jira、Confluence、Bitbucket、Jira Service Management、Assets、Loom、Trello、Rovo、Goals 等。认证基于 OAuth 2.1，Agent 能查到什么，取决于当前用户账号本身能看到什么。CLI 的整体定位见 TWG CLI 官方文档。
这套东西不是孤立的命令行玩具。Team '26 大会上 Atlassian 发布了一系列 Rovo agent 相关公告，之后又在 2026 年 9 月的 governed agent loops 博文里把方向说得更清楚：让 AI 辅助开发从个人的"魔法时刻"走向有治理、可规模化运转的 Agent 循环，也就是他们所说的 AI 原生 SDLC。TWG CLI 加 skills，正是编码 Agent 接入这套体系的地基。
3、安装与目录布局
安装动作只有一条命令，TWG 安装器在安装 CLI 时也会自动完成这一步。
# 为所有检测到的 Agent 安装技能
twg skills install
# 仅为指定 Agent 安装，例如 Claude Code
twg skills install --agent claude
解读：技能默认安装到 ~/.agents/skills，这是通用的 .agents/skills 布局，Codex、Cursor、Gemini CLI、GitHub Copilot、Rovo Dev 等主流 Agent 都直接识别这个位置；检测到特定 Agent 已安装时，还会补一份专属副本，例如 Claude Code 会在 ~/.claude/skills 下拿到拷贝。
装完之后的目录结构长这样：
~/.agents/skills/
├── twg/ # 根操作契约
│ └── SKILL.md
├── twg-jira/ # Jira 语义与写入安全
├── twg-confluence/ # Confluence 语义与写入安全
├── twg-xxx/ # 聚焦工作流的技能包
└── xxx/references/ # 各技能的按需加载指引
各目录职责如下：
| 目录 | 职责 |
|---|---|
twg/ |
根契约：技能发现、输出处理、共享安全规则 |
twg-jira/ |
Jira 产品语义与写入安全 |
twg-confluence/ |
Confluence 产品语义与写入安全 |
twg-xxx/ |
状态汇总、上下文发现等工作流 |
xxx/references/ |
细粒度指引，用到才加载 |
目录里的 xxx 是占位符，代表具体的工作流名。这个三层拆分（根契约、产品包、工作流包）是控制上下文占用的关键：Agent 平时只带根契约，接到具体任务再展开对应的 references，不会把全部规则一次性塞进上下文窗口。
4、按需发现与加载
skills 不依赖"把所有规则预加载"，而是提供了一套发现机制，让 Agent 自己找到该用哪份技能。
# 用自然语言检索技能
twg help discover-skills "snapshot token editing"
# 限定在某个技能包内检索
twg help discover-skills "JQL sprint prioritization" --skill twg-jira
# 查看命名空间或命令的契约
twg help describe "jira"
twg help describe "jira workitem get"
解读：discover-skills 基于策划过的标题与描述检索，不搜正文；每次返回一个主匹配加至多两个备选，避免 Agent 在检索环节打转。describe 对命名空间返回 YAML 路由表，对精确命令返回 JSON 契约——Agent 拿到的是结构化规格，可以照着直接拼参数。
5、典型工作流示例
举个最贴日常的场景：周五写周报。装好 skills 后，你只需要对 Agent 说"把我这周做的工作汇总一下"。Agent 先通过发现机制定位到状态汇总类工作流，再用 describe 逐层拿到 Jira 查询契约，然后执行查询、聚合、输出成文。整条链路你不写一行 JQL，不复制一个链接。
官方目前聚焦四类工作流，对应的团队场景都很好对号入座：
- 状态汇总：站会、周报、sprint 评审前的批量状态盘点
- 上下文发现：开工前找齐设计文档、历史决策与关联条目
- 工程工作：跨仓库的编码任务与变更追踪
- 运维健康：发布后检查服务状态并回写 Jira
注意这些任务的输入就是日常口语，中文英文怎么问都行，Agent 端不需要任何前缀约定。
6、注意事项与边界
写入类操作有独立的安全层：
twg-jira与twg-confluence各自带写入安全语义，Agent 改动生产数据前会经过这层约束，不要为了省事引导 Agent 绕过它。
几个工程上值得提前知道的点：
- 沙箱网络：白板、附件功能需放行两个官方域名
- 权限模型：Agent 可见范围等于账号本身可见范围
- 迭代节奏：文档更新快，命令细节以官方文档为准
- 认证配置：首次使用需完成 OAuth 2.1 授权
第一条展开说：沙箱环境里白板、附件等功能依赖 api.media.atlassian.com 与 *.frontend.public.atl-paas.net 两个域名，Claude Code 中对应 network.allowedDomains 设置，团队统一封装沙箱配置时记得把这一条写进去。
7、总结
Atlassian 把"教 Agent 用 Jira 和 Confluence"这件事产品化了：TWG CLI 提供命令面，skills 提供官方维护的上下文文件，discover 与 describe 提供按需加载的检索层，写入安全兜底。对编码型 Agent 而言，这相当于把企业内部的协作语义变成了即插即用的标准件。对于已经在 Jira、Confluence 上运转的团队，建议先在个人环境执行 twg skills install，挑一个低风险场景（比如周报汇总）把链路跑通，再把经验沉淀进团队的 Agent 使用规范。
