feat(skills): add agent skills as a plugin by mkmeral · Pull Request #1755 · strands-agents/sdk-python

mkmeral · 2026-02-23T22:06:04Z

Motivation

This PR adds SkillsPlugin, a first-class plugin that brings Agent Skills support to Strands. It follows the spec's progressive disclosure model: lightweight metadata (name + description) is injected into the system prompt at startup, and full instructions are loaded on-demand when the agent activates a skill via a tool call. This keeps context usage low while giving agents access to rich, task-specific instructions when needed.

Public API Changes

New SkillsPlugin class and Skill dataclass, both exported from the top-level strands package:

from strands import Agent
from strands.plugins.skills import SkillsPlugin, Skill

# Load skills from filesystem (individual dirs or parent dirs)
plugin = SkillsPlugin(skills=["./skills/pdf-processing", "./skills/"])

# Or provide Skill instances directly
skill = Skill(name="my-skill", description="A custom skill", instructions="Do the thing")
plugin = SkillsPlugin(skills=[skill])

agent = Agent(plugins=[plugin])

The plugin registers a skills tool that the agent calls to activate a skill by name. When activated, the tool returns the full instructions along with metadata (allowed tools, compatibility, location) and a listing of available resource files (scripts/, references/, assets/) for filesystem-based skills.

Skills can be managed at runtime via a symmetric property and a resolution method:

# Direct replacement with Skill instances
plugin.available_skills = [skill_a, skill_b]

# Load and append from filesystem paths (resolves paths, Skill instances, or parent dirs)
plugin.load_skills(["./new-skills/", another_skill])

Skill metadata is injected into the system prompt as XML before each invocation, with special characters escaped:

<available_skills>
<skill>
<name>pdf-processing</name>
<description>Extract text and tables from PDF files.</description>
<location>/path/to/pdf-processing/SKILL.md</location>
</skill>
</available_skills>

The active skill selection is persisted to agent.state for session recovery.

Use Cases

Skill libraries: Point the plugin at a directory of skills and let the agent pick the right one based on the user's request
Dynamic specialization: Swap agent behavior at runtime without rebuilding prompts or agents
Portable skills: Share skill directories across teams and agents using the Agent Skills standard format

Resolves: #1181

Documentation PR

TBD

Type of Change

New feature

Testing

Manually tested using jupyter notebook and set of skills from anthropic/skills repository
100 unit tests covering the plugin, tool, XML generation/escaping, response formatting, resource listing, session persistence, and skill resolution
2 integration tests against a real Bedrock model: model-driven skill activation with codeword verification, and direct tool invocation with state persistence checks
All existing tests (2145 total) continue to pass
I ran hatch run prepare

Checklist

I have read the CONTRIBUTING document
I have added any necessary tests that prove my fix is effective or my feature works
I have updated the documentation accordingly
I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
My changes generate no new warnings
Any dependent changes have been merged and published

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

BREAKING CHANGE: Plugin is now an abstract base class instead of a Protocol. Plugins must explicitly inherit from Plugin and implement the abstract name property and init_plugin method. - Convert Plugin from @runtime_checkable Protocol to ABC - Make name an abstract property - Make init_plugin an abstract method - Update all tests to use inheritance - Maintain support for both sync and async init_plugin - All tests pass (1985 passed) 🤖 Assisted by the code-assist SOP

Implement the SkillsPlugin that adds AgentSkills.io skill support to the Strands Agents SDK. The plugin enables progressive disclosure of skill instructions: metadata is injected into the system prompt upfront, and full instructions are loaded on demand via a tool. Key components: - Skill dataclass with from_path classmethod for loading from SKILL.md - Loader module for discovering, parsing, and validating skills - SkillsPlugin extending the Plugin ABC with: - skills tool (activate/deactivate actions) - BeforeInvocationEvent hook for system prompt injection - AfterInvocationEvent hook for prompt restoration - Single active skill management - Dynamic skill management via property setter - Session persistence via agent.state Files added: - src/strands/plugins/skills/__init__.py - src/strands/plugins/skills/skill.py - src/strands/plugins/skills/loader.py - src/strands/plugins/skills/skills_plugin.py - tests/strands/plugins/skills/ (90 tests) Files modified: - src/strands/plugins/__init__.py (added SkillsPlugin export) - src/strands/__init__.py (added Skill to top-level exports)

@hook

- Create @hook decorator for declarative hook registration in plugins - Convert Plugin from Protocol to base class (breaking change) - Add auto-discovery of @hook and @tool decorated methods in Plugin.__init__() - Add auto-registration of hooks and tools in Plugin.init_plugin() - Support union types for multiple event types (e.g., BeforeModelCallEvent | AfterModelCallEvent) - Export hook from strands.plugins and strands namespaces - Update existing tests to use inheritance-based approach - Add comprehensive test coverage for new functionality BREAKING CHANGE: Plugin is now a base class instead of a Protocol. Existing plugins must inherit from Plugin instead of just implementing the protocol.

- Simplify skills tool to single activate action (remove deactivate/action param) - Capture original system prompt once instead of save/restore pattern - Remove AfterInvocationEvent hook (no longer needed) - Replace optional pyyaml with required dependency - Remove _parse_yaml_simple fallback parser - Export Skill and SkillsPlugin from strands top-level

@hook

Replace manual hook registration and standalone tool factory with declarative @hook and @tool decorators on SkillsPlugin methods. - Remove _make_skills_tool() standalone function - Convert skills() to @tool decorated instance method - Convert _on_before_invocation() to @hook decorated method - Remove register_hooks() (old HookProvider pattern) - Rename skills property to available_skills (avoids collision) - Delegate hook/tool registration to super().init_plugin() - Update tests to match new API surface

This reverts commit 29f9bf4.

codecov · 2026-02-23T23:21:11Z

Codecov Report

❌ Patch coverage is 93.54839% with 18 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/strands/plugins/skills/skills_plugin.py	89.75%	10 Missing and 7 partials ⚠️
src/strands/plugins/skills/loader.py	98.92%	0 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

github-actions · 2026-03-03T15:37:39Z

Assessment: Comment

This is a well-structured implementation of the AgentSkills.io integration. The code follows repository patterns, has comprehensive test coverage (56 unit + 2 integration tests), and provides a clean progressive disclosure model.

Review Categories

API Design: Consider adding needs-api-review label since this introduces new public classes (Skill, SkillsPlugin) exported from the top-level strands package. The API documentation in the PR description is thorough.
Security: XML generation should escape special characters to prevent injection/malformed output.
Type Safety: The metadata field typing may be overly restrictive for YAML frontmatter values.
Naming: Tool name skills could be more descriptive (e.g., activate_skill).

Nice progressive disclosure pattern and clean integration with the existing plugin system! 🎯

- Escape XML special characters in skill names/descriptions using xml.sax.saxutils.escape to prevent injection/malformed output - Change Skill.metadata type from dict[str, str] to dict[str, Any] to preserve non-string YAML frontmatter values - Make available_skills property setter symmetric (list[Skill] in, list[Skill] out) and add load_skills() method for path resolution - Include available skills list in empty skill_name error message for consistency with the 'not found' error

github-actions · 2026-03-03T16:23:05Z

Follow-up Review: Changes Addressed ✅

Thank you for addressing the review feedback! The new commit looks good:

✅ XML special characters are now properly escaped using xml.sax.saxutils.escape
✅ Skill.metadata now uses dict[str, Any] to preserve YAML frontmatter values
✅ available_skills property is now symmetric (list[Skill] in/out) with a separate load_skills() method for path resolution
✅ Error messages now consistently include available skills
✅ New test added for XML escaping (test_escapes_xml_special_characters)

Minor suggestion (optional)

Consider adding tests for the new load_skills() method on the plugin class to ensure it properly merges skills and handles duplicates:

def test_load_skills_merges_with_existing(self, tmp_path):
    """Test that load_skills merges with existing skills."""
    plugin = SkillsPlugin(skills=[_make_skill(name="existing-skill")])
    _make_skill_dir(tmp_path, "new-skill")
    
    plugin.load_skills([tmp_path / "new-skill"])
    
    assert len(plugin.available_skills) == 2
    names = {s.name for s in plugin.available_skills}
    assert names == {"existing-skill", "new-skill"}

Note: This PR introduces new public classes (Skill, SkillsPlugin) exported from the top-level strands package. Consider adding the needs-api-review label per the API bar raising process.

agent-of-mkmeral · 2026-03-04T02:01:47Z

During adversarial testing, I found one edge case that was missed:

Finding: <location> element not XML-escaped in skills_plugin.py

What's the issue?

In skills_plugin.py, the _generate_skills_xml method escapes name and description but not the path:

# Lines 276-280 in skills_plugin.py
lines.append(f"<name>{escape(skill.name)}</name>")      # ✅ escaped
lines.append(f"<description>{escape(skill.description)}</description>")  # ✅ escaped
if skill.path is not None:
    lines.append(f"<location>{skill.path / 'SKILL.md'}</location>")  # ❌ NOT escaped!

Why does it matter?

If a skill directory path contains <, >, or & characters, the generated XML becomes malformed and cannot be parsed.

Reproduction

from pathlib import Path
import xml.etree.ElementTree as ET

# Simulate path with special chars
path = Path("/tmp/skill<dir>&test")
xml = f"<location>{path / 'SKILL.md'}</location>"

ET.fromstring(xml)  # Raises xml.etree.ElementTree.ParseError

Suggested Fix

- lines.append(f"<location>{skill.path / 'SKILL.md'}</location>")
+ lines.append(f"<location>{escape(str(skill.path / 'SKILL.md'))}</location>")

Severity: Medium - While filesystem paths with <, >, & are rare, the inconsistency with the existing escaping pattern for name and description is worth fixing for robustness.

src/strands/plugins/skills/skill.py

src/strands/plugins/skills/skills_plugin.py

Unshure · 2026-03-04T15:30:09Z

src/strands/plugins/skills/skills_plugin.py

+    @property
+    def name(self) -> str:
+        """A stable string identifier for the plugin."""
+        return "skills"


Just curious here, but why @Property over just name = "skills". Its fewer lines of code, and conveys the same information.

I think this is python related, from my agent:

The Plugin base class defines name as an @abstractmethod property, so subclasses need to implement it as a property

I tested this locally and it worked:

name = "skills"

Can you make the update?

src/strands/plugins/skills/skills_plugin.py

Unshure · 2026-03-04T15:35:39Z

src/strands/plugins/skills/skills_plugin.py

+        """
+        return list(self._skills.values())
+
+    @available_skills.setter


unresolving to ask: Why not have a get_available_skills and set_available_skills? Its a bit more obvious that there is more going on under the hood when you use a method rather than a property

src/strands/plugins/skills/skills_plugin.py

tests/strands/telemetry/test_tracer.py

src/strands/plugins/skills/loader.py

sanjolia · 2026-03-04T23:36:35Z

src/strands/plugins/skills/skills_plugin.py

+        logger.debug("skill_count=<%d> | skills plugin initialized", len(self._skills))
+
+    @tool(context=True)
+    def skills(self, skill_name: str, tool_context: ToolContext) -> str:  # noqa: D417


This single active-skill constraint is quite limiting, and contradicts one of the key-benefits of agent-skills from Claude, i.e. capability composition by combining multiple skills for complex workflows. https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview#why-use-skills.

With this implementation, activating multiple skills would require multiple sequential round-trips between LLM and tool-calls? That'd impact the agent's E2E response latency.

Unshure · 2026-03-05T18:13:27Z

src/strands/plugins/skills/skills_plugin.py

+_DEFAULT_MAX_RESOURCE_FILES = 20
+
+
+class SkillsPlugin(Plugin):


from strands.plugins import SkillsPlugin agent = Agent(plugins=[SkillsPlugin(".")])

This is my minimal code example for skills. Two notes:

Can we rename SkillsPlugin to Skills, and maybe rename the Skill dataclass?

Maybe SkillsPlugin -> Skills, Skill -> AgentSkill?

Can you update skills to take in a single string, path, or skill, not just a list?

Unshure · 2026-03-05T18:16:27Z

src/strands/plugins/skills/skills_plugin.py

+
+    def __init__(
+        self,
+        skills: list[str | Path | Skill],


Had an odd interaction when using an agent with no skills:

from strands import Agent from strands.plugins import SkillsPlugin agent = Agent(plugins=[SkillsPlugin(".")]) while True: agent(input("\nInput: "))

Interaction:

Input: Hello Hello! How can I help you today? I have access to various skills that I can activate to assist you with different tasks. Is there something specific you'd like to work on or learn about? Input: can you list the skills you have access to? I don't have a direct way to list all available skills, but I can activate specific skills by name using the skills tool. The skills would typically be listed in my system prompt under an "available_skills" section, but I don't currently see that information in my prompt. If you have a particular task in mind or know the name of a skill you'd like me to use, I can try to activate it for you. Alternatively, you could let me know what you're trying to accomplish, and I can suggest whether there might be a relevant skill available. What would you like help with today?

Should we raise an error if no skills are available? Should we inform the agent that no skills were loaded? Or should we not inject skill information if there are no skills available?

Unshure · 2026-03-05T18:21:37Z

src/strands/plugins/skills/skills_plugin.py

+        if skill.path is not None:
+            resources = self._list_skill_resources(skill.path)
+            if resources:
+                parts.append("\nAvailable resources:\n" + "\n".join(f"  {r}" for r in resources))


If the skill result includes resources, can the agent query them? If not, should we even include this if the agent cant do anything with them?

Maybe if a skill has resources, and no way to read them, we log a warning and dont include them?

Unshure · 2026-03-05T18:24:41Z

src/strands/plugins/skills/skills_plugin.py

+        if skill.allowed_tools:
+            metadata_lines.append(f"Allowed tools: {', '.join(skill.allowed_tools)}")


How is an agent intended to use this information? Should we even include it until we understand how it should be used?

For example, if this isnt the right way to expose this information, and we are instead just supposed to attach these tools, removing this information would be a breaking change.

Just general feedback: I think we should be minimal in what information we provide to the Agent until we have a clear idea on how they will integrate with strands.

With that in mind, should we release this as experimental?

Unshure · 2026-03-05T18:33:34Z

src/strands/plugins/skills/loader.py

+    return skill
+
+
+def load_skills(skills_dir: str | Path) -> list[Skill]:


Should we consider lenient validation as a follow-up? https://agentskills.io/client-implementation/adding-skills-support#lenient-validation

Unshure · 2026-03-05T18:42:48Z

src/strands/plugins/skills/skills_plugin.py

+
+        skills_xml = self._generate_skills_xml()
+        injection = f"\n\n{skills_xml}"
+        new_prompt = f"{current_prompt}{injection}" if current_prompt else skills_xml


The docs call out system prompt and tools as two different approaches to loading skills. If we want to support loading multiple skills, just returning it in the tool result will probably be easier: https://agentskills.io/client-implementation/adding-skills-support#where-to-place-the-catalog

Then we dont need to maintain state too

Unshure and others added 16 commits February 20, 2026 11:12

Add missing docstring updated

6669482

Merge branch 'main' into feat/skills-plugin

17ecfbd

Have decorator not wrap funciton, but just attach hook events

f2f74e4

Update steering to use hook decorator

8fb7244

Update typing

2e8a268

fix: add skills to agents.md

6cf7bac

chore: merge plugin decorator support from agent-tasks/1739

63251d5

fix: use dict for skills for easy name based access

e075d86

feat(skills): add integ test

9252908

feat(skills): extend tool result

539eb47

fix: empty commit

29f9bf4

github-actions bot added the size/xl label Feb 23, 2026

mkmeral had a problem deploying to auto-approve February 23, 2026 22:06 — with GitHub Actions Failure

mkmeral requested a deployment to manual-approval February 23, 2026 22:06 — with GitHub Actions Waiting

mkmeral changed the title ~~feat(skills): Add agent skills as a plugin~~ feat(skills): add agent skills as a plugin Feb 23, 2026

Revert "fix: empty commit"

8023cce

This reverts commit 29f9bf4.

github-actions bot added size/xl and removed size/xl labels Feb 23, 2026

mkmeral had a problem deploying to auto-approve February 23, 2026 22:15 — with GitHub Actions Failure

mkmeral requested a deployment to manual-approval February 23, 2026 22:16 — with GitHub Actions Waiting

fix: improve skills plugin prompt injection and loader robustness

f769d5f

github-actions bot added size/xl and removed size/xl labels Feb 25, 2026

mkmeral requested a deployment to manual-approval February 25, 2026 15:24 — with GitHub Actions Waiting

github-actions bot removed the strands-running label Mar 3, 2026

github-actions bot added size/xl and removed size/xl labels Mar 3, 2026

mkmeral temporarily deployed to manual-approval March 3, 2026 16:18 — with GitHub Actions Inactive

mkmeral temporarily deployed to auto-approve March 3, 2026 16:18 — with GitHub Actions Inactive

github-actions bot added the strands-running label Mar 3, 2026

github-actions bot removed the strands-running label Mar 3, 2026

fix: add unit test for load skills

19f9383

github-actions bot added size/xl and removed size/xl labels Mar 3, 2026

mkmeral requested a deployment to manual-approval March 3, 2026 16:31 — with GitHub Actions Waiting

mkmeral had a problem deploying to auto-approve March 3, 2026 16:31 — with GitHub Actions Failure

mkmeral mentioned this pull request Mar 4, 2026

Adverserial testing agent-of-mkmeral/strands-coder#7

Open

Unshure reviewed Mar 4, 2026

View reviewed changes

refactor: make SkillsPlugin multi-agent safe with per-agent state

8f2f5a7

github-actions bot added size/xl and removed size/xl labels Mar 4, 2026

mkmeral requested a deployment to manual-approval March 4, 2026 18:19 — with GitHub Actions Waiting

mkmeral temporarily deployed to auto-approve March 4, 2026 18:19 — with GitHub Actions Inactive

chore: revert unrelated handler and tracer formatting changes

0acf968

mkmeral temporarily deployed to auto-approve March 4, 2026 18:44 — with GitHub Actions Inactive

github-actions bot removed the size/xl label Mar 4, 2026

mkmeral requested a deployment to manual-approval March 4, 2026 18:44 — with GitHub Actions Waiting

github-actions bot added the size/xl label Mar 4, 2026

sanjolia reviewed Mar 4, 2026

View reviewed changes

Unshure reviewed Mar 5, 2026

View reviewed changes

		if skill.allowed_tools:
		metadata_lines.append(f"Allowed tools: {', '.join(skill.allowed_tools)}")

		return skill


		def load_skills(skills_dir: str \| Path) -> list[Skill]:

Conversation

mkmeral commented Feb 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

Public API Changes

Use Cases

Documentation PR

Type of Change

Testing

Checklist

Uh oh!

codecov bot commented Feb 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

github-actions bot commented Mar 3, 2026

Uh oh!

github-actions bot commented Mar 3, 2026

Uh oh!

agent-of-mkmeral commented Mar 4, 2026

What's the issue?

Why does it matter?

Reproduction

Suggested Fix

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sanjolia Mar 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

mkmeral commented Feb 23, 2026 •

edited

Loading

codecov bot commented Feb 23, 2026 •

edited

Loading

sanjolia Mar 4, 2026 •

edited

Loading