Agent Skills 参考

Agent Skills 是按需的指令、资源与脚本。技能源提供技能名称与描述目录；Agent 将该目录加入系统提示词，并暴露模型在用户任务匹配技能时可使用的工具——这样大型能力库不会膨胀每次提示词。

skills 引擎位于 agents/skills，与框架无关，因此任何 Agent（包括 plain AIChatAgent onChatMessage）都可构建 SkillRegistry。@cloudflare/think 将其作为 skills 命名空间 re-export，并自动将 getSkills() 接入轮次。

在 Think 中使用 skills

捆绑 skill 通常通过 Agents Vite 插件导入：

import { Think, skills } from "@cloudflare/think";
import bundledSkills from "agents:skills"; // resolves to ./skills next to this file

export class MyAgent extends Think {
	getSkills() {
		return [
			bundledSkills,
			skills.r2(this.env.SKILLS_BUCKET, { prefix: "skills/" }),
		];
	}

	getSkillScriptRunner() {
		return skills.runner({
			loader: this.env.LOADER,
			workspaceInstance: this.workspace,
		});
	}
}

import { Think, skills } from "@cloudflare/think";
import bundledSkills from "agents:skills"; // resolves to ./skills next to this file

type Env = {
	AI: Ai;
	LOADER: WorkerLoader;
	SKILLS_BUCKET: R2Bucket;
};

export class MyAgent extends Think<Env> {
	getSkills() {
		return [
			bundledSkills,
			skills.r2(this.env.SKILLS_BUCKET, { prefix: "skills/" }),
		];
	}

	getSkillScriptRunner() {
		return skills.runner({
			loader: this.env.LOADER,
			workspaceInstance: this.workspace,
		});
	}
}

agents:skills 解析为导入文件旁的 ./skills 目录；使用 agents:skills/<dir> 指向不同名称的同级目录。agents:skills 导入由 agents 附带的 ambient 声明提供类型，因此在同一文件导入 Think 即可带入类型（若文件仅导入该 specifier，添加 /// <reference types="agents/skills-module" />）。若未使用 Agents Vite 插件，改用 skills.fromManifest(...) 构建源。

源按顺序应用；首个注册 skill 名称的源获胜，后续重复（或加载失败的源）会跳过并记录警告，而非导致 Agent 失败。

导入目录应每个 skill 包含一个子目录：

src/skills/release-notes/SKILL.md
src/skills/release-notes/scripts/format-release-notes.ts
src/skills/release-notes/references/style-guide.md

技能工具

有可用 skills 时，Agent 暴露：

工具	用途
`activate_skill`	加载匹配 skill 的指令与捆绑资源列表
`read_skill_resource`	通过 `{ name, path }` 或 `skill-name/path` 读取捆绑资源
`run_skill_script`	当 `getSkillScriptRunner()` 返回 runner 时运行捆绑脚本

技能不是始终开启的系统提示词文本。对每轮都应适用的行为，使用 getSystemPrompt() 或会话上下文块。对任务特定流程、参考、脚本、模板与资源，仅在相关时加载，使用技能。

脚本执行

脚本执行为 opt-in，需要 Worker Loader 绑定：

{
	"worker_loaders": [{ "binding": "LOADER" }]
}

[[worker_loaders]]
binding = "LOADER"

skills.runner() 为实验性功能，在 scripts/ 下运行 JavaScript、TypeScript、Python 与 Bash 脚本。TypeScript 使用 @cloudflare/worker-bundler 编译；Python 作为 Python Dynamic Workers 运行；Bash 通过 just-bash 运行。

JavaScript 与 TypeScript 脚本为函数式：

export default async function run(input, ctx) {
	const guide = ctx.files["references/style-guide.md"]; // bundled text resources
	const docs = await ctx.workspace.readFile("README.md"); // gated by permission
	const summary = await ctx.tools.call("summarize", { input }); // explicit tools
	await ctx.output.writeFile("notes.md", summary); // scratch artifact
	return { ok: true };
}

import type { SkillRunContext } from "@cloudflare/think";

export default async function run(input: unknown, ctx: SkillRunContext) {
	const guide = ctx.files["references/style-guide.md"]; // bundled text resources
	const docs = await ctx.workspace.readFile("README.md"); // gated by permission
	const summary = await ctx.tools.call("summarize", { input }); // explicit tools
	await ctx.output.writeFile("notes.md", summary); // scratch artifact
	return { ok: true };
}

ctx 为 { skill, files, workspace, tools, output }。ctx.files 按相对路径保存捆绑文本资源，ctx.workspace 受 workspace 权限约束，ctx.tools 仅暴露 runner 获得的 tool，ctx.output.writeFile(name, content) 向模型返回 scratch 产物（不会变更 workspace）。Python 与 Bash 改用基于路径的约定：/input.json、/context.json、捆绑资源位于 /skill，产物位于 /output。

传入 workspaceInstance 默认给予脚本只读 workspace 访问。网络访问、tool 与 workspace 写入为 opt-in。默认超时 30 秒。

示例

import { Think, skills } from "@cloudflare/think";

export class SkillsAgent extends Think {
	getSkills() {
		return [skills.r2(this.env.SKILLS_BUCKET, { prefix: "skills/" })];
	}
}

import { Think, skills } from "@cloudflare/think";

export class SkillsAgent extends Think<Env> {
	getSkills() {
		return [skills.r2(this.env.SKILLS_BUCKET, { prefix: "skills/" })];
	}
}

有关捆绑 skills、R2 支持的 skills 与脚本执行，请参阅 agent-skills 示例 ↗。