From f5da9477ec8e3f2220a6c1b5026529862f08bff0 Mon Sep 17 00:00:00 2001 From: Davide Gallitelli Date: Mon, 13 Apr 2026 16:26:01 +0000 Subject: [PATCH 1/2] docs(skills): add URL loading documentation Document Skill.from_url() and HTTPS URL support in AgentSkills: - New "Loading skills from URLs" section with examples - Add from_url() to programmatic creation examples - Update configuration table to mention URL sources - Note about resource directory limitations for URL-loaded skills Companion to strands-agents/sdk-python#2091 Co-Authored-By: Claude Opus 4.6 (1M context) --- .../user-guide/concepts/plugins/skills.mdx | 50 ++++++++++++++++++- 1 file changed, 49 insertions(+), 1 deletion(-) diff --git a/src/content/docs/user-guide/concepts/plugins/skills.mdx b/src/content/docs/user-guide/concepts/plugins/skills.mdx index 759234689..0a032b016 100644 --- a/src/content/docs/user-guide/concepts/plugins/skills.mdx +++ b/src/content/docs/user-guide/concepts/plugins/skills.mdx @@ -164,6 +164,48 @@ skill = Skill.from_file("./skills/code-review") # Load all skills from a parent directory skills = Skill.from_directory("./skills/") + +# Load from a URL +skill = Skill.from_url("https://github.com/org/my-skill@v1.0.0") +``` + + + +```ts +// Skills are not yet available in TypeScript SDK +``` + + + +### Loading skills from URLs + +You can load skills directly from HTTPS URLs, which is useful for sharing skills across teams or referencing community skills hosted on GitHub without manual cloning. + + + + +```python +from strands import Agent, AgentSkills, Skill + +# Load from a raw SKILL.md URL +skill = Skill.from_url( + "https://raw.githubusercontent.com/org/repo/main/skills/my-skill/SKILL.md" +) + +# GitHub web URLs are auto-resolved to raw content +skill = Skill.from_url( + "https://github.com/org/repo/tree/main/skills/my-skill" +) + +# Pin a specific version with @ref +skill = Skill.from_url("https://github.com/org/my-skill@v1.0.0") + +# Use URLs directly in the plugin (mixed with local paths) +plugin = AgentSkills(skills=[ + "https://github.com/org/skill-repo/tree/main/skills/brainstorming", + "./local-skills/my-skill", +]) +agent = Agent(plugins=[plugin]) ``` @@ -174,6 +216,12 @@ skills = Skill.from_directory("./skills/") +GitHub web URLs (`github.com/owner/repo/tree/...`) are automatically converted to `raw.githubusercontent.com` URLs. For non-GitHub hosts, provide a direct link to the raw SKILL.md file. + +:::note[URL-loaded skills] +Skills loaded from URLs use `Skill.from_content()` internally, so they don't have a filesystem path. This means resource directories (`scripts/`, `references/`, `assets/`) are not available for URL-loaded skills. If your skill requires resource files, load it from the filesystem instead. +::: + ### Managing skills at runtime You can add, replace, or inspect skills after the plugin is created. Changes take effect on the next agent invocation because the plugin refreshes the system prompt XML before each call. @@ -278,7 +326,7 @@ The `AgentSkills` constructor accepts the following parameters. | Parameter | Type | Default | Description | |-----------|------|---------|-------------| -| `skills` | `SkillSources` | Required | One or more skill sources (paths, `Skill` instances, or a mix). | +| `skills` | `SkillSources` | Required | One or more skill sources (paths, `https://` URLs, `Skill` instances, or a mix). | | `state_key` | `str` | `"agent_skills"` | Key for storing plugin state in `agent.state`. | | `max_resource_files` | `int` | `20` | Maximum number of resource files listed in skill activation responses. | | `strict` | `bool` | `False` | If `True`, raise exceptions on validation issues instead of logging warnings. | From a9ebc73c477e32e351aca8aad52c3385e200fe3d Mon Sep 17 00:00:00 2001 From: Davide Gallitelli Date: Mon, 13 Apr 2026 16:31:52 +0000 Subject: [PATCH 2/2] docs(skills): remove GitHub URL auto-resolution references Update examples to use raw.githubusercontent.com URLs directly, matching the simplified SDK implementation (no URL resolution). Co-Authored-By: Claude Opus 4.6 (1M context) --- .../user-guide/concepts/plugins/skills.mdx | 20 +++++++------------ 1 file changed, 7 insertions(+), 13 deletions(-) diff --git a/src/content/docs/user-guide/concepts/plugins/skills.mdx b/src/content/docs/user-guide/concepts/plugins/skills.mdx index 0a032b016..c9f19fe58 100644 --- a/src/content/docs/user-guide/concepts/plugins/skills.mdx +++ b/src/content/docs/user-guide/concepts/plugins/skills.mdx @@ -165,8 +165,10 @@ skill = Skill.from_file("./skills/code-review") # Load all skills from a parent directory skills = Skill.from_directory("./skills/") -# Load from a URL -skill = Skill.from_url("https://github.com/org/my-skill@v1.0.0") +# Load from a URL (must point to raw SKILL.md content) +skill = Skill.from_url( + "https://raw.githubusercontent.com/org/repo/main/SKILL.md" +) ``` @@ -179,7 +181,7 @@ skill = Skill.from_url("https://github.com/org/my-skill@v1.0.0") ### Loading skills from URLs -You can load skills directly from HTTPS URLs, which is useful for sharing skills across teams or referencing community skills hosted on GitHub without manual cloning. +You can load skills directly from HTTPS URLs, which is useful for sharing skills across teams or referencing community skills without manual cloning. The URL must point directly to the raw SKILL.md content. @@ -192,17 +194,9 @@ skill = Skill.from_url( "https://raw.githubusercontent.com/org/repo/main/skills/my-skill/SKILL.md" ) -# GitHub web URLs are auto-resolved to raw content -skill = Skill.from_url( - "https://github.com/org/repo/tree/main/skills/my-skill" -) - -# Pin a specific version with @ref -skill = Skill.from_url("https://github.com/org/my-skill@v1.0.0") - # Use URLs directly in the plugin (mixed with local paths) plugin = AgentSkills(skills=[ - "https://github.com/org/skill-repo/tree/main/skills/brainstorming", + "https://raw.githubusercontent.com/org/repo/main/skills/brainstorming/SKILL.md", "./local-skills/my-skill", ]) agent = Agent(plugins=[plugin]) @@ -216,7 +210,7 @@ agent = Agent(plugins=[plugin]) -GitHub web URLs (`github.com/owner/repo/tree/...`) are automatically converted to `raw.githubusercontent.com` URLs. For non-GitHub hosts, provide a direct link to the raw SKILL.md file. +For GitHub-hosted skills, use `raw.githubusercontent.com` URLs to access the raw file content. For example, `https://github.com/org/repo/blob/main/SKILL.md` becomes `https://raw.githubusercontent.com/org/repo/main/SKILL.md`. :::note[URL-loaded skills] Skills loaded from URLs use `Skill.from_content()` internally, so they don't have a filesystem path. This means resource directories (`scripts/`, `references/`, `assets/`) are not available for URL-loaded skills. If your skill requires resource files, load it from the filesystem instead.