[mattzcarey]

Agent Skills in agents/skills are now files. skills.workspace(workspace) reads every /workspace/.agents/skills/<name>/SKILL.md from a Computer Workspace before each turn, skills.r2() reads the same layout from a bucket, and skills.manifest() defines skills in code. The parser follows the Agent Skills spec, and Think and the pi harness share one catalog.

Most of the skills code was left over from Think's first pass and only Think used it:

• skills were bundled at build time (agents:skills, the Vite plugin, agents/skills/compile) or copied from sources into the Workspace (skillWorkspace), so a skill written in the Workspace was never found
• the parser accepted any name and dropped invalid skills silently
• the pi harness had its own copy of the registry, and the two had started to differ
• Think extensions still had a "skill" context block type from the removed Session load_context model

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

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

flowchart LR
  W["workspace()"] --> C["loadSkillCatalog()"]
  R["r2()"] --> C
  M["manifest()"] --> C
  C --> T["createSkillTools() — agents/skills/tools/ai-sdk, used by Think"]
  C --> P["skills() — pi harness"]

Loading

• parseSkill() checks name (format, length, matches the directory), description, compatibility, metadata and allowed-tools, and keeps unknown frontmatter keys in extraFields. It follows the spec's guide for agents: a skill that breaks a rule still loads, with a warning per broken rule (SkillWarning diagnostic). Skills with no description, an unsafe name or unparseable YAML are skipped and logged. A skill follows the spec when warnings is empty, which is what to check before writing one. Skill tool failures (unknown skill, missing file) are tool errors: the AI SDK tools throw and the pi tools return isError.
• A SkillSource is list() + readResource(), both returning results. Invalid skills, failing sources and duplicate names become catalog diagnostics. With { previous }, a source that fails to list keeps its last skills, and Think passes its previous catalog each turn.
• createSkillTools() is exported from agents/skills/tools/ai-sdk, like the other <feature>/tools/ai-sdk exports, so agents/skills itself does not import ai or zod.
• Think: an overridden getSystemPrompt() now always renders above the context blocks, instead of being dropped once any block (including the skills catalog) exists. The think_skills block is whenChanged: "remind", so a skill changing mid-conversation reaches the model as a reminder and does not rebuild the cached system prompt.
• Removed: the agents:skills import (it now fails with a migration message), agents/skills/compile, skills-module.d.ts, SkillRegistry, Think's skillWorkspace, and ExtensionSkillBridge. esbuild moved to dev dependencies.
• skills.fromManifest() is an alias of skills.manifest() and still accepts the old fields (fingerprint, version, resource kind).
• skills.runner() stays as an experimental fallback for R2 and manifest skills, with a TODO to move to Computer. It no longer compiles TypeScript. Its ctx.workspace access now rejects paths outside /workspace. It lives at agents/skills/runner (Think still exposes skills.runner), so agents/skills no longer pulls in just-bash and codemode: its exports drop from about 310 KiB gzipped to 0.1–33 KiB.
• Examples: computer-skills (skills as Workspace files, scripts run with exec) and r2-skills replace agent-skills and assistant. Both seed their starter skills on start, with a TODO to use a Computer loader.

Docs: cloudflare/cloudflare-docs#34717.

agents workers, node and harness-pi suites, and Think's workers suite ran. I haven't run the two examples against a live model.

[changeset-bot]

🦋 Changeset detected

Latest commit: 9a5096c

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
agents	Minor
@cloudflare/think	Minor
@cloudflare/agent-think	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

Open in StackBlitz

agents

npm i https://pkg.pr.new/agents@2771

@cloudflare/ai-chat

npm i https://pkg.pr.new/@cloudflare/ai-chat@2771

@cloudflare/codemode

npm i https://pkg.pr.new/@cloudflare/codemode@2771

hono-agents

npm i https://pkg.pr.new/hono-agents@2771

@cloudflare/shell

npm i https://pkg.pr.new/@cloudflare/shell@2771

@cloudflare/think

npm i https://pkg.pr.new/@cloudflare/think@2771

@cloudflare/voice

npm i https://pkg.pr.new/@cloudflare/voice@2771

@cloudflare/worker-bundler

npm i https://pkg.pr.new/@cloudflare/worker-bundler@2771

commit: 9a5096c

[agent-think]

🟡 agents import sizes: 1 entry point grew

	Entry point	Exports	Largest gzip change	Size now
🟡	agents/harness/pi	1 resized	+957 B (+4.43%)	22 KiB
🆕	agents/skills	2 resized, 16 new, 4 removed	up to -307.5 KiB (-99.22%)	2.4 KiB
🆕	agents/skills/runner	1 new	—	375.9 KiB
🆕	agents/skills/tools/ai-sdk	1 new	—	91.5 KiB
🟢	agents/vite	1 resized	-46.9 KiB (-15.76%)	250.7 KiB
➖	agents/skills/compile	2 removed	—	—

Changed exports (28)

	Import	Gzip change	Size now
🟡	agents/harness/pi#skills	+957 B (+4.43%)	22 KiB
🆕	agents/skills/runner#runner	—	375.9 KiB
🆕	agents/skills/tools/ai-sdk#createSkillTools	—	91.5 KiB
🆕	agents/skills#workspace	—	33.2 KiB
🆕	agents/skills#parseSkill	—	31.5 KiB
🆕	agents/skills#formatSkill	—	16.7 KiB
🆕	agents/skills#manifest	—	2.4 KiB
🆕	agents/skills#loadSkillCatalog	—	1.7 KiB
🆕	agents/skills#parseSkillName	—	464 B
🆕	agents/skills#parseSkillResourcePath	—	315 B
🆕	agents/skills#formatSkillDiagnostic	—	298 B
🆕	agents/skills#renderSkillResource	—	254 B
🆕	agents/skills#SkillSourceError	—	219 B
🆕	agents/skills#InvalidSkillResourcePathError	—	183 B
🆕	agents/skills#SkillResourceNotFoundError	—	163 B
🆕	agents/skills#UnknownSkillError	—	146 B
🆕	agents/skills#SkillParseError	—	133 B
🆕	agents/skills#isModelInvocable	—	124 B
🆕	agents/skills#DEFAULT_WORKSPACE_SKILLS_ROOT	—	77 B
🟢	agents/skills#fromManifest	-307.5 KiB (-99.22%)	2.4 KiB
🟢	agents/skills#r2	-297.1 KiB (-89.98%)	33.1 KiB
🟢	agents/vite#default	-46.9 KiB (-15.76%)	250.7 KiB
➖	agents/skills#parseSkillFrontmatter	—	—
➖	agents/skills#parseSkillMarkdown	—	—
➖	agents/skills#runner	—	—
➖	agents/skills#SkillRegistry	—	—
➖	agents/skills/compile#compileSkillScript	—	—
➖	agents/skills/compile#isCompilableSkillScript	—	—

How this works

Each runtime export is bundled on its own, minified, and gzipped. Changes smaller than 100 B, or smaller than 1% and 1 KiB, are ignored. Growth over 10% or 5 KiB is marked 🔴. This report is informational and does not fail CI. The workflow artifact contains every measurement.

_{Compared 08747d9a → 9a5096c8 · workflow run · reported by agent-think[bot]}