使用 Skills
在 Cody 里，Skills 是把项目或团队知识打包成可发现文档的一种方式：每个 Skill 对应一份 SKILL.md，框架会在构建对话上下文时按规则加载，让模型在合适的任务上「自带说明书」。本篇先给一段可直接运行的查询示例，再拆开讲四层优先级、内置列表、自定义文件格式与目录配置。
完整示例：列出并读取一个 Skill
下面假设你已按第 01 篇设置好环境变量（本系列演示模型统一为 qwen3.5-plus）。客户端不显式传模型名，由 CODY_MODEL 等环境变量决定。
# list_skills_get_skill_demo.py import asyncio from cody.sdk import Cody async def main(): # workdir 指向你的项目根目录；模型来自环境变量（如 qwen3.5-plus） client = Cody().workdir(".").build() skills = await client.list_skills() for s in skills: print(s["name"], "|", s["source"], "|", s["enabled"]) skill = await client.get_skill("git") print("--- documentation 预览 ---") print(skill["documentation"][:500]) if __name__ == "__main__": asyncio.run(main())
运行后你会看到每条 Skill 的名称、来源与是否启用；get_skill 则返回 documentation 字段（整份 SKILL.md 文本），便于你在 UI 或调试脚本里展示。
加载机制：四层优先级与 11 个内置 Skill
Cody 按固定顺序合并 Skill 来源，高优先级覆盖低优先级中同名 Skill。记忆口诀：
custom > project > global > builtin
| 层级 | 典型路径 / 含义 | 说明 |
|---|---|---|
| custom | 通过 .skill_dir() / .skill_dirs() 或 CODY_SKILL_DIRS 指定 | 团队共享目录、多仓库共用规范等 |
| project | 项目下 .cody/skills/ | 随仓库版本化的项目 Skill |
| global | 用户目录 ~/.cody/skills/ | 本机所有项目可复用的个人 Skill |
| builtin | 框架内置 | 开箱即用，可被上层同名 Skill 覆盖 |
内置共 11 个 Skill，名称如下（与 SDK 约定一致）：
git、github、docker、npm、python、rust、go、java、web、cicd、testing。
查询 API：list_skills 与 get_skill
list_skills
异步方法 await client.list_skills() 返回 list[dict]，每个元素字段为：
| 字段 | 类型 | 含义 |
|---|---|---|
name | str | Skill 标识（小写、连字符） |
description | str | 一句话摘要，供模型判断是否相关 |
enabled | bool | 是否启用 |
source | str | 来源（如 custom / project / builtin 等实现细节） |
get_skill
await client.get_skill(skill_name) 返回单个 dict，在列表字段基础上增加：
| 字段 | 类型 | 含义 |
|---|---|---|
documentation | str | SKILL.md 文件的完整文本（含 YAML frontmatter 与正文） |
CodyNotFoundError（code="SKILL_NOT_FOUND"）。需要开关启停时可进一步了解 enable_skill / disable_skill（会写回配置文件）。
自定义 Skill：完整的 SKILL.md
每个 Skill 目录下放一个 SKILL.md。Frontmatter 必填 name 与 description：name 必须为小写字母与连字符；description 要写得让模型能判断「何时该读这篇文档」。可选 metadata 存放作者、版本等。
# 示例：.cody/skills/internal-api/SKILL.md
---
name: internal-api
description: 当用户询问本公司内部 HTTP API 的鉴权与错误码约定时使用本 Skill。
metadata:
author: platform-team
version: "1.0"
---
# 内部 API 约定
## 鉴权
- 所有请求头携带 `Authorization: Bearer <token>`。
- 开发环境 Base URL：`https://api.dev.example.com`。
## 常见错误
| HTTP | 含义 |
|------|------|
| 401 | Token 无效或过期 |
| 429 | 触发限流，应指数退避重试 |
## 禁止事项
- 勿在日志中打印完整 Token。
正文部分使用普通 Markdown 即可；Cody 会把内容与描述一并纳入技能管理器，供系统提示与检索逻辑使用。
目录配置：.skill_dir()、.skill_dirs() 与 CODY_SKILL_DIRS
在 Builder 上追加自定义扫描目录的写法如下（与 SDK 一致）：
from cody.sdk import Cody client = ( Cody() .workdir(".") .skill_dir("/shared/team-skills") .skill_dirs(["/dir1", "/dir2"]) # 批量 .build() )
.skill_dirs([...]) 会用新列表整体替换当前已收集的自定义目录。若需要同时保留 /shared/team-skills 与 /dir1、/dir2，请把前者一并放进 .skill_dirs([...]) 的列表，或只使用多次 .skill_dir(...) 追加。
环境变量方式适合容器或 CI，多个路径用冒号分隔（与文档约定一致）：
export CODY_SKILL_DIRS=/shared/team-skills:/home/user/my-skills
如需在代码里显式指定通义千问（与第 01 篇一致），可使用：
client = (
Cody()
.workdir(".")
.model("qwen3.5-plus")
.base_url("https://coding.dashscope.aliyuncs.com/v1")
.api_key("sk-xxx")
.build()
)
SKILL.md 放对目录、写好 description，并保证对应 Skill 处于启用状态即可。
小结
本篇覆盖了 Skills 的四层优先级、11 个内置名称、list_skills / get_skill 的返回字段，以及自定义 SKILL.md 与 skill_dir / CODY_SKILL_DIRS 的配置方式。下一步建议在真实项目里加一个 .cody/skills/ 目录试跑，再阅读 第 08 篇 · 集成 MCP，把外部工具与文档能力接到同一套 Agent 上。