[Agents] Overhaul agent skills docs — split into SDK-agnostic and Think-specific pages#31282
Open
thomasgauvin wants to merge 3 commits into
Open
[Agents] Overhaul agent skills docs — split into SDK-agnostic and Think-specific pages#31282thomasgauvin wants to merge 3 commits into
thomasgauvin wants to merge 3 commits into
Conversation
…nk-specific pages - Overhaul /agents/runtime/execution/agent-skills/ as a reference page covering framework-agnostic primitives (SkillRegistry, sources, runner, parsers), AI SDK tool integration, and script execution. Adds DIY vs managed skills comparison table and examples for AIChatAgent and OpenAI SDK usage. - Create /agents/harnesses/think/skills/ covering Think-specific wiring: getSkills(), getSkillScriptRunner(), Vite plugin, R2 sources, custom sources, and how Think integrates the registry into the turn loop. - Update Think index, configuration, and tools pages to link to the new Think-specific skills page.
github-actions
Bot
added
product:agents
github-actions
Bot
assigned
elithrar,
irvinebroque,
rita3ko,
threepointone and
whoiskatrin
Contributor
|
This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:
|
thomasgauvin
requested review from
a team,
elithrar,
irvinebroque,
rita3ko,
threepointone and
whoiskatrin
as code owners
ask-bonk
Bot
added
documentation
![ask-bonk[bot]](https://avatars.githubusercontent.com/in/2454580?s=60&v=4){kind=small}
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
Contributor
|
Reviewed PR #31282. Applied labels Summary: The PR correctly splits agent skills documentation into an SDK-agnostic concept/reference page ( Issues to fix:
No build breakers, broken links, missing imports, or incorrect frontmatter found. The heading hierarchy and sentence case are correct on both new and modified pages. |
- Wrap bare code fences in TypeScriptExample where appropriate - Fix SkillRunContext import from agents/skills (not @cloudflare/think) - Fix this.env.DB reference in custom SkillSource example (capture in closure) - Use TOML instead of JSONC in WranglerConfig
Contributor
Author
|
/bonk rereview |
The comment inside a TypeScriptExample code block causes Prettier's babel parser to fail during build rendering. Replace with a valid variable reference .
| | `fingerprint` | `string` (getter) | Composite hash of all sources — changes when any source changes | | ||
| | `systemPrompt()` | `string` or `null` | Markdown catalog of available skills and their descriptions, for injection into the system prompt | | ||
| | `snapshot()` | `SkillRegistrySnapshot` | `{ fingerprint, catalogPrompt }` — for caching and state management | | ||
| | `loadSkill(name)` | `Promise<SkillContent or null>` | Loads the full skill body, resource listing, and metadata by name | |
Contributor
There was a problem hiding this comment.
Fix TypeScript type syntax and avoid or inside backticks:
Suggested change
| | `loadSkill(name)` | `Promise<SkillContent or null>` | Loads the full skill body, resource listing, and metadata by name | | |
| | `loadSkill(name)` | `Promise<SkillContent>` or `null` | Loads the full skill body, resource listing, and metadata by name | |
| | `systemPrompt()` | `string` or `null` | Markdown catalog of available skills and their descriptions, for injection into the system prompt | | ||
| | `snapshot()` | `SkillRegistrySnapshot` | `{ fingerprint, catalogPrompt }` — for caching and state management | | ||
| | `loadSkill(name)` | `Promise<SkillContent or null>` | Loads the full skill body, resource listing, and metadata by name | | ||
| | `readResource(name, path)` | `Promise<string or null>` | Reads a bundled resource by skill name and relative path | |
Contributor
There was a problem hiding this comment.
Fix TypeScript type syntax:
Suggested change
| | `readResource(name, path)` | `Promise<string or null>` | Reads a bundled resource by skill name and relative path | | |
| | `readResource(name, path)` | `Promise<string>` or `null` | Reads a bundled resource by skill name and relative path | |
|
|
||
| | Tool | Available when | What it does | | ||
| | --- | --- | --- | | ||
| | `activate_skill` | Always (if skills exist) | Model calls with a skill `name` from the catalog. Returns the skill's full body plus a resource listing, wrapped in `<skill_content>` tags. | |
Contributor
There was a problem hiding this comment.
Wrap angle-bracket text in backticks to prevent MDX parsing errors:
Suggested change
| | `activate_skill` | Always (if skills exist) | Model calls with a skill `name` from the catalog. Returns the skill's full body plus a resource listing, wrapped in `<skill_content>` tags. | | |
| | `activate_skill` | Always (if skills exist) | Model calls with a skill `name` from the catalog. Returns the skill's full body plus a resource listing, wrapped in `<skill_content>` tags. | |
| | Tool | Available when | What it does | | ||
| | --- | --- | --- | | ||
| | `activate_skill` | Always (if skills exist) | Model calls with a skill `name` from the catalog. Returns the skill's full body plus a resource listing, wrapped in `<skill_content>` tags. | | ||
| | `read_skill_resource` | Always (if skills exist) | Model reads a bundled resource by passing `{ name, path }` or a qualified path like `"release-notes/references/style-guide.md"`. | |
Contributor
There was a problem hiding this comment.
Wrap braces in backticks to prevent MDX expression parsing:
Suggested change
| | `read_skill_resource` | Always (if skills exist) | Model reads a bundled resource by passing `{ name, path }` or a qualified path like `"release-notes/references/style-guide.md"`. | | |
| | `read_skill_resource` | Always (if skills exist) | Model reads a bundled resource by passing `{ name, path }` or a qualified path like `"release-notes/references/style-guide.md"`. | |
Comment on lines
+330
to
+338
| <WranglerConfig> | ||
|
|
||
| export class SkillsAgent extends Think<Env> { | ||
| getSkills() { | ||
| return [skills.r2(this.env.SKILLS_BUCKET, { prefix: "skills/" })]; | ||
| } | ||
| ```jsonc | ||
| { | ||
| "worker_loaders": [{ "binding": "LOADER" }] | ||
| } | ||
| ``` | ||
|
|
||
| </WranglerConfig> |
Contributor
There was a problem hiding this comment.
WranglerConfig must use TOML input per the style guide:
Suggested change
| <WranglerConfig> | |
| export class SkillsAgent extends Think<Env> { | |
| getSkills() { | |
| return [skills.r2(this.env.SKILLS_BUCKET, { prefix: "skills/" })]; | |
| } | |
| ```jsonc | |
| { | |
| "worker_loaders": [{ "binding": "LOADER" }] | |
| } | |
| ``` | |
| </WranglerConfig> | |
| <WranglerConfig> | |
| ```toml | |
| [[worker_loaders]] | |
| binding = "LOADER" |
Contributor
|
Re-reviewed PR #31282. All issues from prior reviews have been addressed:
Posted 5 inline suggestions on
|
Contributor
Contributor
|
/full-review |
Contributor
ReviewWarnings (9)
Suggestions (1)
CommandsOnly codeowners can run commands. Post a comment with the command to trigger it.
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
7 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Restructures the Agent Skills documentation into two pages:
/agents/runtime/execution/agent-skills/— now a reference page covering the SDK-agnostic primitives (SkillRegistry, skill sources, script runner, parsers, types), the AI SDK tool integration (registry.tools()), and script execution. Adds a DIY vs managed skills comparison table and code examples for usingSkillRegistryinAIChatAgentand with the OpenAI SDK./agents/harnesses/think/skills/(new) — Think-specific configuration coveringgetSkills(),getSkillScriptRunner(), theagents:skillsVite plugin, R2 sources, custom sources, and how Think wires the registry into the turn loop with fingerprint caching and Session persistence.Updates Think index, configuration, and tools pages to link to the new Think-specific skills page.
Documentation checklist